sourcecode 5.9.22__tar.gz → 5.9.23__tar.gz

{sourcecode-5.9.22 → sourcecode-5.9.23}/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [5.9.23] — 2026-09-01
+
+*Regression hardening after the 5.9.22 audit and testing-repository battery.*
+
+### Fixed
+
+- `--compact` and `--agent` reserve envelope metadata before trimming, so their
+  published 30 KB and 40 KB stdout ceilings remain true after final rendering.
+- `--agent` now has a 1,536 MB default RSS ceiling, reports context construction
+  accurately in progress output, and rejects Java repositories above 10,000 files
+  with `AGENT_SCOPE_TOO_LARGE` before an unbounded deep analysis can be killed.
+- Agent mode no longer builds a module graph implicitly; callers can still request
+  it explicitly with `--graph-modules`.
+
+### Documentation
+
+- Added the Windows large-repository audit with measured P0/P1 regressions,
+  performance boundaries and explicit closure requirements.
+- Synchronized the defect ledger and README so silent-success, incomplete
+  coverage, compact-output, cache-growth and deep-agent memory risks are visible
+  rather than implied closed by smaller-repository measurements.
+
 ## [5.9.22] — 2026-08-31
 
 *Large-repository route projection performance.*

{sourcecode-5.9.22 → sourcecode-5.9.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.9.22
+Version: 5.9.23
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 Project-URL: Homepage, https://github.com/HarounDominique/sourcecode
 Project-URL: Repository, https://github.com/HarounDominique/sourcecode
@@ -59,7 +59,7 @@ Description-Content-Type: text/markdown
 > question. All analysis is local and deterministic; see [Privacy](#configuration--privacy)
 > before inspecting a repository whose telemetry policy you need to control.
 
-![Version](https://img.shields.io/badge/version-5.9.22-blue)
+![Version](https://img.shields.io/badge/version-5.9.23-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 Copyright (c) 2026 Dominique Haroun. All rights reserved. ASK Engine 5.7.0 and
@@ -191,10 +191,10 @@ must not be gated on this variable; their budget applicability remains visible i
 the [defect ledger](docs/DEFECT-LEDGER.md).
 
 **Memory is measurable and bounded.** Repository-scoped JSON answers publish
-`_meta.memory.peak_rss_mb` and the configured ceiling. For a supervised deep run,
-set `ASK_MAX_RSS_MB=<megabytes>`; if the process exceeds it, ASK refuses the
-answer with `MEMORY_TOO_LARGE`, including the observed peak and limit. Leave it
-unset, or set it to `0`, to disable the ceiling explicitly.
+`_meta.memory.peak_rss_mb` and the configured ceiling. `--agent` applies a
+1,536 MB ceiling by default; set `ASK_MAX_RSS_MB=<megabytes>` to override it or
+`ASK_MAX_RSS_MB=0` to disable it explicitly. If the process exceeds the ceiling,
+ASK refuses the answer with `MEMORY_TOO_LARGE`, including the observed peak and limit.
 
 **Current performance status.** Release 5.9.22 retains the shared Canonical IR
 path used by `validation` and now passes that same CIR into labelled `data-exposure`
@@ -212,6 +212,14 @@ exit 75 (`--allow-partial` accepts one deliberately). The long-run progress
 message names the phase it is in and whether that phase has changed, so a slow run
 is distinguishable from a blocked one.
 
+**External audit boundary (2026-09-01).** The latest Windows audit rates the
+large-repository experience at **6.6/10** and reports open P0/P1 issues: empty
+successful Markdown `audit-report`, silent `risk` termination, multi-gigabyte
+deep-agent RSS, incomplete parse/coverage disclosure and oversized compact
+surfaces. These findings are tracked in the [external audit](docs/AUDIT-2026-09-01-EXTERNAL-5.9.22.md)
+and [defect ledger](docs/DEFECT-LEDGER.md); they are not closed by the existing
+engineering-host measurements.
+
 The current external audit still records two open availability limits, and they
 are held open deliberately: `audit-report --format markdown` under contention, and
 the root compact flow under strict timeouts on very large monorepos. Neither

{sourcecode-5.9.22 → sourcecode-5.9.23}/README.md

@@ -10,7 +10,7 @@
 > question. All analysis is local and deterministic; see [Privacy](#configuration--privacy)
 > before inspecting a repository whose telemetry policy you need to control.
 
-![Version](https://img.shields.io/badge/version-5.9.22-blue)
+![Version](https://img.shields.io/badge/version-5.9.23-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 Copyright (c) 2026 Dominique Haroun. All rights reserved. ASK Engine 5.7.0 and
@@ -142,10 +142,10 @@ must not be gated on this variable; their budget applicability remains visible i
 the [defect ledger](docs/DEFECT-LEDGER.md).
 
 **Memory is measurable and bounded.** Repository-scoped JSON answers publish
-`_meta.memory.peak_rss_mb` and the configured ceiling. For a supervised deep run,
-set `ASK_MAX_RSS_MB=<megabytes>`; if the process exceeds it, ASK refuses the
-answer with `MEMORY_TOO_LARGE`, including the observed peak and limit. Leave it
-unset, or set it to `0`, to disable the ceiling explicitly.
+`_meta.memory.peak_rss_mb` and the configured ceiling. `--agent` applies a
+1,536 MB ceiling by default; set `ASK_MAX_RSS_MB=<megabytes>` to override it or
+`ASK_MAX_RSS_MB=0` to disable it explicitly. If the process exceeds the ceiling,
+ASK refuses the answer with `MEMORY_TOO_LARGE`, including the observed peak and limit.
 
 **Current performance status.** Release 5.9.22 retains the shared Canonical IR
 path used by `validation` and now passes that same CIR into labelled `data-exposure`
@@ -163,6 +163,14 @@ exit 75 (`--allow-partial` accepts one deliberately). The long-run progress
 message names the phase it is in and whether that phase has changed, so a slow run
 is distinguishable from a blocked one.
 
+**External audit boundary (2026-09-01).** The latest Windows audit rates the
+large-repository experience at **6.6/10** and reports open P0/P1 issues: empty
+successful Markdown `audit-report`, silent `risk` termination, multi-gigabyte
+deep-agent RSS, incomplete parse/coverage disclosure and oversized compact
+surfaces. These findings are tracked in the [external audit](docs/AUDIT-2026-09-01-EXTERNAL-5.9.22.md)
+and [defect ledger](docs/DEFECT-LEDGER.md); they are not closed by the existing
+engineering-host measurements.
+
 The current external audit still records two open availability limits, and they
 are held open deliberately: `audit-report --format markdown` under contention, and
 the root compact flow under strict timeouts on very large monorepos. Neither

sourcecode-5.9.23/docs/AUDIT-2026-09-01-EXTERNAL-5.9.22.md

@@ -0,0 +1,71 @@
+# External Audit — ASK Engine 5.9.22
+
+**Received:** 2026-09-01  
+**Audited build:** `5.9.22` (`64c8b3e429eadd7a12d34eb1e5eefa0c08e430e4`)  
+**Platform:** Windows 11, Python 3.10, Git Bash  
+**Corpus:** repositories under `laboratorioDePruebas/testing/`; the largest
+reported target contains 3,342 Java files.
+
+This document records external observations. An observation is not a closure:
+the defect ledger remains authoritative until a fix, all affected consumers and
+a regression assertion exist.
+
+## Executive Result
+
+The audit rates ASK Engine **6.6/10** on the large MSAS corpus and **7.5/10** on
+the smaller nine-axis assessment. The measurements agree on the main risk:
+source analysis is accurate and unusually explicit about uncertainty, but large
+repository execution and several output contracts are not yet reliable enough
+for interactive or unattended security use.
+
+Strengths confirmed: endpoint extraction, effective access resolution,
+determinism, structured input errors, cache warm-up and bounded CI-oriented
+flows. The principal gaps are silent success, incomplete parse disclosure,
+SQL-injection recall, memory, and inconsistent CLI contracts.
+
+## Priority Findings
+
+| ID | Priority | Status | Finding and closure requirement |
+|---|---|---|---|
+| `BUG-01` | P0 | Open | `audit-report --format markdown` reproduced with `rc=0` and empty stdout. Add a non-empty-answer invariant and full/partial renderer coverage. |
+| `BUG-02` | P0 | Open | Large `risk` ended `rc=127` with no output or structured error. Add fail-fast resource/process handling and durable partial checkpoints. |
+| `BUG-12` | P0 | Open | Deep `--agent` output construction reaches multi-gigabyte RSS before producing a small answer. Bound projection while building, not after materialization. |
+| `BUG-03` | P1 | Open | `content_id` changes between cold and warm because cache state is hashed into the answer. Separate execution metadata from answer identity. |
+| `BUG-04` | P1 | Open | `selftest` publishes `complete=true` with five error rows. Derive bounds from its actual result population. |
+| `BUG-04b` | P1 | Open | `selftest` uses a fixed 120-second deadline not covered by the documented analysis budget. Make it configurable or refuse unscoped large runs. |
+| `BUG-05` | P1 | Open | Overloaded endpoint handlers can receive the wrong declaration line. Resolve by mapping annotation or publish ambiguity. |
+| `BUG-06` | P1 | Open | The `repo-ir --budget-tokens 12000` help example is below the measured minimum view (~20,367 tokens) on the audited corpus. |
+| `BUG-07` | P1 | Open | `--compact` exceeds the published size expectation on `migrate-check` and `spring-audit`. Apply bounded projections with omission metadata. |
+| `BUG-08` | P1 | Open | Root help claims universal `--path`, `--repo` and `--dir` aliases, but sampled commands reject them. Align implementation and help. |
+| `BUG-09` | P2 | Open | Related diff commands disagree on `--base`, `--base-ref`, `--since`, `--repo` and `--path`. Accept compatible aliases or publish one vocabulary. |
+| `BUG-10` | P1 | Open | Unsupported routing styles can produce `coverage.gaps=[]`. Publish detected-but-unmodeled routing gaps. |
+| `BUG-11` | P1 | Open | Default `pack assessment` can fail on a small Spring repository. Use a bounded default or explicit full mode. |
+| `BUG-13` | P1 | Open | Unscoped `selftest` starts over nested repositories after warning. Refuse and require an explicit repository path. |
+| `BUG-15` | P2 | Open | Non-terminal help output contains visible markup/control text. Strip markup when stdout is not a TTY. |
+| `BUG-16` | P1 | Open | Context-cache growth is not bounded or documented; about 1.5 GB was measured. Add a published budget, eviction policy and status. |
+| `BUG-19` | P2 | Open | Unknown-command errors use plain text instead of the JSON error envelope. Normalize command admission errors. |
+| `BUG-20` | P2 | Open | `--detach` can report the unresolved user path while writing to a resolved Windows path. Publish the actual absolute output path. |
+| `BUG-21` | P2 | Open | `--jobs 999` is silently clipped. Publish the effective limit or reject out-of-range values. |
+| `BUG-22` | P1 | Open | RSS ceilings are checked post-hoc; a 50 MB ceiling was reported only after ~768 MB. Add periodic in-flight sampling and orderly abort. |
+| `BUG-23` | P2 / coverage | Open | Micronaut is detected but unsupported and its controllers are not modeled as endpoints. Add a scoped coverage contract. |
+
+## Performance Evidence
+
+The audit measured `--agent` on ThingsBoard at **182.6 s / 2,088 MB RSS** and
+`spring-audit` at **164.2 s cold**. On the larger MSAS corpus it reports
+`ask . --agent` at **447 s**, `contract-diff` at **329 s**, `delta` at **187 s**,
+and `validation --compact` at **91 s**. Warm root compact analysis can be below
+one second; these are cold/deep-path costs.
+
+Until the P0/P1 rows close, do not market `risk`, full `audit-report` or full
+`--agent` as interactive guarantees for 3,000+ Java-file repositories. The
+target remains bounded interactive views below 20 s and peak RSS below 400 MB
+on the reference large-repository tier.
+
+## Required Closure Bar
+
+Each P0/P1 row requires a focused regression test, output/exit-code assertions,
+cold/warm/concurrent runs on the affected platform, and a ledger entry naming
+the fix commit and remaining verification boundary. Documentation alone never
+closes a defect.
+

{sourcecode-5.9.22 → sourcecode-5.9.23}/docs/DEFECT-LEDGER.md

@@ -14,6 +14,32 @@ Status values: `open` · `in-progress` · `closed <version>` · `by-design` (wit
 The facts these rows are keyed to are published: `ask schema facts-v1` prints the registry
 (authority, definition, consumers, parity test) that the release battery enforces.
 
+## Current Synchronization — External Audit `5.9.22` (2026-09-01)
+
+The external audit confirms strong precision, determinism and uncertainty
+disclosure, but opens a P0/P1 cluster around silent success, incomplete
+population disclosure, large-run memory and compact-output contracts. Full
+evidence: [`AUDIT-2026-09-01-EXTERNAL-5.9.22.md`](AUDIT-2026-09-01-EXTERNAL-5.9.22.md).
+
+| ID | Severity | Status | Evidence and required closure |
+|---|---:|---|---|
+| `BUG-01` | Critical maximum | **open, P0** | Full Markdown `audit-report` reproduced with `rc=0` and empty stdout. Add a global non-empty-answer invariant and renderer coverage. |
+| `BUG-02` | Critical maximum | **open, P0** | Large `risk` ended `rc=127` with no output or structured failure. Add fail-fast resource/process handling and durable partial checkpoints. |
+| `BUG-12` | Critical maximum | **open, P0** | Deep `--agent` output construction reaches multi-gigabyte RSS before a small answer. Bound projection while building. |
+| `BUG-03` | High | **open, P1** | `content_id` changes between cold and warm because cache state is hashed into identity. Separate execution metadata from answer identity. |
+| `BUG-04` | High | **open, P1** | `selftest` publishes `complete=true` with five error rows. Derive bounds from actual results. |
+| `BUG-05` | High | **open, P1** | Overloaded endpoint handlers can receive the wrong declaration line. Resolve by mapping annotation or publish ambiguity. |
+| `BUG-07` | High | **open, P1** | `--compact` remains oversized on `migrate-check` and `spring-audit`. Apply bounded projections with omission metadata. |
+| `BUG-10` | High | **open, P1** | Unsupported routing styles can produce empty coverage gaps. Publish detected-but-unmodeled routing gaps. |
+| `BUG-11` | High | **open, P1** | Default `pack assessment` can fail on a small Spring repository. Use a bounded default or explicit full mode. |
+| `BUG-13` | High | **open, P1** | Unscoped `selftest` starts over nested repositories after warning. Refuse and require an explicit path. |
+| `BUG-16` | High | **open, P1** | Context-cache growth has no published budget or eviction contract; about 1.5 GB was measured. |
+| `BUG-22` | High | **open, P1** | RSS ceilings are checked post-hoc. Add periodic sampling and orderly abort. |
+
+The remaining `BUG-04b`, `BUG-06`, `BUG-08`, `BUG-09`, `BUG-15`, `BUG-19`,
+`BUG-20`, `BUG-21` and `BUG-23` findings are open P2/coverage follow-ups in
+the audit document. None is closed by documentation alone.
+
 ## Current Synchronization — External Audit `AUD-621`
 
 **Release `5.9.19` remediation.** The stderr-decoding fix for `AUD-621-PACK-STDERR` remains in code, and the distinct `pack gate --since` crash found by the post-remediation re-audit is corrected with a Python 3.9–3.11-compatible tar extraction path. `AUD-621-R` has a second Windows barrier at process-pool construction, complementing the sequential fallback. The broader findings remain open until their required native Windows evidence is recorded; `AUD-621-CONTEXT` and `AUD-621-WIN-PROC` are unchanged.

{sourcecode-5.9.22 → sourcecode-5.9.23}/docs/PRODUCT_TIERS.md

@@ -59,7 +59,7 @@ single-repo, offline.**
 | **Modernization planning** | `ask modernize .` | Hotspots, callerless types (with `unknown` where a framework may dispatch), coupling tangles, refactor roadmap |
 | **Git-churn ranking** | `--rank-by git-churn` | File volatility via git history |
 | **No truncation limits** | `--full` | Full transactional boundaries, DTO mappers, large result sets |
-| **Spring semantic audit** | `ask spring-audit .` | TX-001..006 anomalies + SEC-001..009 security surface; JAVA/SPRING only |
+| **Spring semantic audit** | `ask spring-audit .` | TX-001..006 anomalies + SEC-001..010 security surface; JAVA/SPRING only |
 | **Impact chain + opt-in TX/SEC findings** | `ask impact-chain <symbol>` (`--with-findings` for audit findings) | Systemic blast radius with transaction boundary and security surfaces per hop |
 | **Event topology** | `ask impact-chain <event> --type events` | Publisher → event → consumer graph; AFTER_COMMIT/BEFORE_COMMIT TX phase |
 | RIS bootstrap context | `ask cold-start .` | Repository Intelligence Snapshot; instant return from persisted cache |

{sourcecode-5.9.22 → sourcecode-5.9.23}/docs/USER_GUIDE.md

@@ -382,6 +382,9 @@ Output: detected stacks, entry points, dependencies, transactional boundaries (S
 ### `ask --agent`
 
 More structured version of `--compact`. Designed for AI agent system prompt injection.
+It is bounded to 40 KB on stdout and admits repositories up to 10,000 Java files;
+larger repositories return `AGENT_SCOPE_TOO_LARGE` before expensive analysis. Use
+`--compact` or narrow the path in that case.
 
 ```bash
 ask /repo --agent --output context.json
@@ -528,7 +531,7 @@ disabled changes runtime behaviour nobody measured; a diff is how a person makes
 call with the evidence in front of them.
 
 **TX patterns (TX-001..TX-006):** proxy bypass, nested transactions, readOnly propagation, NOT_SUPPORTED in active TX, exception swallowing, self-invocation of a `@Transactional` sibling.
-**SEC patterns (SEC-001..SEC-009):** unsecured endpoints, CVE-2025-41248 `@PreAuthorize` inheritance bypass, `@Transactional` on controllers, passwords stored under a fast unsalted digest, CSRF disabled under session-bearing authentication, cookies created without the Secure attribute, credentials stored in a deployment descriptor, SQL built by MyBatis string interpolation, and anonymous request-chain exceptions. **DEAD-001** reports a security control that is present only in comments and therefore disabled.
+**SEC patterns (SEC-001..SEC-010):** unsecured endpoints, CVE-2025-41248 `@PreAuthorize` inheritance bypass, `@Transactional` on controllers, passwords stored under a fast unsalted digest, CSRF disabled under session-bearing authentication, cookies created without the Secure attribute, credentials stored in a deployment descriptor, SQL built by MyBatis string interpolation, anonymous request-chain exceptions, and HTTP input reaching a concatenated known query sink through bounded positional in-repository calls. **DEAD-001** reports a security control that is present only in comments and therefore disabled.
 **GATE patterns (GATE-001..GATE-004):** custom AOP/security-gate risks over the same custom-gate authority published in `security_posture`: proxy bypass (`private`/`final`/self-invocation), advice that appears to fail open, disabled or tautological annotation attributes, and fragile `args[0]`/reflection binding.
 
 Each finding includes `severity`, `confidence`, `symbol`, `source_file`, `evidence`, `explanation`, and `fix_hint`. JAVA/SPRING ONLY.
@@ -1812,10 +1815,10 @@ stops at 1 408 files inside the `SEC-004` group and ends at 5.1s.
 **Memory budget.** Repository-scoped JSON answers include `_meta.memory` with
 `unit: "MB"`, the observed `peak_rss_mb`, the `peak_rss_basis` it was sampled
 from, `configured_max_rss_mb`, and `ceiling_enforceable`. To bound long analyses
-on a CI or supervised runner, set `ASK_MAX_RSS_MB=<megabytes>`. Exceeding the
-ceiling produces exit code `1` and a structured `MEMORY_TOO_LARGE` error with the
-peak and configured limit; no partial answer is published. Unset the variable, or
-set it to `0`, to disable this ceiling.
+on a CI or supervised runner, set `ASK_MAX_RSS_MB=<megabytes>`. `--agent` uses
+1,536 MB when the variable is unset. Exceeding the ceiling produces exit code `1`
+and a structured `MEMORY_TOO_LARGE` error with the peak and configured limit; no
+partial answer is published. Set the variable to `0` to disable this ceiling.
 
 Where the platform exposes no footprint sample, `peak_rss_mb` is `null` and
 `peak_rss_basis` says why — never `0`, which would read as a measured floor. A

{sourcecode-5.9.22 → sourcecode-5.9.23}/pyproject.toml

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

{sourcecode-5.9.22 → sourcecode-5.9.23}/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__ = "5.9.22"
+__version__ = "5.9.23"

{sourcecode-5.9.22 → sourcecode-5.9.23}/src/sourcecode/answer_bounds.py

@@ -99,6 +99,16 @@ def _gaps(payload: "dict[str, Any]") -> "list[dict[str, Any]]":
             found.append({"field": "non_coverage", "what": _summarise(entry)})
     elif non_coverage:
         found.append({"field": "non_coverage", "what": _summarise(non_coverage)})
+    populations = [payload.get("population")]
+    metadata = payload.get("metadata")
+    if isinstance(metadata, dict):
+        populations.append(metadata.get("population"))
+    for population in populations:
+        if not isinstance(population, dict):
+            continue
+        for failure in _as_list(population.get("parse_failures")):
+            if failure:
+                found.append({"field": "population.parse_failures", "what": _summarise(failure)})
     for prefix, block in _blocks(payload):
         for field in _GAP_FIELDS:
             value = block.get(field)

{sourcecode-5.9.22 → sourcecode-5.9.23}/src/sourcecode/canonical_ir.py

@@ -594,6 +594,7 @@ def ir_dict_to_canonical(
         "edge_count": len(call_graph),
         "subsystems": ir.get("subsystems") or [],
         "analysis_gaps": ir.get("analysis_gaps") or [],
+        "population": ir.get("population") or {},
         "spring_events": ir.get("spring_events") or {},
         "score_basis": (ir.get("impact") or {}).get("score_basis", "none"),
         "reverse_graph_size": len(ir.get("reverse_graph") or {}),

{sourcecode-5.9.22 → sourcecode-5.9.23}/src/sourcecode/cli.py

@@ -513,6 +513,28 @@ _START_HERE: "tuple[tuple[str, str], ...]" = (
 )
 
 
+def _start_here_entries(root: "Optional[Path]") -> "tuple[tuple[str, str], ...]":
+    """Return pasteable first steps that the measured repository can accept."""
+    if root is None:
+        return _START_HERE
+    try:
+        from sourcecode.spring_profiles import profile_population
+
+        profiles = profile_population(root).names
+    except Exception:
+        # Help must remain available if a repository cannot be read.
+        return _START_HERE
+    if len(profiles) < 2:
+        # `posture --diff` rejects undeclared profile names. Do not publish an
+        # example that cannot run on this repository.
+        return tuple(entry for entry in _START_HERE if not entry[0].startswith("posture "))
+    diff = f"posture . --diff {profiles[0]}:{profiles[1]}"
+    return tuple(
+        (diff, answers) if invocation.startswith("posture ") else (invocation, answers)
+        for invocation, answers in _START_HERE
+    )
+
+
 #: Resolved bounding flags, by invocation. Deliberately **not** an `lru_cache`:
 #: only a resolution that found the command is stored. AUD-601-D01 — the front
 #: page is composed while this module is still being imported, so the first
@@ -637,6 +659,8 @@ def _start_here_block(scope: "Optional[Any]" = None) -> str:
         BUCKET_ORDER, BUCKET_TITLE, BUDGETED, DETACH, RUNS_NOW, UNKNOWN, plan,
     )
 
+    root = getattr(scope, "root", None) if scope is not None else None
+    entries = _start_here_entries(root)
     if scope is None or not scope.measured:
         # AUD-601-D01. The ceiling is a property of the **command**, not of the
         # repository, so the bounding flag must not depend on measuring one.
@@ -647,13 +671,13 @@ def _start_here_block(scope: "Optional[Any]" = None) -> str:
         # the generator covers them, and this rendering never called it.
         static = [
             (_bounded_invocation(invocation), answers)
-            for invocation, answers in _START_HERE
+            for invocation, answers in entries
         ]
         width = max([29] + [len(invocation) + 1 for invocation, _ in static])
         lines = ["[bold]Start here — Java/Spring analysis:[/bold]"]
         for invocation, answers in static:
             lines.append(f"  {invocation:<{width}}[dim]# {answers}[/dim]")
-        if any(bounded != raw for (bounded, _), (raw, _) in zip(static, _START_HERE)):
+        if any(bounded != raw for (bounded, _), (raw, _) in zip(static, entries)):
             lines.append(
                 "  [dim]Bounded for a first look: each line above carries the "
                 "flag its command declares against the output ceiling. Drop it, "
@@ -661,7 +685,7 @@ def _start_here_block(scope: "Optional[Any]" = None) -> str:
             )
         return "\n".join(lines)
 
-    answers = dict(_START_HERE)
+    answers = dict(entries)
     # AUD-596-X02: this block sold three commands under "Runs now" and two of
     # them exited 1 here, both with `OUTPUT_TOO_LARGE` — `posture . --diff
     # dev:prod` at ~71K estimated tokens over a 50K ceiling, and `endpoints .`
@@ -672,12 +696,12 @@ def _start_here_block(scope: "Optional[Any]" = None) -> str:
     # it from an error.
     bounded = {
         invocation: _bounded_invocation(invocation)
-        for invocation, _ in _START_HERE
+        for invocation, _ in entries
     }
     for invocation, bounded_form in bounded.items():
         if bounded_form != invocation:
             answers[bounded_form] = answers[invocation]
-    grouped = plan([bounded[invocation] for invocation, _ in _START_HERE], scope)
+    grouped = plan([bounded[invocation] for invocation, _ in entries], scope)
 
     # AUD-597-A01. The plan orders by *time* and the ceiling refuses by *size*,
     # so a command that is seconds away from an answer it cannot print is not a
@@ -729,7 +753,7 @@ def _start_here_block(scope: "Optional[Any]" = None) -> str:
                 "    [dim]…each of these answers into a file and survives the shell:"
                 " add --output <file> --detach[/dim]"
             )
-    if any(bounded[invocation] != invocation for invocation, _ in _START_HERE):
+    if any(bounded[invocation] != invocation for invocation, _ in entries):
         lines.append(
             "  [dim]Bounded for a first look: each line above carries the flag "
             "its command declares against the output ceiling. Drop it, or add "
@@ -888,12 +912,12 @@ scope matches; `ask cache model` says exactly what a warm buys per command.
   data-exposure .              [dim]# one semantic model is shared across declared label seeds[/dim]
   repo-ir . --since main --budget-tokens 12000 [dim]# bounded agent context[/dim]
   migrate-check . --format sarif -o migration.sarif [dim]# located migration findings[/dim]
-  [dim]The repository is a positional argument everywhere; --path, --repo and --dir
-  are accepted as aliases for it on any command that does not already declare them.[/dim]
+  [dim]Repository paths are normally positional. Commands that publish --path, --repo
+  or --dir accept that documented spelling; use each command's --help for its grammar.[/dim]
 
   ASK_MAX_ANALYSIS_SECONDS=N   [dim]# deadline for {_budget_tiers_phrase()}[/dim]
   [dim]Other commands do not consume this budget; use `--progress` or `--detach` where offered.[/dim]
-  ASK_MAX_RSS_MB=N             [dim]# peak resident-memory ceiling for costly analyses; 0 disables[/dim]
+  ASK_MAX_RSS_MB=N             [dim]# peak resident-memory ceiling; --agent defaults to 1536 MB, 0 disables[/dim]
   [dim]Repository JSON answers publish `_meta.memory.peak_rss_mb` with its basis; exceeding the ceiling
   returns MEMORY_TOO_LARGE, and a platform that exposes no sample returns MEMORY_CEILING_UNAVAILABLE
   rather than passing a ceiling nothing measured.[/dim]
@@ -1796,7 +1820,12 @@ def _apply_budget(
 
     to_file = output_path is not None
     return _trim(
-        data, budget_bytes, label=label, skip=to_file, warn_stderr=not to_file
+        data,
+        budget_bytes,
+        label=label,
+        skip=to_file,
+        warn_stderr=not to_file,
+        strict=(label in {"agent", "compact"}),
     )
 
 
@@ -3140,6 +3169,18 @@ def _emit_command_output(
     not about the encoding. A command that already serialized its own YAML passes
     the default and is untouched: the conversion only fires on a JSON object.
     """
+    # A completed analysis with no payload is never a successful answer.  The
+    # process-level guard also catches this for the production entry point, but
+    # rejecting it here protects every direct Typer invocation and prevents an
+    # empty file from being published as an artefact.
+    if not content.strip():
+        _emit_error_json(
+            EXECUTION_FAILED_CODE,
+            "The command finished without publishing an answer.",
+            command=_ANSWER_REQUIRED_BY or "unknown",
+            expected="a non-empty parseable answer or report",
+        )
+        raise typer.Exit(code=1)
     if stamp_envelope:
         content = _stamp_envelope(content)
     if fmt == "yaml":
@@ -4906,6 +4947,24 @@ DOCS_DEPTH_CHOICES = ["module", "symbols", "full"]
 _FREE_TIER_NODE_CAP: int = 50  # graph/semantic node cap — applies only to large repos on free tier
 _JAVA_MIN_SCAN_DEPTH: int = 12  # Maven src/main/java/<pkg>/<module>/File depth floor
 _LARGE_REPO_ADVISORY_FILES: int = 3000  # cold-scan advisory threshold (files); honest expectation-setting, not a speed claim
+_AGENT_JAVA_FILE_CAP: int = 10_000
+
+
+def _agent_scope_error(root: Path) -> "Optional[dict[str, Any]]":
+    """Refuse an agent run that cannot stay inside its memory contract."""
+    try:
+        java_files = sum(1 for _ in root.rglob("*.java"))
+    except OSError:
+        return None
+    if java_files <= _AGENT_JAVA_FILE_CAP:
+        return None
+    return {
+        "code": "AGENT_SCOPE_TOO_LARGE",
+        "message": f"--agent is limited to {_AGENT_JAVA_FILE_CAP:,} Java files by default; this repository has {java_files:,}.",
+        "hint": "Use --compact for the bounded summary, or narrow the repository path.",
+        "java_files": java_files,
+        "max_java_files": _AGENT_JAVA_FILE_CAP,
+    }
 
 #: What one Java file costs in serialized `repo-ir` output, measured across five
 #: repositories (C3-18): spring-petclinic 30 files/318 KB (10.8 KB/file),
@@ -5769,7 +5828,14 @@ def main(
         code_notes = True
         no_tree = True  # agents never need the raw file tree
         architecture = True  # agents need full architectural signal (M4)
-        graph_modules = True  # IC-003: import graph needed for architecture confidence
+        # Module graphs are quadratic on large import populations and are not
+        # required by agent_view. Keep them opt-in via --graph-modules.
+        _agent_error = _agent_scope_error(target)
+        if _agent_error is not None:
+            _emit_error_json(
+                _agent_error.pop("code"), _agent_error.pop("message"), **_agent_error
+            )
+            raise typer.Exit(code=2)
 
     # --compact implicitly enables lightweight analysis passes so that
     # dependency_summary, env_summary and code_notes_summary are never null.
@@ -6351,6 +6417,7 @@ def main(
         """Close a phase and stop the run if the operator's budget is spent."""
         _root_run.completed.append(phase)
         if not _root_run.exhausted():
+            _root_memory_seam()
             return
         _progress.stop()
         _block = _root_run.status(_WHY_BUDGET)
@@ -6362,6 +6429,26 @@ def main(
         _emit_command_output(_serialize_dict(_block, format), output, copy)
         raise typer.Exit(code=_exit)
 
+    def _root_memory_seam() -> None:
+        """Enforce the agent's protective RSS ceiling at every root boundary."""
+        if not agent:
+            return
+        from sourcecode import resource_budget
+
+        memory_error = resource_budget.exceeded(
+            "ask --agent",
+            default_ceiling_mb=resource_budget.DEFAULT_AGENT_RSS_CEILING_MB,
+        )
+        if memory_error is None:
+            return
+        _progress.stop()
+        _emit_error_json(
+            memory_error.pop("code"),
+            memory_error.pop("message"),
+            **memory_error,
+        )
+        raise typer.Exit(code=1)
+
     _perf_discovery = perf.start()
     scanner = AdaptiveScanner(target, topology=_topology, base_depth=effective_depth,
                                extra_excludes=_extra_excludes)
@@ -7099,7 +7186,7 @@ def main(
     _root_timing.setdefault("ris_ms", 0.0)
     _root_timing.setdefault("snapshot_ms", 0.0)
     # 4. Serialize
-    _progress.update("serializing output")
+    _progress.update("building bounded agent context" if agent else "serializing output")
     _perf_serialize = perf.start()
     if _is_contract_mode and not agent:
         from sourcecode.serializer import contract_view as _contract_view
@@ -7156,6 +7243,7 @@ def main(
         content = _serialize_dict(data, format)
 
     perf.stop("serialize", _perf_serialize)
+    _root_seam("serialize")
     perf.flush_recorder()
 
     # 5. Write output (CLI-04)

{sourcecode-5.9.22 → sourcecode-5.9.23}/src/sourcecode/migrate_check.py

@@ -2673,6 +2673,20 @@ class MigrationReport:
             for _col in ("evidence", "target_lts_blockers"):
                 _cap_into(_l, _col, top_n)
             compact["java_lts_inventory"] = _l
+        inventory = full.get("jvm_inventory")
+        if isinstance(inventory, dict) and isinstance(inventory.get("frameworks"), dict):
+            _inventory = dict(inventory)
+            _frameworks: dict[str, dict] = {}
+            for _name, _framework in inventory["frameworks"].items():
+                if not isinstance(_framework, dict):
+                    _frameworks[_name] = _framework
+                    continue
+                _bounded = dict(_framework)
+                for _collection in ("declared", "observed"):
+                    _cap_into(_bounded, _collection, top_n)
+                _frameworks[_name] = _bounded
+            _inventory["frameworks"] = _frameworks
+            compact["jvm_inventory"] = _inventory
         return compact
 
     def to_text(self, min_severity: str = "low") -> str:

{sourcecode-5.9.22 → sourcecode-5.9.23}/src/sourcecode/non_coverage.py

@@ -487,6 +487,7 @@ _STACK_INDEPENDENT_AXES: "tuple[str, ...]" = (
 def stack_fit(
     spring_detected: bool,
     security_frameworks: "tuple[str, ...] | list[str]" = (),
+    spring_footprint: "Optional[dict[str, int]]" = None,
 ) -> dict:
     """Whether this product's Spring-shaped axes model the repository. (CL-19)
 
@@ -553,6 +554,22 @@ def stack_fit(
                 "Spring Security result must not be read as public access."
             ),
         }
+    footprint = spring_footprint or {}
+    beans = int(footprint.get("spring_beans") or 0)
+    java_files = int(footprint.get("java_files") or 0)
+    if spring_detected and java_files and beans / java_files < 0.1:
+        return {
+            "schema_version": STACK_FIT_SCHEMA,
+            "spring_detected": True,
+            "fit": "partial",
+            "spring_footprint": {"spring_beans": beans, "java_files": java_files},
+            "statement": (
+                "Spring is present but marginal in this scope, so Spring-shaped axes "
+                "model only the detected Spring population. Do not read their absence "
+                "of findings as coverage of the remaining repository."
+            ),
+            "how_to_read": "Use Spring results for the detected Spring population only.",
+        }
     if spring_detected:
         return {
             "schema_version": STACK_FIT_SCHEMA,