sourcecode 4.0.0__tar.gz → 4.1.0__tar.gz

{sourcecode-4.0.0 → sourcecode-4.1.0}/CHANGELOG.md

@@ -2,6 +2,111 @@
 
 ## [Unreleased]
 
+## [4.1.0] — 2026-08-03
+
+Minor, not a patch, and the criterion is this project's own: a new rule can trip
+a gate that was green yesterday. `spring-audit --ci` and `verify --fail-on any`
+will fail on a repository that stores a credential in a deployment descriptor —
+correctly, and for the first time. Nothing is removed, no default moves, and no
+exit code changes meaning.
+
+Field audit #8 (deep read-only audit of the eval #6/#7 repository, by a new
+evaluator, 100 % catalogue coverage) ran a build self-reporting **3.5.0** while
+4.0.1 was shipping, and re-derived twelve of its fourteen product complaints from
+rows already closed — one of them the answer to its own critical finding. The
+first entry below is that defect; the rest are the three findings that survived
+verification against 4.0.1.
+
+### Added
+
+- **SEC-007 — a credential stored in a deployment descriptor** (CL-10). The audit
+  found `monitor:{SHA-256}dc20b820…` in
+  `src/main/options/{DPA,M3,M3DEV}/WEB-INF/web.xml`: unsalted, the same hash in all
+  three per-environment overlays, and found by hand because *"los overlays
+  `src/main/options/**` son punto ciego"*. The gap was admission surface, not
+  detection — those descriptors are files `environment_resolution`,
+  `filter_surface` and `path_filters` already open, and SEC-004 already names a
+  fast unsalted digest. The rule fires on the **shape of the value**
+  (`{ALGO}<hex>`), never on the parameter's name (VAI), with `${placeholder}` as
+  the negative control; the digest is truncated in the finding, because a report
+  about a credential must not be a place to read one from; and identical digests
+  across descriptors are composed into the statement the audit actually made —
+  three environments share one credential, so the least protected decides the
+  strength of all three. NC-002 is **narrowed, not deleted**: Helm values, CI
+  variable files and shell scripts stay declared out of scope. Zero findings across
+  six field repositories.
+- **`ask version` says how old the build is** (C4-12). Age in days alone would not
+  have caught the audit's case — that build was three days old. On this project's
+  cadence three days is six releases (eight, in fact). So the block publishes the
+  release date, the measured release rate (2.07/day over the last 30 releases), an
+  **estimate** of releases since with its basis, and an advisory naming the upgrade
+  command and the defect ledger. It never claims a newer release exists: offline,
+  that would be the confident-wrong answer the ledger exists to prevent. `_meta`
+  carries `tool_release_date` only — the date is a constant of the build, the age
+  changes daily, and the envelope is byte-identical by contract.
+
+### Fixed
+
+- **`posture` now says when the container would not contradict its own resolution**
+  (CL-11). `allow-bean-definition-overriding: true` and
+  `allow-circular-references: true`, in the repository whose entire security verdict
+  turns on which `SecurityConfig` bean wins: with overriding enabled a second
+  definition replaces the first silently, so the startup failure that would have
+  caught a filter-chain override never happens. The block only ever **lowers**
+  confidence, so it sits beside the verdict and is repeated inside
+  `security.resolution_is_a_default` — the C1-20 lesson runs the other way here, and
+  a caveat a reader has to go and find does not reach the conclusion it was written
+  for. An undecidable setting is not read as off.
+- **The platform claim matches what the battery can check** (C3-38). Third field
+  report of console mojibake on Windows/PowerShell; C3-3 and C3-12 are both recorded
+  *does not reproduce*, both scoped macOS-only. Patching a codec that was never
+  reproduced is what C3-27's rule forbids, so the README states instead that
+  Windows is a target the battery cannot verify, names what the CLI does do for it,
+  and cites the three rows. A documented limit is not a fix: C3-38 stays open until
+  a Windows runner exists.
+
+
+## [4.0.1] — 2026-08-02
+
+Patch, and the criterion is the one this project has used since 3.2.0: nothing here
+moves a published field, an exit code or a default. Three surfaces stopped
+misdescribing an engine that did not change — the release advertised half its own
+security ruleset, the front page led to neither capability the field asked for by
+name, and the document both of them call the full command reference covered fewer
+than half the commands. All three were found in-house.
+
+### Fixed
+
+- **`spring-audit --help` advertised three security rules and the build ships six**
+  (C4-9). The one-liner the root panel prints, and the command's own screen, said
+  `security surface (SEC-001..003)` two releases after CL-9 shipped SEC-004, SEC-005
+  and SEC-006; `docs/PRODUCT_TIERS.md` said `TX-001..005 + SEC-001..003` and
+  `docs/USER_GUIDE.md` said `TX-001..TX-005`. The engine was right in every case —
+  the product advertised half its ruleset, in the release that answered the field's
+  complaint about security recall. `sourcecode/rule_catalog.py` now holds one summary
+  line per rule and the help renders from it, while the id *set* is derived from the
+  shipped pattern registries by `tests/test_rule_catalog.py`: a seventh rule fails the
+  build until it is documented, and no surface may name a rule the build cannot emit.
+  The non-coverage block in the same help is rendered from `non_coverage` too, which
+  had a renderer with no consumer beside four rows restated by hand.
+- **The front page did not lead to either remedy that C4-8 closed** (C4-10). The
+  pointer lived in the payload that states the limitation, which reaches an agent and
+  not a reader who has not run the command yet — the same reader who wrote
+  `ask posture --provenance` and `ask contracts init` by hand after a full session.
+  `ask --help` now renders a *Questions the repository alone does not answer* block
+  from `remedies.REMEDIES`, and lists `risk .` in Start here; the README carries
+  `--resolve-environments`, `verify --init` and `ask risk` in the Quickstart,
+  `--resolve-environments` in §5b beside the `--diff` it qualifies, and a §5c for
+  composed risk. `tests/test_remedies.py` fails when a remedy is absent from either
+  surface.
+- **The "full command reference" documented 14 of 32 commands** (C4-11). `verify`,
+  `verify-edit` and `pr-impact` — the three gate commands — appeared only as names in
+  the tier table, and eight more had no occurrence in the file at all. Sections added
+  for the gate family (with the exit-code contract they share), for `plan`, `compare`,
+  `delta` and `contract-diff`, and a table for the rest.
+  `tests/test_user_guide_coverage.py` takes the command population from the CLI and
+  parses every invocation the guide prints against it.
+
 ## [4.0.0] — 2026-08-02
 
 Major because two published `gate_coverage` fields are removed, not because the

{sourcecode-4.0.0 → sourcecode-4.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.0.0
+Version: 4.1.0
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -97,13 +97,25 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 2.5.1
+ask version                    # ask 4.1.0 — and, on a build that has aged,
+                               # how many releases have probably shipped since
 ```
 
 > **Package vs. command.** The install package is named `sourcecode` this release
 > (renaming the distribution is a separate, breaking change). Installing it gives you the
 > canonical **`ask`** command plus the deprecated **`sourcecode`** alias.
 
+> **Platforms.** Developed and tested on macOS and Linux; every release runs its full
+> battery there. **Windows/PowerShell is a target we cannot verify:** the CLI is written
+> for it — UTF-8 streams are forced at both console entry points, a successful run writes
+> nothing to stderr (PowerShell 5.1 raises `NativeCommandError` on any stderr write), and
+> the MCP server strips the BOM PowerShell puts on stdin — but no Windows runner exists in
+> the battery. Three separate field reports of console mojibake (`—` rendering as `â€"`)
+> have never reproduced under measurement, and the only variable those reports share is the
+> platform we cannot exercise (C3-3, C3-12, C3-38 in the
+> [defect ledger](docs/DEFECT-LEDGER.md)). On Windows, prefer `--output <file>` over shell
+> redirection, and report a rendering problem rather than assuming it is known.
+
 ---
 
 ## Quickstart
@@ -129,6 +141,26 @@ ask spring-audit /path/to/repo
 ask migrate-check /path/to/repo --compact
 ```
 
+**Then the three that finish the sentence the four above start.** A profile-set answer stays
+conditional until you know which set the deployment starts with, a gate nobody can populate is
+a gate nobody runs, and a defect ranked without its reach is a linter note:
+
+```bash
+# Which profile set ACTUALLY runs? Reads every artefact that can set it — build,
+# descriptors, Dockerfile, Compose, Kubernetes, launch scripts — with file:line, and
+# says NOT DECIDED IN THIS REPOSITORY when nothing in the tree decides it. Then ranks
+# every admissible set by what it leaves reachable without authentication.
+ask posture /path/to/repo --resolve-environments
+
+# Derive the contracts this repository already satisfies, execute each one before
+# writing it, and populate .ask/contracts.yml from the measurement instead of by hand.
+ask verify /path/to/repo --init
+
+# What each defect actually costs once reach, access and write effect are in it:
+# severity × reachability × auth_verdict × write_effect, ordered, every factor traceable.
+ask risk /path/to/repo
+```
+
 Then the everyday loop:
 
 ```bash
@@ -145,13 +177,17 @@ ask onboard /path/to/repo
 ask review-pr /path/to/repo --since main
 
 # CI gate on NEW violations only, instead of on pre-existing debt
+ask verify /path/to/repo --init               # derive the contracts, don't hand-write them
 ask verify /path/to/repo --capture-baseline   # accept today's debt, once
 ask verify /path/to/repo                      # then: only new violations block
 ```
 
-> **Adopting a gate on a real codebase.** A repository that starts declaring contracts already
-> violates them somewhere; `ask verify` is **baseline-relative by default** (`--fail-on new`)
-> so the gate survives contact with reality instead of being switched off on day one.
+> **Adopting a gate on a real codebase.** Nobody hand-writes contracts for a 3 000-file
+> monolith, so `ask verify --init` derives the ones the repository satisfies **today** and
+> executes each before writing it — init followed by verify passes by construction.
+> A repository that starts declaring contracts already violates them somewhere; `ask verify`
+> is **baseline-relative by default** (`--fail-on new`) so the gate survives contact with
+> reality instead of being switched off on day one.
 > `ask baseline capture|diff|trend` is a different thing: versioned architectural metrics over
 > time, for trend reporting rather than blocking.
 
@@ -194,10 +230,32 @@ What a profile set **actually wires**: which conditional beans register, which d
 `ask posture` · `ask posture --diff dev:prod` · `ask posture --property k=v`
 → [posture.md](docs/posture.md)
 
+**`--resolve-environments` carries it past the edge of the repository.** Every answer above
+is conditional on a profile set, and which set runs is decided by the deployment. This flag
+reads every artefact in the tree that can set `spring.profiles.active` — Maven/Gradle,
+`web.xml`, `Dockerfile`, Compose, Kubernetes, launch scripts — with `file:line`, and returns
+`decided_in_repository`, `artefacts_disagree` (two deployments, never resolved by picking
+one) or **`NOT DECIDED IN THIS REPOSITORY`**. Then it resolves every admissible set over one
+parse and publishes the worst. A field audit closed those five hops by hand with grep before
+the flag existed.
+`ask posture . --resolve-environments`
+
 Unresolved is a first-class outcome: a condition the resolver cannot decide is reported as a
 hole with the condition named, never folded into active or inactive. **A posture answer that
 guesses is a confident security falsehood — the worst failure mode this tool has.**
 
+### 5c · Composed Risk *(experimental)*
+Every command above answers one axis, and a reader composes them by hand. `ask risk` does the
+join over the endpoint and symbol ids these commands already share with each other:
+`severity_effective = defect_severity × reachability × auth_verdict × write_effect`. The
+product of the published factors **is** the published score — decomposable to the four
+figures and the authority behind each — and an axis this build cannot measure is `unknown`,
+weighted 1.0 and named in `blind_axes` rather than silently treated as safe. Measured on a
+field case: a defect both `spring-audit` and `impact-chain` called *medium* composes to
+**high (8.06)** once *reachable unauthenticated* and *writes to the database* are in it.
+`ask risk .` · `ask risk . --min-band high` · `ask risk . --limit 10`
+→ [reference](docs/USER_GUIDE.md)
+
 ### 6 · Developer Workflows
 The everyday loop: diff-based PR review, symptom-driven bug triage, and delta context for continuous agent runs.
 `ask review-pr` · `ask fix-bug` · `ask prepare-context`
@@ -285,7 +343,7 @@ reading JSON sees the same boundary a buyer reads here.
 | Not covered | Why | What answers it |
 |---|---|---|
 | **Whether request input reaches a sink — no dataflow or taint analysis.** | This engine resolves structure and wiring without compiling. Taint needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL). What this product adds on top is reachability: which of that tool's findings sit behind an endpoint that is reachable unauthenticated. |
-| **Secrets outside Java and Spring configuration — a credential in a deployment descriptor, a Helm value, a CI variable file.** | The file population this analyzer reads is the Java source and the Spring configuration convention. A secret elsewhere is not missed by a weak rule; it is outside the set of files anything here opens. | A dedicated secret scanner over the whole tree (gitleaks, trufflehog). |
+| **Secrets outside Java, Spring configuration and the deployment descriptors — a Helm value, a CI variable file, a shell script.** | The file population this analyzer reads is the Java source, the Spring configuration convention and the descriptors it already parses to resolve an environment. A secret elsewhere is not missed by a weak rule; it is outside the set of files anything here opens. Narrowed by CL-10: a credential stored in `web.xml` or a Spring XML context IS reported (SEC-007), because those files were already being read. | A dedicated secret scanner over the whole tree (gitleaks, trufflehog). |
 | **Filter-chain order and per-filter URL patterns — the presence of a custom filter is structural only.** | Which filter runs first is decided by bean ordering this analyzer does not resolve. Where two active configurations both match a request, the answer published is `undecided` rather than a guess. | `ask posture --profile <set>` states per endpoint what the readable rules decide and what they leave undecided. |
 | **Known vulnerabilities in dependencies — no CVE database, no version advisory matching.** | Enriching a vulnerability feed is a different product with a different update cadence; a stale embedded database is worse than no database, because it reads as a clean bill of health. | A dependency scanner (Trivy, OWASP Dependency-Check). `impact-chain` then answers which of its findings anything actually reaches. |
 

{sourcecode-4.0.0 → sourcecode-4.1.0}/README.md

@@ -59,13 +59,25 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 2.5.1
+ask version                    # ask 4.1.0 — and, on a build that has aged,
+                               # how many releases have probably shipped since
 ```
 
 > **Package vs. command.** The install package is named `sourcecode` this release
 > (renaming the distribution is a separate, breaking change). Installing it gives you the
 > canonical **`ask`** command plus the deprecated **`sourcecode`** alias.
 
+> **Platforms.** Developed and tested on macOS and Linux; every release runs its full
+> battery there. **Windows/PowerShell is a target we cannot verify:** the CLI is written
+> for it — UTF-8 streams are forced at both console entry points, a successful run writes
+> nothing to stderr (PowerShell 5.1 raises `NativeCommandError` on any stderr write), and
+> the MCP server strips the BOM PowerShell puts on stdin — but no Windows runner exists in
+> the battery. Three separate field reports of console mojibake (`—` rendering as `â€"`)
+> have never reproduced under measurement, and the only variable those reports share is the
+> platform we cannot exercise (C3-3, C3-12, C3-38 in the
+> [defect ledger](docs/DEFECT-LEDGER.md)). On Windows, prefer `--output <file>` over shell
+> redirection, and report a rendering problem rather than assuming it is known.
+
 ---
 
 ## Quickstart
@@ -91,6 +103,26 @@ ask spring-audit /path/to/repo
 ask migrate-check /path/to/repo --compact
 ```
 
+**Then the three that finish the sentence the four above start.** A profile-set answer stays
+conditional until you know which set the deployment starts with, a gate nobody can populate is
+a gate nobody runs, and a defect ranked without its reach is a linter note:
+
+```bash
+# Which profile set ACTUALLY runs? Reads every artefact that can set it — build,
+# descriptors, Dockerfile, Compose, Kubernetes, launch scripts — with file:line, and
+# says NOT DECIDED IN THIS REPOSITORY when nothing in the tree decides it. Then ranks
+# every admissible set by what it leaves reachable without authentication.
+ask posture /path/to/repo --resolve-environments
+
+# Derive the contracts this repository already satisfies, execute each one before
+# writing it, and populate .ask/contracts.yml from the measurement instead of by hand.
+ask verify /path/to/repo --init
+
+# What each defect actually costs once reach, access and write effect are in it:
+# severity × reachability × auth_verdict × write_effect, ordered, every factor traceable.
+ask risk /path/to/repo
+```
+
 Then the everyday loop:
 
 ```bash
@@ -107,13 +139,17 @@ ask onboard /path/to/repo
 ask review-pr /path/to/repo --since main
 
 # CI gate on NEW violations only, instead of on pre-existing debt
+ask verify /path/to/repo --init               # derive the contracts, don't hand-write them
 ask verify /path/to/repo --capture-baseline   # accept today's debt, once
 ask verify /path/to/repo                      # then: only new violations block
 ```
 
-> **Adopting a gate on a real codebase.** A repository that starts declaring contracts already
-> violates them somewhere; `ask verify` is **baseline-relative by default** (`--fail-on new`)
-> so the gate survives contact with reality instead of being switched off on day one.
+> **Adopting a gate on a real codebase.** Nobody hand-writes contracts for a 3 000-file
+> monolith, so `ask verify --init` derives the ones the repository satisfies **today** and
+> executes each before writing it — init followed by verify passes by construction.
+> A repository that starts declaring contracts already violates them somewhere; `ask verify`
+> is **baseline-relative by default** (`--fail-on new`) so the gate survives contact with
+> reality instead of being switched off on day one.
 > `ask baseline capture|diff|trend` is a different thing: versioned architectural metrics over
 > time, for trend reporting rather than blocking.
 
@@ -156,10 +192,32 @@ What a profile set **actually wires**: which conditional beans register, which d
 `ask posture` · `ask posture --diff dev:prod` · `ask posture --property k=v`
 → [posture.md](docs/posture.md)
 
+**`--resolve-environments` carries it past the edge of the repository.** Every answer above
+is conditional on a profile set, and which set runs is decided by the deployment. This flag
+reads every artefact in the tree that can set `spring.profiles.active` — Maven/Gradle,
+`web.xml`, `Dockerfile`, Compose, Kubernetes, launch scripts — with `file:line`, and returns
+`decided_in_repository`, `artefacts_disagree` (two deployments, never resolved by picking
+one) or **`NOT DECIDED IN THIS REPOSITORY`**. Then it resolves every admissible set over one
+parse and publishes the worst. A field audit closed those five hops by hand with grep before
+the flag existed.
+`ask posture . --resolve-environments`
+
 Unresolved is a first-class outcome: a condition the resolver cannot decide is reported as a
 hole with the condition named, never folded into active or inactive. **A posture answer that
 guesses is a confident security falsehood — the worst failure mode this tool has.**
 
+### 5c · Composed Risk *(experimental)*
+Every command above answers one axis, and a reader composes them by hand. `ask risk` does the
+join over the endpoint and symbol ids these commands already share with each other:
+`severity_effective = defect_severity × reachability × auth_verdict × write_effect`. The
+product of the published factors **is** the published score — decomposable to the four
+figures and the authority behind each — and an axis this build cannot measure is `unknown`,
+weighted 1.0 and named in `blind_axes` rather than silently treated as safe. Measured on a
+field case: a defect both `spring-audit` and `impact-chain` called *medium* composes to
+**high (8.06)** once *reachable unauthenticated* and *writes to the database* are in it.
+`ask risk .` · `ask risk . --min-band high` · `ask risk . --limit 10`
+→ [reference](docs/USER_GUIDE.md)
+
 ### 6 · Developer Workflows
 The everyday loop: diff-based PR review, symptom-driven bug triage, and delta context for continuous agent runs.
 `ask review-pr` · `ask fix-bug` · `ask prepare-context`
@@ -247,7 +305,7 @@ reading JSON sees the same boundary a buyer reads here.
 | Not covered | Why | What answers it |
 |---|---|---|
 | **Whether request input reaches a sink — no dataflow or taint analysis.** | This engine resolves structure and wiring without compiling. Taint needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL). What this product adds on top is reachability: which of that tool's findings sit behind an endpoint that is reachable unauthenticated. |
-| **Secrets outside Java and Spring configuration — a credential in a deployment descriptor, a Helm value, a CI variable file.** | The file population this analyzer reads is the Java source and the Spring configuration convention. A secret elsewhere is not missed by a weak rule; it is outside the set of files anything here opens. | A dedicated secret scanner over the whole tree (gitleaks, trufflehog). |
+| **Secrets outside Java, Spring configuration and the deployment descriptors — a Helm value, a CI variable file, a shell script.** | The file population this analyzer reads is the Java source, the Spring configuration convention and the descriptors it already parses to resolve an environment. A secret elsewhere is not missed by a weak rule; it is outside the set of files anything here opens. Narrowed by CL-10: a credential stored in `web.xml` or a Spring XML context IS reported (SEC-007), because those files were already being read. | A dedicated secret scanner over the whole tree (gitleaks, trufflehog). |
 | **Filter-chain order and per-filter URL patterns — the presence of a custom filter is structural only.** | Which filter runs first is decided by bean ordering this analyzer does not resolve. Where two active configurations both match a request, the answer published is `undecided` rather than a guess. | `ask posture --profile <set>` states per endpoint what the readable rules decide and what they leave undecided. |
 | **Known vulnerabilities in dependencies — no CVE database, no version advisory matching.** | Enriching a vulnerability feed is a different product with a different update cadence; a stale embedded database is worse than no database, because it reads as a clean bill of health. | A dependency scanner (Trivy, OWASP Dependency-Check). `impact-chain` then answers which of its findings anything actually reaches. |
 

{sourcecode-4.0.0 → sourcecode-4.1.0}/pyproject.toml

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

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

{sourcecode-4.0.0 → sourcecode-4.1.0}/src/sourcecode/cli.py

@@ -297,6 +297,27 @@ def _group_help_block() -> str:
     return "\n".join(lines)
 
 
+def _remedy_help_block() -> str:
+    """The front page names the answers the field asked for as missing features.
+
+    C4-8 was closed in the payload: a limitation now carries the invocation that
+    resolves it. But the evaluator who wrote `ask posture --provenance` and `ask
+    contracts init` by hand was reading `--help` first, and neither shipped flag
+    was on it. The block is rendered from `remedies.REMEDIES`, so the pointer and
+    the capability cannot drift — `tests/test_remedies.py` already refuses a
+    remedy whose option the CLI does not accept.
+    """
+    from sourcecode.remedies import headlines
+
+    lines = ["[bold]Questions the repository alone does not answer:[/bold]"]
+    for invocation, headline in headlines():
+        # Bare invocation, like every other block on this page: the header panels
+        # print without the `ask ` prefix (C3-16).
+        bare = invocation.removeprefix("ask ")
+        lines.append(f"  {bare:<33}[dim]# {headline}[/dim]")
+    return "\n".join(lines)
+
+
 def _build_help_text() -> str:
     """Build --help text dynamically based on current license state."""
     try:
@@ -323,6 +344,9 @@ of files) in minutes. Semantic analysis itself is sub-second; repo indexing domi
   endpoints .                  [dim]# endpoints + effective path + policy[/dim]
   spring-audit .               [dim]# TX anomalies + security surface[/dim]
   migrate-check . --compact    [dim]# Boot 2→3: located blockers + effort[/dim]
+  risk .                       [dim]# defects ranked by reach × access (exp.)[/dim]
+
+{_remedy_help_block()}
 
 [bold]Agent context:[/bold]
   ask --compact                [dim]# high-signal summary (~2,500–4,000 tokens)[/dim]
@@ -6438,19 +6462,11 @@ def spring_audit_cmd(
         help=_NO_CACHE_SUBCOMMAND_HELP,
     ),
 ) -> None:
-    """Spring semantic audit: TX anomalies (TX-001..006) + security surface (SEC-001..003).
+    """Spring semantic audit: {{RULE_SUMMARY}}.
 
     \b
     Detects:
-      TX-001  @Transactional on private/final method (CGLIB proxy bypass)
-      TX-002  REQUIRES_NEW nested in REQUIRED call chain
-      TX-003  readOnly=true boundary propagating to write operation
-      TX-004  NOT_SUPPORTED/NEVER within active TX chain
-      TX-005  Exception swallowing inside @Transactional
-      TX-006  Self-invocation of @Transactional sibling (proxy bypass)
-      SEC-001 Unsecured endpoint in annotation_based security model
-      SEC-002 CVE-2025-41248: @PreAuthorize on inherited method from generic supertype
-      SEC-003 @Transactional on @Controller/@RestController (TX in wrong layer)
+{{RULE_LIST}}
 
     \b
     Findings and defects are two counts, both published. A rule fires per
@@ -6482,10 +6498,7 @@ def spring_audit_cmd(
     \b
     What it does not look at (the whole list is in the payload's `non_coverage`,
     and in the README):
-      NC-001  whether request input reaches a sink — no dataflow or taint
-      NC-002  secrets outside Java and Spring configuration
-      NC-003  filter-chain ORDER — a custom filter's presence is structural only
-      NC-004  known vulnerabilities in dependencies — no CVE matching
+{{NON_COVERAGE}}
     Silence about those is not evidence that there is nothing to find.
 """
     import json as _json
@@ -6587,6 +6600,30 @@ def spring_audit_cmd(
         raise typer.Exit(code=1)
 
 
+def _render_audit_help(doc: str) -> str:
+    """Fill the rule and non-coverage blocks from the tables that own them.
+
+    The rules this command detects were written out by hand in its own help, and
+    stayed at `SEC-001..003` for two releases after CL-9 shipped three more — the
+    C4-1 shape, where a curated list beside a generated one drifts and the
+    curated one is what the reader gets. Both blocks are rendered now, so adding
+    a rule updates the help by construction.
+    """
+    from sourcecode import non_coverage, rule_catalog
+
+    nc_lines = [
+        f"      {line}" for line in non_coverage.render_help_lines("security_surface", width=68)
+    ]
+    return (
+        doc.replace("{{RULE_SUMMARY}}", rule_catalog.summary_line())
+        .replace("{{RULE_LIST}}", rule_catalog.render_help_block())
+        .replace("{{NON_COVERAGE}}", "\n".join(nc_lines))
+    )
+
+
+spring_audit_cmd.__doc__ = _render_audit_help(spring_audit_cmd.__doc__ or "")
+
+
 # ── verify-edit: in-loop semantic diff gate ───────────────────────────────────
 
 
@@ -8897,8 +8934,16 @@ def version_cmd() -> None:
       {"cli_version": "1.33.11", "mcp_schema_version": "1.33.11",
        "compatibility_schema_version": "1.0"}
     """
+    from sourcecode.release_info import advisory_line, build_status
+
     if getattr(sys.stdout, "isatty", lambda: False)():
         typer.echo(f"ask {__version__}")
+        # C4-12: the field audits builds that are days old and many releases
+        # behind, and nothing said so. Printed only when it applies — an advisory
+        # on every run is one nobody reads.
+        _advisory = advisory_line()
+        if _advisory:
+            typer.echo(_advisory)
     else:
         import json as _json_ver
         from sourcecode.envelope import ENVELOPE_VERSION, available_schemas
@@ -8906,6 +8951,10 @@ def version_cmd() -> None:
             "cli_version": __version__,
             "mcp_schema_version": __version__,
             "compatibility_schema_version": "1.0",
+            # Which release this is, when it shipped, and how far behind it
+            # probably is. The estimate carries its basis and never claims a
+            # newer release exists (C4-12).
+            "build": build_status(),
             # What a consumer should actually pin against: the release string
             # changes every release, the envelope version only when the output
             # contract does.

{sourcecode-4.0.0 → sourcecode-4.1.0}/src/sourcecode/envelope.py

@@ -123,6 +123,16 @@ def build_meta(
         "tool_version": __version__,
         "command": command,
     }
+    # C4-12: a consumer holding a payload could not tell how old the build that
+    # produced it was. The DATE is a constant of the build, so it goes here; the
+    # AGE changes daily and would break the byte-identical property above, so it
+    # is derived where it is asked for (`ask version`), never in the envelope.
+    try:
+        from sourcecode.release_info import RELEASE_DATE
+
+        meta["tool_release_date"] = RELEASE_DATE
+    except Exception:
+        pass
     if schema_version:
         meta["schema_version"] = schema_version
 

{sourcecode-4.0.0 → sourcecode-4.1.0}/src/sourcecode/non_coverage.py

@@ -74,13 +74,16 @@ NON_COVERAGE: tuple[NonCoverage, ...] = (
         id="NC-002",
         surface="security_surface",
         not_covered=(
-            "Secrets outside Java and Spring configuration — a credential in a "
-            "deployment descriptor, a Helm value, a CI variable file."
+            "Secrets outside Java, Spring configuration and the deployment "
+            "descriptors — a Helm value, a CI variable file, a shell script."
         ),
         why=(
-            "The file population this analyzer reads is the Java source and the "
-            "Spring configuration convention. A secret elsewhere is not missed by "
-            "a weak rule; it is outside the set of files anything here opens."
+            "The file population this analyzer reads is the Java source, the Spring "
+            "configuration convention and the descriptors it already parses to "
+            "resolve an environment. A secret elsewhere is not missed by a weak "
+            "rule; it is outside the set of files anything here opens. Narrowed by "
+            "CL-10: a credential stored in `web.xml` or a Spring XML context IS "
+            "reported (SEC-007), because those files were already being read."
         ),
         instead="A dedicated secret scanner over the whole tree (gitleaks, trufflehog).",
     ),