sourcecode 5.8.31__py3-none-any.whl → 5.9.0__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.8.31"
+__version__ = "5.9.0"

sourcecode/_build_commit.py

@@ -1,5 +1,5 @@
 """Generated at build time by hatch_build.py. Do not edit (AUD-592-D04)."""
 
-BUILD_COMMIT = '32e9b630f9276e5e481a33f0232c3a7876cd5751'
+BUILD_COMMIT = 'b4c3691c4110d863fedcd54a61a08fd2997e400c'
 CLOSURE_PROVENANCE = {'Window': {'commit': '', 'status': 'uncited'}, '`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'}, '`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': 113, 'present': 88, 'absent': 0, 'unresolved': 0, 'uncited': 25, 'unknown': 0}

sourcecode/_docs/DEFECT-LEDGER.md

@@ -16,6 +16,94 @@ The facts these rows are keyed to are published: `ask schema facts-v1` prints th
 
 ## Current Synchronization
 
+**External `5.8.32` audit received, 2026-08-26 — `AUD-607`.** Two independent
+reports ([`AUDIT-2026-08-26-EXTERNAL-5.8.32.md`](AUDIT-2026-08-26-EXTERNAL-5.8.32.md)):
+a reverification round (9.7/10) and a comparison round against `5.8.31` (8/10).
+Six previously closed findings hold on their third or fourth consecutive
+re-check, and **no regression is reported by either round**.
+
+One new defect is confirmed and closed in `5.9.0`: `AUD-607-C01`
+(P1), where `chunk-file` emitted chunk content that did not match its own
+declared `start_line`/`end_line`. Controlled reproduction found the mechanism
+**wider than reported** — two defects, not one: `_flush_chunk` serialised the
+untruncated pending buffer while declaring a truncated end line, and the
+annotation buffer's clearing guard was **unreachable**, so a field's
+`@Autowired` was carried onto the following method while the field's own
+declaration line dropped out of that chunk. The report's "deliberate undeclared
+overlap" hypothesis is refuted; no overlap contract is published. Its bounding
+battery now asserts content against the declared range, which the previous
+`include_content=False` coverage structurally could not see.
+
+`AUD-607-E01` (P2, `explain` returned "No stereotype detected" while listing that
+same class's endpoints) and `AUD-607-I01` (P3, `--files -` asserted "stdin is a
+terminal" for a Git Bash/MSYS redirect it cannot verify) are also closed in
+`5.9.0`. The first is fixed vendor-agnostically by reading the endpoint
+evidence the answer already computed, never by adding JAX-RS to a Spring
+annotation list; the second names the outcome instead of an unverifiable cause,
+the same rule `_confirm` follows for C3-106.
+
+**`AUD-607-O01` is not reproduced — second independent refutation, and it
+supersedes `AUD-606-O01`.** The two reports disagreed; measurement resolved it.
+The reverification round re-ran the command itself and confirmed the vendor
+position, and controlled reproduction on the current checkout finds no list
+exceeding the cap on `spring-petclinic` or `BroadleafCommerce`, with the
+`total`/`shown`/`omitted` envelope published on both sides of the diff. The
+`estimated_tokens` figure the second report cites is **not emitted by this
+command's payload**; it belongs to the output-ceiling spill path and describes a
+run that overflowed the ceiling. This row must not be reopened from that figure
+alone.
+
+`AUD-606-P01` is closed: the cold-cache improvement held for a second
+consecutive release (`137.8s` then `130s`), so it is no longer a single sample.
+`AUD-607-P01` (`pack gate --since` timing) is inconclusive for the fourth round
+under confirmed process contamination and stays bound to the existing
+measurement protocol — a contaminated sample is evidence of neither a regression
+nor its absence.
+
+**Feature intake `AUD-607-X01`…`X09` is CLOSED, one commit per row.** All nine
+are released in `5.9.0` with bounding batteries and full registry entries
+(`b7df333`, `182d95e`, `da3e2da`, `d35b7f8`, `3e42c2c`, `0fc3a15`, `55b93c2`,
+`6463fdf`, `f1fa913`): `cve`, `intent`, `remediate`, `pr-risk`,
+`export --c4 --render`, `watch`, `baseline --kind findings`, `drift` and
+`self-audit`. Six schemas were registered and published alongside them.
+⚠**Three defects were found by building these, not by the audit:** the C4
+renderer's first version drew report metadata (`summary`, `coverage_note`) as
+system architecture; the watch loop stat-ed repository-relative paths against
+the process CWD and so reported "nothing changed" forever; and `self-audit`
+found its own schema identifier unregistered on its first run. Each is covered
+by an assertion now. `X09` ships with its "not recommended" verdict inside the
+payload rather than dropped: the semantic engine does not apply to this
+product's own Python source, and those figures are declared absent rather than
+reported as zeros.
+
+**Current `5.9.0` queue:** `AUD-607-U01` (P3, new commands do not name their
+applicable bounding flags in `--help`) and `AUD-607-U02` (P2, unconfirmed:
+`cache warm` reported a component `exit 143` under a global exit `0`). Feature
+intake `AUD-607-X01`…`X09` is recorded in the audit note and the development
+roadmap; **two proposed features were withdrawn on inspection** because they
+already ship as `spring-audit --clusters` (CODEOWNERS ownership) and
+`spring-audit --since --fail-on-new` (new-versus-historical findings). The
+existing `AUD-604-R01` and `AUD-605` release-artifact verification items remain
+unchanged.
+
+**External `5.8.31` audit received, 2026-08-26 - `AUD-606`.**
+[`AUDIT-2026-08-26-EXTERNAL-5.8.31.md`](AUDIT-2026-08-26-EXTERNAL-5.8.31.md)
+confirms the new progress and shared-cache controls, and records one actionable
+external-subject follow-up `AUD-606-O01`, where `posture --diff --compact --limit`
+was effectively unchanged on the auditor's nested output; the current checkout
+reproduces no such gap and its bounding batteries pass. It also opens the CLI
+consistency row `AUD-606-R01` for heterogeneous `retrieve` target flags, fixed
+in the current checkout by `be16c04` with help-parity coverage.
+The 137.8s cold run is a single-sample improvement and remains `AUD-606-P01`
+benchmark follow-up, not a parser regression. `AUD-606-P02` (`pack gate` timing)
+and `AUD-606-I01` (`pr-impact --files -` with `/dev/null`) are inconclusive due
+to process contamination and shell-specific stdin behaviour respectively.
+
+**Current `5.8.31` queue:** external-subject follow-up `AUD-606-O01`; controlled
+benchmark/portability follow-ups `AUD-606-P01`, `AUD-606-P02` and `AUD-606-I01`.
+The existing `AUD-604-R01` and `AUD-605` release-artifact verification items
+remain unchanged.
+
 **External pack audit received, 2026-08-26 - `AUD-605`.**
 [`AUDIT-2026-08-26-EXTERNAL-5.8.28-PACK.md`](AUDIT-2026-08-26-EXTERNAL-5.8.28-PACK.md)
 adds two rows: `AUD-605-G01`, where an unresolved test file broadened pack-gate unknown
@@ -25,7 +113,7 @@ checkout by `52bcc36` and `f89ae18`, with focused regression batteries passing;
 artefact verification remains pending. The pack's `--since` timing is additional evidence
 for `AUD-604-P01`, not a duplicate performance finding.
 
-**Current `5.8.31` queue:** artefact verification for `AUD-604-R01`; the two `AUD-605`
+**Previous `5.8.31` pack queue:** artefact verification for `AUD-604-R01`; the two `AUD-605`
 fixes are included in this release and await release-artefact verification.
 
 **External `5.8.28` audit received, 2026-08-26 - `AUD-604`.**

sourcecode/_docs/USER_GUIDE.md

@@ -46,13 +46,13 @@ CLI commands        — impact, endpoints, spring-audit, explain, … each a pro
 The key idea: the extraction is **content-addressed**. Commands reuse the parse cache and,
 where their analysed scope matches, the shared Canonical IR; `ask cache model` names what a
 warm buys for each command rather than implying that every projection costs the same. In
-5.8.31, `validation` enters through that shared CIR and `data-exposure` reuses one semantic
+5.9.0, `validation` enters through that shared CIR and `data-exposure` reuses one semantic
 model across all declared label seeds. (The extraction and consumption contract is fixed in
 the architecture ADRs 0001–0004 under `docs/architecture/`.)
 
 The current external pack audit intake is tracked in
 [`AUDIT-2026-08-26-EXTERNAL-5.8.28-PACK.md`](AUDIT-2026-08-26-EXTERNAL-5.8.28-PACK.md);
-the two pack fixes are included in release 5.8.31, with release-artifact verification
+the two pack fixes are included in release 5.9.0, with release-artifact verification
 remaining for detached execution and pack evidence.
 
 ---
@@ -115,6 +115,8 @@ ask pack list
 ask pack assessment . --profile prod --output-dir .ask/packs/assessment
 ask pack gate . --since origin/main --compact --output-dir .ask/packs/gate
 ask pack assessment . --format markdown -o assessment.md
+ask pack assessment . --only risk,posture --output-dir .ask/packs/assessment
+ask pack gate . --pr 123 --output-dir .ask/packs/gate
 ```
 
 To include deployment evidence, pass the environment artefacts that describe
@@ -129,8 +131,25 @@ The gate can emit native annotations for CI logs:
 ```bash
 ask pack gate . --since origin/main --format github-actions
 ask pack gate . --since origin/main --format gitlab
+ask pack gate . --since origin/main --format sarif -o gate.sarif
 ```
 
+`pack assessment --only` selects a comma-separated subset of the declared
+assessment components. The manifest records omitted components;
+`audit-report` may be selected only together with `risk`.
+
+MCP `get_assessment_pack` exposes the same capability through its `only`
+`list[str]` input. It uses the declared component order and validation rules;
+the reproducible CLI command in the `mcp` projection includes the selection.
+
+`pack gate --pr NUMBER` resolves changed files through the local `gh` CLI and
+uses the pull request's exact base commit. The base commit must already exist
+locally; the command does not fetch or modify the repository and cannot be
+combined with `--since`.
+
+The `sarif` gate format is a bounded SARIF 2.1.0 export of ASK-owned gate
+decisions. It does not re-emit findings produced by third-party scanners.
+
 The pack JSON preserves `manifest`, identity, fingerprints, evidence and each
 component's partial status. `PASS`, `BLOCK` and `UNVERIFIED` are data
 decisions; the process exit code is the pipeline signal. When `--output-dir` is
@@ -139,6 +158,10 @@ component remains a separate JSON artifact. An explicit `--output FILE` takes
 precedence. See the
 [Product Route contract](PRODUCT-ROUTE.md) for the boundaries.
 
+The MCP `get_change_safety_gate` tool accepts the same two comparison modes:
+`since` for a local Git ref or `pr` for GitHub pull-request resolution through
+the local `gh` CLI. Pass exactly one; PR mode requires the base SHA locally.
+
 See [Product Route](PRODUCT-ROUTE.md) for the evidence contract and scope.
 
 A distinct set of commands exists to feed **AI coding agents** rather than to be read by a
@@ -183,7 +206,7 @@ pipx install sourcecode   # isolated install, no venv needed
 
 # Verify
 ask version
-# ask 5.8.31
+# ask 5.9.0
 ```
 
 Requires Python 3.9+.
@@ -228,7 +251,7 @@ estimate scaled by file count would be wrong in the direction that costs you a s
 and an anchor printed without its release goes on recommending a nightly job for a command
 that has come to finish in seconds (C3-97).
 
-41 commands and seven command groups exist. Four of them carry most of the measured
+48 commands and seven command groups exist. Four of them carry most of the measured
 value in field use, and they are the ones to learn first:
 
 | Start with | Because |
@@ -1275,16 +1298,24 @@ explaining. The rest do one thing; `ask <command> --help` is the whole story.
 | Command | Tier | What it does |
 |---|---|---|
 | `ask migrate-check` | core | Spring Boot 2→3 readiness plus Java LTS/licensing inventory: blockers, effort range, target JDK evidence and explicit licensing-review signals. Full reference: [migrate-check.md](migrate-check.md) |
+| `ask drift` | supported | What changed in the effective access — since the last capture (`--capture` records; the default compares) or between two profile sets (`--against`). One arithmetic for both axes. Separates `newly_unmatched` from `newly_matched`, and a `removed` route is NOT reported as having become safe. |
+| `ask watch` | supported | Warm the index once, then answer what each save affected — one JSON line per tick. `--once` is the pre-commit shape; `--ticks`/`--for` bound the loop. A file added since the warm is reported `unresolved`, never `unreachable`, and a failed analysis is an `error` tick rather than an empty change list. |
+| `ask pr-risk` | supported | One verdict for one diff — does this change make things worse? Joins `pr-impact` reach, endpoint access, the shared risk model and CODEOWNERS. `--since` differences route inventories so `new_endpoints` is a fact rather than a guess. An unresolved changed file caps the verdict at `UNKNOWN`, which fails every gate. |
+| `ask remediate` | supported | One loop from finding to verified change: audit → recipe → apply in a dedicated worktree → `verify-edit`. Dry by default; `--write` applies. Publishes `mechanisable` against `manual_remainder` with the reason each family cannot be rewritten, and reports `unverified` — never `applied` — when the result could not be checked. |
+| `ask cve` | supported | Cross the dependency inventory against a **local** OSV advisory feed (`--feed`; no network is taken), then report whether a route can reach the vulnerable package: `reachable`, `imported_not_exposed`, `not_observed` or `unknown`. `not_observed` is not a statement of safety, and nothing here answers "not reachable". |
 | `ask explain <Class>` | supported | Human-readable architectural summary for one class (text by design, not JSON) |
-| `ask export` | supported | Tool-agnostic views for downstream tooling: `--c4`, `--module-graph`, `--by-directory`, `--integrations` |
+| `ask export` | supported | Tool-agnostic views for downstream tooling: `--c4`, `--module-graph`, `--by-directory`, `--integrations`. `--c4 --render mermaid\|svg` draws the same model instead of emitting it — presentation over the existing payload, with the node cap written on the diagram. |
 | `ask repo-ir` | supported | Deterministic symbol-level IR for the whole repository |
 | `ask cold-start` | supported | Repository Intelligence Snapshot bootstrap context, returned from the persisted RIS |
+| `ask baseline … --kind findings` | supported | The defect population as a persisted series, in the same store as the architectural baseline: `capture` records it, `diff` reports new/resolved/persisting against the last capture, and `trend` says how long each still-open defect has been open. `first_seen` is the earliest STORED capture — not the day it was introduced. |
 | `ask prepare-context <task>` | supported | Task-shaped context: `onboard`, `delta`, `fix-bug`, `generate-tests`. See [Typical workflows](#typical-workflows) |
 | `ask chunk-file <file>` | supported | Split a large Java file into semantic chunks an agent can consume |
+| `ask intent "<question>"` | supported | Resolve a plain-language question to the typed `retrieve` query that answers it (scored lexical match against a declared vocabulary — no model, no generation). Prints the query; `--run` executes it. A question fitting two intents too closely is refused with both named. |
 | `ask rename-class` | supported | Word-boundary Java rename across the repository |
 | `ask schema <name>` | supported | Print a published JSON Schema for this tool's output |
+| `ask self-audit` | supported | Check the SHIPPED build's own coherence — cache model, format contract, schema registry and output affordances. Declares explicitly that the semantic engine does not apply to this product's own source (ASK analyses Java; this build is Python), rather than reporting zeros. `ask selftest` is the different question: the defect ledger run against a real repository. |
 | `ask archetype` | experimental | Evidence-based architectural archetype across four dimensions |
-| `ask retrieve` | parked | Typed knowledge queries over the model — kept working, no longer developed |
+| `ask retrieve` | parked | Typed knowledge queries over the model — kept working, no longer developed. Symbol-oriented queries accept `--target/-t`; `--module/-m`, `--subsystem/-s` and `--endpoint/-e` remain compatible domain aliases. |
 | `ask baseline capture\|diff\|trend` | supported | Versioned architectural metrics over time; see [`ask trend`](#ask-trend-dir--how-the-architecture-moved) |
 | `ask cache status\|warm\|model\|clear\|freshness` | supported | Cache inspection; `ask cache model` states what a warm buys each command |
 | `ask config` · `ask version` · `ask activate` · `ask auth` · `ask telemetry` · `ask mcp` | supported | Configuration, version, licence, authentication, telemetry (on by default), MCP integration |
@@ -1359,6 +1390,51 @@ ask endpoints /repo --compact                # the census without the rows: coun
 ask endpoints /repo --output endpoints.json
 ```
 
+### Closing the loop: find it, judge it, fix it, prove it
+
+The seven newest commands are joins of pieces that already shipped, and they share one
+rule: where the answer cannot be decided, they say so rather than return a reassuring zero.
+
+```bash
+# 1. Which advisories a route can actually REACH — not which are on the classpath.
+#    The feed is a local file; no network is taken during analysis, so a CI gate can
+#    never pass because a fetch timed out.
+ask cve . --feed ./osv-maven.json --reachable-only --fail-on reachable
+
+# 2. Ask in your own words. It SELECTS one of retrieve's typed queries and prints it;
+#    --run executes it. It never invents an answer.
+ask intent "what breaks if I change OrderService?"
+
+# 3. Judge the change, not the repository. UNKNOWN outranks PASS and fails the gate.
+git diff --name-only main | ask pr-risk . --files - --since main --fail-on block
+
+# 4. Fix the mechanical part, and prove the tree still holds.
+ask remediate .                       # the plan; writes nothing
+ask remediate . --write --allow-network
+
+# 5. Keep the receipts, so "how long has this been open?" has an answer.
+ask baseline capture . --kind findings
+ask baseline trend . --kind findings
+```
+
+Two of them run on a clock rather than on demand:
+
+```bash
+# In CI, after each deploy: what opened up since the last capture?
+ask drift . --profile prod --capture
+ask drift . --profile prod --fail-on-exposure
+
+# In the editor: what did this save affect?
+ask watch . --once
+```
+
+And two answer about the tool rather than the repository:
+
+```bash
+ask self-audit --fail-on fail       # does the INSTALLED build's registry agree with itself?
+ask selftest .                      # the published defect ledger, run against your repo
+```
+
 ### MCP server (AI agent integration)
 
 ```bash
@@ -1443,6 +1519,16 @@ the **RIS**, builds the **shared Canonical IR** and fills the **parse cache**. I
 `--exclude` change *what is analysed*, so they miss the warmed core and rescan — that is the
 171s the field measured after a 103s warm.
 
+Select the root views needed by a workflow explicitly:
+
+```bash
+ask cache warm . --views compact
+ask cache warm . --views compact,agent
+```
+
+Without `--views`, all declared root views are warmed. `cache model` reports the
+same per-view contract and names any view that was skipped.
+
 What invalidates what:
 
 - **Any change to the analysed files** → every layer keys on one signature of the tree state:

sourcecode/access_drift.py

@@ -0,0 +1,232 @@
+"""access_drift.py — what changed in the effective access, and when.
+
+`AUD-607-X08`. `posture --diff dev:prod` already answers *"do these two
+environments expose different things?"*, and `baseline trend` already keeps a
+series. Neither answers the question an operator actually gets paged about:
+*what changed in prod's effective access since the last deploy?* — because the
+first is a comparison of two profile sets at one instant, and nobody was
+recording the instants.
+
+One diff serves both axes. A snapshot is `route → access class` for a profile
+set, so comparing two profile sets and comparing one profile set across time are
+the same operation on different pairs, and the two answers can never disagree
+about what "newly exposed" means.
+
+**Direction is not symmetry.** A route that moved from a matched rule to
+`no_rule_matched` is not the same event as the reverse, and collapsing both into
+"changed" is how an alert that matters gets read as noise. The payload separates
+`newly_unmatched` from `newly_matched`.
+
+**A route that vanished did not become safe.** It may have been deleted, renamed
+or moved behind a profile that is no longer active, and this analysis cannot tell
+those apart — so `removed` is its own bucket and says so.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+SCHEMA_VERSION = "1.0"
+SCHEMA_ID = "access-drift-v1"
+
+#: Stored snapshots share the baseline directory; the prefix keeps the three
+#: series (architecture, findings, access) from reading each other's documents.
+FILENAME_PREFIX = "access-"
+
+#: The access class published when the posture found no rule deciding a route.
+UNMATCHED = "no_rule_matched"
+
+#: Keys of `effective_access` that are not access classes.
+_NOT_A_CLASS = frozenset({"chains", "summary"})
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+def routes_from_posture(posture: "dict") -> "dict[str, str]":
+    """`"VERB path" → access class`, from a posture payload.
+
+    The lists under `effective_access` are keyed by access class and hold
+    `VERB:path:controller:handler` strings. Only the verb and path identify the
+    route across two runs: a handler that moved class is the same route to a
+    caller, and keying on the handler would report a refactor as a new exposure.
+    """
+    access = ((posture or {}).get("endpoints") or {}).get("effective_access") or {}
+    routes: "dict[str, str]" = {}
+    for access_class, value in access.items():
+        if access_class in _NOT_A_CLASS or not isinstance(value, list):
+            continue
+        for entry in value:
+            parts = str(entry).split(":")
+            if len(parts) < 2:
+                continue
+            verb, path = parts[0].strip().upper(), parts[1].strip()
+            if not path:
+                continue
+            routes[f"{verb} {path}"] = access_class
+    return routes
+
+
+def build_snapshot(
+    root: Path,
+    profiles: "set[str]",
+    *,
+    posture: "Optional[dict]" = None,
+    properties: "Optional[dict]" = None,
+    commit: "Optional[str]" = None,
+) -> dict:
+    """One capture of the effective access under a profile set."""
+    from sourcecode.architectural_baseline import git_commit
+
+    if posture is None:
+        from sourcecode.posture import build_posture
+
+        posture = build_posture(Path(root), set(profiles or ()), properties)
+
+    routes = routes_from_posture(posture)
+    by_class: "dict[str, int]" = {}
+    for access_class in routes.values():
+        by_class[access_class] = by_class.get(access_class, 0) + 1
+
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "schema": SCHEMA_ID,
+        "kind": "access",
+        "captured_at": _utc_now(),
+        "commit": commit if commit is not None else git_commit(Path(root)),
+        "repo": Path(root).name,
+        "profiles": sorted(profiles or ()),
+        "counts": {
+            "routes": len(routes),
+            "by_access_class": dict(sorted(by_class.items())),
+        },
+        "routes": dict(sorted(routes.items())),
+    }
+
+
+def snapshot_filename(snapshot: "dict") -> str:
+    profiles = "-".join(snapshot.get("profiles") or ()) or "default"
+    stem = snapshot.get("commit") or snapshot.get("captured_at", "capture")
+    safe = "".join(c if (c.isalnum() or c in "-_.") else "-" for c in f"{profiles}-{stem}")
+    return f"{FILENAME_PREFIX}{safe}.json"
+
+
+def write_snapshot(snapshot: "dict", out_dir: Path) -> Path:
+    from sourcecode import readonly as _readonly
+    from sourcecode.architectural_baseline import protect_ask_dir
+
+    out_dir = Path(out_dir)
+    _readonly.guard(out_dir, what="access history directory")
+    out_dir.mkdir(parents=True, exist_ok=True)
+    protect_ask_dir(out_dir)
+    path = out_dir / snapshot_filename(snapshot)
+    path.write_text(
+        json.dumps(snapshot, indent=2, sort_keys=True, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+    return path
+
+
+def load_series(out_dir: Path, *, profiles: "Optional[set]" = None) -> "list[dict]":
+    """Stored access snapshots, oldest first, optionally for one profile set."""
+    out_dir = Path(out_dir)
+    if not out_dir.is_dir():
+        return []
+    series: "list[dict]" = []
+    wanted = sorted(profiles) if profiles is not None else None
+    for path in sorted(out_dir.glob(f"{FILENAME_PREFIX}*.json")):
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue
+        if not isinstance(payload, dict) or payload.get("kind") != "access":
+            continue
+        if wanted is not None and list(payload.get("profiles") or ()) != wanted:
+            continue
+        payload["_source_file"] = path.name
+        series.append(payload)
+    series.sort(key=lambda s: str(s.get("captured_at") or ""))
+    return series
+
+
+def diff_snapshots(base: "dict", head: "dict", *, axis: str = "time") -> dict:
+    """What moved between two access snapshots.
+
+    `axis` only labels the answer: `time` for one profile set across captures,
+    `environment` for two profile sets at one instant. The arithmetic is identical,
+    which is the point — the two can never disagree about "newly exposed".
+    """
+    base_routes: "dict[str, str]" = dict(base.get("routes") or {})
+    head_routes: "dict[str, str]" = dict(head.get("routes") or {})
+
+    added = sorted(set(head_routes) - set(base_routes))
+    removed = sorted(set(base_routes) - set(head_routes))
+    shared = sorted(set(base_routes) & set(head_routes))
+
+    newly_unmatched: "list[dict]" = []
+    newly_matched: "list[dict]" = []
+    reclassified: "list[dict]" = []
+    for route in shared:
+        before, after = base_routes[route], head_routes[route]
+        if before == after:
+            continue
+        row = {"route": route, "from": before, "to": after}
+        if after == UNMATCHED:
+            newly_unmatched.append(row)
+        elif before == UNMATCHED:
+            newly_matched.append(row)
+        else:
+            reclassified.append(row)
+
+    added_rows = [{"route": r, "access": head_routes[r]} for r in added]
+    added_unmatched = [r for r in added_rows if r["access"] == UNMATCHED]
+
+    changed = (
+        len(added) + len(removed) + len(newly_unmatched)
+        + len(newly_matched) + len(reclassified)
+    )
+
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "schema": SCHEMA_ID,
+        "axis": axis,
+        "base": {
+            "captured_at": base.get("captured_at"),
+            "commit": base.get("commit"),
+            "profiles": list(base.get("profiles") or ()),
+            "routes": len(base_routes),
+        },
+        "head": {
+            "captured_at": head.get("captured_at"),
+            "commit": head.get("commit"),
+            "profiles": list(head.get("profiles") or ()),
+            "routes": len(head_routes),
+        },
+        "counts": {
+            "added": len(added),
+            "added_without_a_matching_rule": len(added_unmatched),
+            "removed": len(removed),
+            "newly_unmatched": len(newly_unmatched),
+            "newly_matched": len(newly_matched),
+            "reclassified": len(reclassified),
+            "changed_total": changed,
+        },
+        "drifted": bool(changed),
+        "added": added_rows,
+        "removed": [{"route": r, "access": base_routes[r]} for r in removed],
+        "newly_unmatched": newly_unmatched,
+        "newly_matched": newly_matched,
+        "reclassified": reclassified,
+        "non_coverage": [
+            "a route in `removed` did not become safe: it may have been deleted, "
+            "renamed, or moved behind a profile that is no longer active, and this "
+            "comparison cannot tell those apart",
+            "routes are identified by verb and path, so a handler that moved class "
+            "is the same route — a refactor is not reported as a new exposure",
+        ],
+    }