sourcecode 5.9.19__py3-none-any.whl → 5.9.23__py3-none-any.whl

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.19"
+__version__ = "5.9.23"

sourcecode/_build_commit.py

@@ -1,5 +1,5 @@
 """Generated at build time by hatch_build.py. Do not edit (AUD-592-D04)."""
 
-BUILD_COMMIT = 'a22805b99d15c1a8046a1d48314986d67f132aa8'
+BUILD_COMMIT = '75c2f78dd8e2c7945e8a034f4f3c4fc8f9c40fc8'
 CLOSURE_PROVENANCE = {'AUD-611-B05': {'commit': '', 'status': 'uncited'}, 'AUD-611-B06': {'commit': '', 'status': 'uncited'}, 'AUD-611-B07': {'commit': '', 'status': 'uncited'}, 'AUD-611-B08': {'commit': '', 'status': 'uncited'}, 'AUD-611-B09': {'commit': '', 'status': 'uncited'}, 'AUD-611-B10': {'commit': '', 'status': 'uncited'}, 'AUD-611-B11': {'commit': '', 'status': 'uncited'}, 'AUD-612-07': {'commit': '', 'status': 'uncited'}, 'AUD-612-09': {'commit': '', 'status': 'uncited'}, 'AUD-612-14': {'commit': '', 'status': 'uncited'}, 'AUD-612-B03': {'commit': '', 'status': 'uncited'}, 'AUD-612-B07': {'commit': '', 'status': 'uncited'}, 'AUD-612-B13': {'commit': '', 'status': 'uncited'}, 'AUD-612-E': {'commit': '', 'status': 'uncited'}, 'AUD-612-G': {'commit': '', 'status': 'uncited'}, 'AUD-612-I': {'commit': '', 'status': 'uncited'}, 'AUD-612-K': {'commit': '', 'status': 'uncited'}, 'AUD-612-M': {'commit': '', 'status': 'uncited'}, 'AUD-612-R': {'commit': '', 'status': 'uncited'}, 'AUD-613-ROOT': {'commit': '', 'status': 'uncited'}, 'AUD-614-07': {'commit': '', 'status': 'uncited'}, 'AUD-614-E': {'commit': '', 'status': 'uncited'}, 'AUD-614-F': {'commit': '', 'status': 'uncited'}, 'AUD-614-G': {'commit': '', 'status': 'uncited'}, 'AUD-614-I': {'commit': '', 'status': 'uncited'}, 'AUD-614-INTENT-TIE': {'commit': '', 'status': 'uncited'}, 'AUD-614-JUNIT4': {'commit': '', 'status': 'uncited'}, 'AUD-614-RISK-L0': {'commit': '', 'status': 'uncited'}, 'AUD-614-SELFTEST-TIMEOUT': {'commit': '', 'status': 'uncited'}, 'AUD-615-07': {'commit': '', 'status': 'uncited'}, 'AUD-615-COLD-COMPACT': {'commit': '', 'status': 'uncited'}, 'AUD-615-DRIFT': {'commit': '', 'status': 'uncited'}, 'AUD-615-E': {'commit': '', 'status': 'uncited'}, 'AUD-615-F': {'commit': '', 'status': 'uncited'}, 'AUD-615-INTENT-TIE': {'commit': '', 'status': 'uncited'}, 'AUD-615-JUNIT4': {'commit': '', 'status': 'uncited'}, 'AUD-615-RISK-L0': {'commit': '', 'status': 'uncited'}, 'AUD-615-SELFTEST-TIMEOUT': {'commit': '', 'status': 'uncited'}, 'AUD-616-E-PROV': {'commit': '', 'status': 'uncited'}, 'AUD-616-F, -RISK-L0, -SELFTEST-TIMEOUT, -INTENT-TIE, -DRIFT, -COLD-COMPACT, -E, -07': {'commit': '', 'status': 'uncited'}, 'AUD-616-INTENT-TIE-COV': {'commit': '', 'status': 'uncited'}, 'AUD-616-JUNIT4-SELF': {'commit': '', 'status': 'uncited'}, 'AUD-616-KOTLIN': {'commit': '', 'status': 'uncited'}, 'AUD-616-O': {'commit': '', 'status': 'uncited'}, 'AUD-616-P': {'commit': '', 'status': 'uncited'}, 'Window': {'commit': '', 'status': 'uncited'}, '`ASK-FIELD-01`': {'commit': '829f9fa', 'status': 'present'}, '`ASK-FIELD-02`': {'commit': '6a659fa', 'status': 'present'}, '`ASK-FIELD-03`': {'commit': '55b0d51', 'status': 'present'}, '`AUD-588-F05`': {'commit': '470e4a4', 'status': 'present'}, '`AUD-590-B01` / `B-01`, `F-01`': {'commit': '', 'status': 'uncited'}, '`AUD-590-B02` / `B-02`, `F-02`': {'commit': '', 'status': 'uncited'}, '`AUD-590-B03` / `B-03`, `F-03`': {'commit': '', 'status': 'uncited'}, '`AUD-590-B04` / `B-04`, `F-04`': {'commit': '', 'status': 'uncited'}, '`AUD-590-R01` / `R-01`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A01` / `A-1`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A02` / `A-2`, `A-4`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A03` / `A-3`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A05` / `A-5`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A06` / `A-6`, `A-7`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A08` / `A-8`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A09` / `A-9`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A10` / `A-10`': {'commit': '', 'status': 'uncited'}, '`AUD-592-A02` / `A-1` second half, `§12.5`': {'commit': '63f3d61', 'status': 'present'}, '`AUD-592-B01` / `B-8`': {'commit': '8329614', 'status': 'present'}, '`AUD-592-D01` / `D-1`': {'commit': '0f8e03f', 'status': 'present'}, '`AUD-592-D02` / `D-2`': {'commit': '1d3db4d', 'status': 'present'}, '`AUD-592-D03` / `D-3`': {'commit': 'f28fe40', 'status': 'present'}, '`AUD-592-R01` / `A-1`': {'commit': '216025f', 'status': 'present'}, '`AUD-592-R02` / `N-4`, reopens `AUD-513-N04`': {'commit': 'ec3050d', 'status': 'present'}, '`AUD-593-N01` / `N-01`': {'commit': 'dd6a706', 'status': 'present'}, '`AUD-593-N02` / `N-02`': {'commit': 'f539787', 'status': 'present'}, '`AUD-593-N03` / `N-03`': {'commit': '1dd0b1c', 'status': 'present'}, '`AUD-593-N05` / `N-05`': {'commit': 'aa89388', 'status': 'present'}, '`AUD-593-N06` / `N-06`': {'commit': 'aa584a6', 'status': 'present'}, '`AUD-594-N04` / `D-5`, disclosure half of `B-3`': {'commit': 'a0060b7', 'status': 'present'}, '`AUD-594-X01` / `A-1`, residual of `AUD-593-N03`': {'commit': 'dd222b9', 'status': 'present'}, '`AUD-594-X02` / `A-1` second half': {'commit': '1193937', 'status': 'present'}, '`AUD-594-X03` / `X-03`, residual of `AUD-593-N01`': {'commit': 'e89e8f0', 'status': 'present'}, '`AUD-594-X04`': {'commit': '05b8cc9', 'status': 'present'}, '`AUD-595-A02` / `N-5`, advisory half of `AUD-588-B11`': {'commit': '3e15227', 'status': 'present'}, '`AUD-595-A03` / `B-6` exit-code half': {'commit': 'ab7285f', 'status': 'present'}, '`AUD-595-A05`': {'commit': 'e0b3d10', 'status': 'present'}, '`AUD-595-A07`, narrow half of `AUD-592-A02`': {'commit': 'cc15177', 'status': 'present'}, '`AUD-595-B01` / §B': {'commit': 'b77a1ad', 'status': 'present'}, '`AUD-595-Q01`': {'commit': '91a6566', 'status': 'present'}, '`AUD-596-A01` / `ASK-DET-001`': {'commit': 'fa508b4', 'status': 'present'}, '`AUD-596-A02` / `ASK-SELF-001`': {'commit': '4dfadc8', 'status': 'present'}, '`AUD-596-A03` / `ASK-C1-001`': {'commit': 'bffa3a6', 'status': 'present'}, '`AUD-596-A04` / `ASK-UX-003` + `ASK-UX-004`': {'commit': 'f0aac3c', 'status': 'present'}, '`AUD-596-B01` / `B-01`, harder witness for `BUG-6`': {'commit': '567d09d', 'status': 'present'}, '`AUD-596-B02` / `B-02`, class residual of `R2`': {'commit': '', 'status': 'uncited'}, '`AUD-596-B03` / `B-03`': {'commit': 'a8cb814', 'status': 'present'}, '`AUD-596-B06` / `B-06`': {'commit': '8107927', 'status': 'present'}, '`AUD-596-B07` / `B-07`, class residual of `AUD-592-R02`': {'commit': 'e060485', 'status': 'present'}, '`AUD-596-B09` / `B-09`': {'commit': '5b8146c', 'status': 'present'}, '`AUD-596-B10` / `B-10`': {'commit': '5cb994d', 'status': 'present'}, '`AUD-596-B16` / `B-16`': {'commit': '1507f69', 'status': 'present'}, '`AUD-596-D01` / `B-13` + `B-14`': {'commit': '0b1bdf0', 'status': 'present'}, '`AUD-596-D02` / `B-08`, residual of `AUD-594-N04`': {'commit': 'e7f73c3', 'status': 'present'}, '`AUD-596-D03` / `ASK-AGT-001`': {'commit': '8c46967', 'status': 'present'}, '`AUD-596-D04` / `B-18`': {'commit': '040f027', 'status': 'present'}, '`AUD-596-D05` / `B-19`': {'commit': 'fd2bf68', 'status': 'present'}, '`AUD-596-D06` / `B-20`': {'commit': '784cd83', 'status': 'present'}, '`AUD-596-D07` / `B-17`, half refuted': {'commit': 'c3ff822', 'status': 'present'}, '`AUD-596-D08` / `B-22`, class residual of `AUD-591-A06`': {'commit': 'b396c6a', 'status': 'present'}, '`AUD-596-D09` / `B-23`, surviving half of `B26`': {'commit': 'fd3d63f', 'status': 'present'}, '`AUD-596-D10` / `B-29`': {'commit': '', 'status': 'uncited'}, '`AUD-596-D11` / `ASK-UX-005`': {'commit': 'f4b4f77', 'status': 'present'}, '`AUD-596-D12` — six hints that send the reader back to the error': {'commit': '498df44', 'status': 'present'}, '`AUD-596-D13` / `B-28`': {'commit': '1014c72', 'status': 'present'}, '`AUD-596-D14` / `B-15`, narrow half of `B20`': {'commit': '10f2827', 'status': 'present'}, '`AUD-596-R01` / `B-05`': {'commit': '', 'status': 'uncited'}, '`AUD-596-X01` / `ASK-GATE-001`, gating half of `B24`': {'commit': 'e59c655', 'status': 'present'}, '`AUD-596-X02` / `ASK-UX-001` + `ASK-UX-002` + `B-21`': {'commit': 'f6ebf50', 'status': 'present'}, '`AUD-597-A01` / `ASK-UX-001` + `N-01`': {'commit': 'f8cf061', 'status': 'present'}, '`AUD-597-A02` / `ASK-UX-008` + `ASK-DOC-002`': {'commit': '9d47a4c', 'status': 'present'}, '`AUD-597-A03` / `ASK-DET-001`': {'commit': '4c7622a', 'status': 'present'}, '`AUD-597-A04` / `ASK-LEDGER-001`': {'commit': '46fb870', 'status': 'present'}, '`AUD-597-D01` / `B-04`': {'commit': '1094e6a', 'status': 'present'}, '`AUD-597-D02` / `ASK-DOC-001`': {'commit': 'ecb1bb7', 'status': 'present'}, '`AUD-597-D03` / `N-06`': {'commit': '9784333', 'status': 'present'}, '`AUD-597-D04` / `N-05`': {'commit': 'e51c087', 'status': 'present'}, '`AUD-597-D05` / `N-04`, fourth appearance of `C4-27`': {'commit': '9cccc15', 'status': 'present'}, '`AUD-597-D06` / `ASK-CLI-001`': {'commit': '178aa6d', 'status': 'present'}, '`AUD-597-D07` / `N-03`': {'commit': '9245e35', 'status': 'present'}, '`AUD-597-R01` / `ASK-PERF-001`': {'commit': '6910054', 'status': 'present'}, '`AUD-597-R02` / `ASK-ENC-001`': {'commit': 'ce6dac1', 'status': 'present'}, '`AUD-597-R03` / `ASK-UX-002`': {'commit': 'c57e50b', 'status': 'present'}, '`AUD-597-X01` / `ASK-BUILD-001` + `ASK-META-001` / `B-12`': {'commit': '354338b', 'status': 'present'}, '`AUD-598-B01` / `ASK-META-001`': {'commit': 'b2f7c65', 'status': 'present'}, '`AUD-598-B02` / `ASK-UX-002`': {'commit': '56a4bf7', 'status': 'present'}, '`AUD-598-B03` / `B-11`': {'commit': 'c63cb24', 'status': 'present'}, '`AUD-598-B04` / `N-02`': {'commit': '187937f', 'status': 'present'}, '`AUD-598-R01` / `ASK-PERF-002`': {'commit': '', 'status': 'uncited'}, '`AUD-598-X01` / `N-01` + `B-13` + `B-14` + `B-29` + `N-06`': {'commit': '6f2f5a4', 'status': 'present'}, '`AUD-600-B01` / `P-01`': {'commit': '366ffed', 'status': 'present'}, '`AUD-600-B02` / `P-02` + `ASK-PACK-002`': {'commit': '2a814c3', 'status': 'present'}, '`AUD-600-B03` / `ASK-PACK-001`': {'commit': '452f2a0', 'status': 'present'}, '`AUD-600-D01`': {'commit': '1224e1b', 'status': 'present'}, '`AUD-600-D02`': {'commit': 'eab8172', 'status': 'present'}, '`AUD-600-R01` / `R-01`': {'commit': '88add64', 'status': 'present'}, '`AUD-601-B01` / `N-02`, 5th round': {'commit': '', 'status': 'uncited'}, '`AUD-601-B02` / `ASK-PACK-004`': {'commit': '', 'status': 'uncited'}, '`AUD-601-D01` / `N-01`, `ASK-UX-001`, 5th round': {'commit': '', 'status': 'uncited'}, '`AUD-601-D02` / `B-13`, `B-14`, 5th round': {'commit': '', 'status': 'uncited'}, '`AUD-601-M01` / `B-26`, `B-27` retracted': {'commit': '', 'status': 'uncited'}, '`AUD-601-R01` / `R-02`': {'commit': '', 'status': 'uncited'}, '`AUD-619-WATCH`': {'commit': '', 'status': 'uncited'}, '`AUD-620-COMMAND-SURFACE`': {'commit': '', 'status': 'uncited'}, '`AUD-620-REVIEW-PR`': {'commit': '', 'status': 'uncited'}, '`AUD-621-REVIEW-PR`': {'commit': '', 'status': 'uncited'}, '`B-3`': {'commit': '773268d', 'status': 'present'}, '`B-6`': {'commit': '17c6e06', 'status': 'present'}, '`B-8`': {'commit': '8329614', 'status': 'present'}, '`BUG-3` / `443b345`': {'commit': '', 'status': 'uncited'}, '`BUG-4a` / `AUD-588-B11` residual': {'commit': '24b4185', 'status': 'present'}, '`BUG-4b` / `AUD-588-B11` residual': {'commit': '0376350', 'status': 'present'}, '`E-39`, class residual of `AUD-593-N06`': {'commit': '25fc11f', 'status': 'present'}, '`N-5`': {'commit': 'c68083f', 'status': 'present'}, '`N-7`': {'commit': '082e9de', 'status': 'present'}, '`R-1`': {'commit': '424fb1c', 'status': 'present'}, '`R-2`': {'commit': '5158b92', 'status': 'present'}, '`R-3`': {'commit': '88aec04', 'status': 'present'}, '`R-4`': {'commit': '04fd04f', 'status': 'present'}}
 CLOSURE_COVERAGE = {'closed_rows': 165, 'present': 91, 'absent': 0, 'unresolved': 0, 'uncited': 74, 'unknown': 0}

sourcecode/_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/_docs/USER_GUIDE.md

@@ -332,7 +332,7 @@ value in field use, and they are the ones to learn first:
 | `ask posture . --diff dev:prod` | The only command that answers *"what changes about effective access between two profile sets, across every endpoint at once"*. Experimental, and the most differentiated capability in the product. |
 | `ask endpoints .` | Every REST endpoint with its **effective path** (context-path + `spring.mvc.servlet.path` resolved), inferred security policy and per-endpoint confidence. Turns "audit the API" into a list. |
 | `ask spring-audit .` | Transactional anomalies that a compiler cannot see — `@Transactional` on a private method is a silent CGLIB no-op — plus the security surface. |
-| `ask migrate-check . --compact` | Boot 2→3 readiness plus Java LTS/licensing inventory: blockers, effort, target JDK evidence and explicit licensing-review signals. |
+| `ask migrate-check . --compact` | Boot 2→3 readiness plus Java LTS/licensing and local JVM ecosystem inventory: blockers, effort, target JDK evidence, framework/runtime signals and explicit licensing-review signals. |
 
 Everything else is either a projection of the same model (`impact`, `export`, `explain`) or an
 agent-facing packaging of it (`--compact`, `--agent`, `prepare-context`). The full surface is
@@ -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/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/canonical_ir.py

@@ -528,10 +528,17 @@ def ir_dict_to_canonical(
         files = sorted(file_set)
 
     # Sorted call graph edges — stable ordering: from, type, to
-    call_graph = sorted(
-        edges,
-        key=lambda e: (e.get("from", ""), e.get("type", ""), e.get("to", "")),
-    )
+    # The raw graph is owned by this CIR conversion and its edge order is not
+    # observable until after conversion. Sort in place instead of creating a
+    # second repository-sized list during the raw/CIR overlap peak.
+    if isinstance(edges, list):
+        edges.sort(key=lambda e: (e.get("from", ""), e.get("type", ""), e.get("to", "")))
+        call_graph = edges
+    else:
+        call_graph = sorted(
+            edges,
+            key=lambda e: (e.get("from", ""), e.get("type", ""), e.get("to", "")),
+        )
 
     # Dependency edges (structural subset of call_graph)
     _dep_types = frozenset({"imports", "extends", "implements", "injects"})
@@ -587,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/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":
@@ -4404,7 +4445,9 @@ app = typer.Typer(
     name="ask",
     help=_HELP,
     add_completion=False,
-    rich_markup_mode="rich",
+    # Rich's Windows help renderer can drop options from long command panels;
+    # plain Click help keeps the complete option contract visible there.
+    rich_markup_mode=None if os.name == "nt" else "rich",
     no_args_is_help=False,
 )
 
@@ -4904,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),
@@ -5767,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.
@@ -6349,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)
@@ -6360,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)
@@ -7097,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
@@ -7154,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)
@@ -7531,6 +7621,7 @@ def prepare_context_cmd(
         Path("."),
         help="Repository path to analyze (default: current directory)",
     ),
+    jobs: Optional[int] = _jobs_option(),
     since: Optional[str] = typer.Option(
         None,
         "--since",
@@ -7605,7 +7696,6 @@ def prepare_context_cmd(
         ),
     ),
     progress_mode: Optional[str] = _progress_option(),
-    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """Task-specific context for AI coding agents.
 
@@ -8426,6 +8516,7 @@ def repo_ir_cmd(
         Path("."),
         help="Repository root to analyze (default: current directory)",
     ),
+    jobs: Optional[int] = _jobs_option(),
     since: Optional[str] = typer.Option(
         None,
         "--since",
@@ -8491,7 +8582,6 @@ def repo_ir_cmd(
         help="Compress output with gzip. Requires --output. Reduces large IR files by ~70-80%.",
     ),
     progress_mode: Optional[str] = _progress_option(),
-    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """Deterministic symbol-level IR for Java repositories.
 
@@ -9185,6 +9275,7 @@ def endpoints_cmd(
         Path("."),
         help="Repository path to scan for REST endpoints (default: current directory)",
     ),
+    jobs: Optional[int] = _jobs_option(),
     output_path: Optional[Path] = typer.Option(
         None, "--output", "-o",
         help="Write output to a file instead of stdout.",
@@ -9251,7 +9342,6 @@ def endpoints_cmd(
              "than protect).",
     ),
     progress_mode: Optional[str] = _progress_option(),
-    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """Extract REST API endpoint surface from Java source files.
 
@@ -9806,6 +9896,7 @@ def export_cmd(
         Path("."),
         help="Repository path to export (default: current directory)",
     ),
+    jobs: Optional[int] = _jobs_option(),
     output_path: Optional[Path] = typer.Option(
         None, "--output", "-o",
         help="Write output to a file instead of stdout.",
@@ -9848,7 +9939,6 @@ def export_cmd(
              "written on the diagram whenever it bites.",
     ),
     progress_mode: Optional[str] = _progress_option(),
-    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """Export structured, tool-agnostic codebase views for downstream tooling.
 
@@ -10015,6 +10105,7 @@ def validation_cmd(
         Path("."),
         help="Repository path to scan for request-body validation (default: current directory)",
     ),
+    jobs: Optional[int] = _jobs_option(),
     output_path: Optional[Path] = typer.Option(
         None, "--output", "-o",
         help="Write output to a file instead of stdout.",
@@ -10045,7 +10136,6 @@ def validation_cmd(
         help=_NO_CACHE_SUBCOMMAND_HELP,
     ),
     progress_mode: Optional[str] = _progress_option(),
-    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """Map request-body validation per endpoint (constraints + custom validators).
 
@@ -12173,6 +12263,7 @@ def spring_audit_cmd(
         Path("."),
         help="Repository path to audit (default: current directory)",
     ),
+    jobs: Optional[int] = _jobs_option(),
     output_path: Optional[Path] = typer.Option(
         None, "--output", "-o",
         help="Write output to a file instead of stdout.",
@@ -12304,7 +12395,6 @@ def spring_audit_cmd(
     ),
     detach: bool = _detach_option(),
     progress_mode: Optional[str] = _progress_option(),
-    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """Spring semantic audit: {{RULE_SUMMARY}}.
 
@@ -13483,6 +13573,7 @@ def risk_cmd(
         Path("."),
         help="Repository path (default: current directory).",
     ),
+    jobs: Optional[int] = _jobs_option(),
     limit: int = typer.Option(
         50, "--limit", help="How many composed risks to publish (highest first).", min=0,
     ),
@@ -13542,7 +13633,6 @@ def risk_cmd(
     allow_partial: bool = _allow_partial_option(),
     detach: bool = _detach_option(),
     progress_mode: Optional[str] = _progress_option(),
-    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """What each defect actually costs, once reach and access are in it.
 
@@ -14796,6 +14886,7 @@ def posture_cmd(
         Path("."),
         help="Repository path (default: current directory).",
     ),
+    jobs: Optional[int] = _jobs_option(),
     profile: Optional[str] = typer.Option(
         None,
         "--profile",
@@ -14877,7 +14968,6 @@ def posture_cmd(
     format: str = _format_option(help="Output format: json or yaml."),
     copy: bool = _copy_option(),
     progress_mode: Optional[str] = _progress_option(),
-    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """Which beans are wired under a profile set — and which cannot be decided.
 
@@ -15300,6 +15390,7 @@ def migrate_check_cmd(
         Path("."),
         help="Repository path to scan (default: current directory)",
     ),
+    jobs: Optional[int] = _jobs_option(),
     output_path: Optional[Path] = typer.Option(
         None, "--output", "-o",
         help="Write output to a file instead of stdout.",
@@ -15441,7 +15532,6 @@ def migrate_check_cmd(
     ),
     detach: bool = _detach_option(),
     progress_mode: Optional[str] = _progress_option(),
-    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """Spring Boot 2→3 migration readiness + Java LTS/licensing inventory.
 
@@ -15847,6 +15937,7 @@ def impact_chain_cmd(
         Path("."),
         help="Repository root (default: current directory)",
     ),
+    jobs: Optional[int] = _jobs_option(),
     depth: int = typer.Option(
         4,
         "--depth",
@@ -15886,7 +15977,6 @@ def impact_chain_cmd(
         ),
     ),
     progress_mode: Optional[str] = _progress_option(),
-    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """Spring impact-chain: systemic blast radius of a symbol; TX/SEC findings are opt-in.