@clear-capabilities/agentic-security-scanner 0.136.9 → 0.137.0

package/CHANGELOG.md

@@ -9,6 +9,650 @@
 > make the history less accurate, not more.
 
 
+## 0.137.0 — detection-gap remediation Themes B+D, C, E, plus R9, the R16 close-out, and the docs overhaul
+
+Seven independent slices of `docs/DETECTION_GAP_REMEDIATION_PRD.md` land
+together here (R6, R8, R9, R10, R11, R13, R14(a), R14(b), R16), alongside the
+world-class docs overhaul (`docs/DOCS_OVERHAUL_PRD.md`). Each has its own
+subsection below, and each subsection carries its own verification paragraph —
+the numbers in one do not describe the other.
+
+### Docs overhaul — a learning layer, an accuracy pass, and an anti-rot gate
+
+The product had a strong evidence layer (architecture, metrics, compliance
+maps) and no learning layer. This release adds one, and repairs what was false.
+
+- **A deliberately-vulnerable demo app** at `examples/demo-app/` — ~10 files
+  spanning every pillar (SQLi, missing auth, eval, MD5 hashing, prompt
+  injection, hardcoded key, Dockerfile hygiene, vulnerable deps). Its promised
+  findings are pinned by `scanner/test/demo-app.test.js` (wired into
+  `test:smoke`) so a detector change can't silently make the tutorials lie. It
+  is outside the self-scan gate's target set, so it never perturbs that gate.
+- **A 15-minute quickstart** (`docs/guides/quickstart.md`) and **six
+  task-oriented how-to guides** — scanning, fixing, SBOM/AI-BOM, compliance, CI
+  setup, leaked-secret response — plus a **CLI reference**, a **configuration &
+  env-var reference**, and a **docs hub** (`docs/README.md`). Every command
+  shown was run against the demo app before being documented.
+- **Accuracy pass** — repaired every false/contradictory claim the doc survey
+  found: version drift across four manifests (`gemini-extension.json` was
+  ~60 versions stale), the model-cost-optimizer default contradiction, the
+  compliance `--gap` row, a skill pointing at a deleted command file (revoke-URL
+  matrix restored inline), the README's `hunt`-is-a-slash-command claim, and
+  `secure --tour`/`--daily` documented-but-unimplemented (now implemented).
+- **New anti-rot gate** — `scripts/check-doc-drift.mjs --gate` fails on any
+  dangling internal link across README/docs/commands/skills/agents; wired into
+  the release gate as `doc-links` and proven both directions. Manifest
+  version-sync now also covers `gemini-extension.json`.
+- **Two output-correctness fixes surfaced while documenting:** the CycloneDX/
+  SPDX SBOM tool version was hardcoded `0.7.0` — now stamped from the real
+  engine version via `meta.engineVersion`. And `js-yaml` was bumped
+  `5.2.3 → 5.3.0` to clear the dependency-currency gate.
+
+Verification: `test:smoke` 30/30 (includes the two demo-app contract tests),
+`sbom` 3/3, `release-check` 49/49, `check-doc-drift --gate` clean and
+fails-on-planted-break. Full `npm test` + the release gate run on push.
+
+### R9 — Java call-graph edges existed in the CFG but never reached the call graph
+
+`ir/parser-java.js` never emitted `fn.calls`, leaving every Java function's
+call-graph edges permanently empty (`callgraph.js` reads `fn.calls`
+exclusively). Wired the same shared, language-agnostic call-extraction helper
+six other parsers already use — no new extraction logic, matching the
+identical precedent set by Ruby's earlier fix. A final-review fix wave
+rebuilt the bundle, corrected doc overclaims, and added a resolution proof
+test (`test/parser-java-calls.test.js`, 94 lines).
+
+### R16 — independent population re-measured; the finding is the absence of movement
+
+Re-ran `bench/independent` (110 GHSA-labelled entries, fresh fetch, scan
+state wiped) after seven PRD themes landed since the last measurement. Result
+is identical, entry for entry, to the 2026-08-09 run — same TP/FP/FN/TN, same
+per-language split, same recall across all ~40 CWE categories. Reported
+plainly rather than explained away: the independent population has zero
+Java/C#/Kotlin/PHP/Ruby/Go entries, so R8/R9 could not have moved it
+structurally; Theme A (the plan's own hypothesized dominant lever, which also
+landed after the baseline) plus R6/R10/R11/R13/R14(a) could have moved a
+JS/TS/Python entry and none did. This measurement cannot distinguish "fix
+doesn't occur in these 110 entries' shapes" from "effect masked elsewhere in
+the same scan" — only that the net observable outcome per entry is unchanged.
+The PRD backlog is closed on this basis.
+
+### Theme B+D (R6, R10, R11) — semantic grounding and interprocedural completeness
+
+Closes three of the five open items in `docs/DETECTION_GAP_REMEDIATION_PRD.md`'s
+Theme B ("semantic grounding of matching") and Theme D ("interprocedural
+completeness"). R7 and R12 — filed under the same two themes — turned out to
+already be landed (commit `553f9a5`, swept in opportunistically alongside
+Theme A's nine fixes).
+
+- **Class Hierarchy Analysis is now wired into the deep pipeline** —
+  prerequisite infrastructure for R6 and R11. `ir/class-hierarchy.js` and the
+  receiver-type heuristic (`dataflow/receiver-context.js`) were both already
+  built and unit-tested but never consulted at scan time; `dataflow/index.js`
+  now builds CHA once per scan and threads it through every `callContext`.
+  Landing this exposed a real, independent pre-existing bug in
+  `class-hierarchy.js` itself: its method-qid parser assumed a dot-joined
+  `"ClassName.method"` shape, but the parser's actual qid format for a class
+  method is `::`-joined (`file.js::ClassName::method@line`) — so `cha.classes`
+  was silently empty for every JS/TS class, and CHA-based resolution could
+  never have worked at all until this was fixed. The only prior test for
+  `buildClassHierarchy` had hand-mocked a qid in the wrong shape, which is why
+  this went unnoticed.
+- **R6 — catalog sink matching is now gated by CHA-inferred receiver type.**
+  A bare-name sink like `.query()` or `.get()` previously matched on ANY
+  receiver project-wide (`cache.query(x)` scored identically to
+  `db.query(x)`). An opt-in `match.receiverTypeIn` catalog field is now
+  declared on the 5 highest-FP-risk bare-name entries (`js-sql-query`,
+  `js-sql-execute`, `py-requests-get` x2, `rb-erb-new`). Unknown receiver type
+  never suppresses a match — only a confidently resolved, non-matching type
+  does.
+
+  **Coverage is not uniform across those 5, and the honest summary is that
+  only the two JS entries do real work.** The gate can only fire when CHA
+  actually resolves a receiver type, and CHA's `typeOfVar` is populated from
+  exactly one shape: a local `let/const x = new Foo()` whose IR carries the
+  `isNew` marker — emitted today by the JS/TS, Java and C# parsers only.
+  So `rb-erb-new` is effectively inert: `ERB.new(x)`'s receiver is a bare
+  identifier that is never `new`-assigned, so the type is always unknown and
+  the entry always stays permissive. The two `py-requests-get` entries are
+  inert for the same reason (Python has no `new`, so its parser emits no
+  marker). Both are harmless — an inert gate is a permissive gate, and the
+  pattern layer's match survives untouched — but "applied to 5 entries"
+  should not be read as "gating 5 entries."
+- **R10 — a call nested inside another expression now consults the callee's
+  own taint summary.** `sink(getUserInput())` previously only checked
+  `getUserInput()`'s own arguments for taint (the call's return-taint was
+  invisible outside assignment-RHS and bare-statement position, the only two
+  places the summary cache was consulted). `exprTaint`'s `'call'` case now
+  also resolves and consults the callee's summary, via the same shared
+  resolver R11 uses.
+- **R11 — a JS/TS member call (`svc.save(x)`) now resolves interprocedurally
+  when CHA traces the receiver to one unambiguous, assignment-tracked local
+  variable.** Previously refused unconditionally (a bare dotted-name guess
+  risks inventing an edge between two unrelated same-named methods). This
+  landed narrower than originally scoped: it deliberately still refuses
+  `this.field.method()` resolution. An early implementation reused R6's full
+  receiver-type heuristic, including its two name-guess fallbacks
+  (`this.field` PascalCase-to-class guessing, bare-identifier soft-labeling) —
+  safe for R6's weaker consequence (mis-gating an *existing* catalog match),
+  but review found that reusing the same guesses for R11's stronger
+  consequence (fabricating a *new* interprocedural call-graph edge) let a
+  same-named unrelated variable resolve to the wrong class purely by name
+  coincidence. R11 now calls `classOfVar` directly, trusting only genuinely
+  assignment-tracked local types, and an ambiguous or unresolved receiver
+  (including every `this.field` shape) still safely refuses to resolve rather
+  than guessing — matching this PRD's own stated caution that R11 should stay
+  unimplemented rather than ship with degraded precision.
+
+Two narrower gaps surfaced during R11 implementation and were deliberately
+left unfixed as out of scope (recorded as candidate future work in
+`docs/DETECTION_GAP_REMEDIATION_PRD.md`'s new "Status updates" section): CHA's
+variable-type tracking is scoped to the exact enclosing function (a
+module-scope instance referenced from inside a closure/route-handler can't be
+typed there), and taint-argument recognition only handles bare-identifier or
+one-level member-access call arguments (a two-level access like
+`req.query.cmd` passed directly is invisible to it).
+
+- **A wiring-and-verification pass on this work caught R6 suppressing a real
+  finding, and the fix landed the same way it was found: with a gate.**
+  `bench:layer-recall:check` — which exists precisely to catch a layer going
+  quiet on a language it used to cover — flagged `js/ts` taint recall
+  dropping 7 → 6. Root cause: `_receiverTypeFor` fell back to returning the
+  receiver's own bare identifier name (e.g. `c`) whenever `classOfVar`
+  couldn't verify a type, and the caller then treated that name as a
+  confidently-resolved non-match rather than as "unknown" — a direct
+  violation of R6's own "unknown != clean" rule. Concretely:
+  `const c = mysql.createConnection({}); c.query(tainted)` (a `mysql`
+  connection assigned via a factory call rather than `new X()`, the exact
+  shape `CVE-2021-22214-node-sqli-shape` exercises) was silently dropped by
+  the taint engine, because `'c'` doesn't match the SQL receiver allow-list —
+  even though it's a genuine, tainted SQL sink. `bench:cve-replay:check`
+  stayed green throughout, because a different, non-taint layer happened to
+  still catch this same corpus entry — the corpus gate answers "was it
+  detected at all," not "by which layer," which is exactly the blind spot
+  `bench:layer-recall:check` exists to close. Fixed by removing the
+  bare-identifier fallback: a non-`this` receiver is now trusted only when
+  `classOfVar` genuinely resolves it, mirroring the fix already applied to
+  R11 above. This is exactly the kind of near-miss the full gate sequence
+  (test, corpus, mutation, layer-recall) exists to catch before it ships, and
+  it did.
+- **That fix was too narrow, and the whole-branch review caught it: the same
+  bug class had three more instances in the same function.** The round-4 fix
+  above removed the bare-identifier fallback but kept the `this.field`
+  PascalCase guess, on the reasoning that it wasn't implicated in *that*
+  regression. It was implicated in the identical one. `receiverTypeAtCall`'s
+  `this`-branch structurally cannot return `null` — it PascalCases the field
+  name and returns it — so every `this.<field>.method()` call was treated as a
+  confidently-resolved type, and only field names that happened to collide
+  with the allow-list vocabulary survived. `this.dbConn.query(req.query.q)`
+  and `this.readReplica.query(req.query.q)` are both real SQL injections, both
+  reported by the pre-branch base commit, and both were silently absent from
+  this branch — not demoted, gone, with no other layer catching them. Two more
+  instances alongside it: for a multi-segment chain like `svc.db.query(x)` the
+  code resolved `parts[0]` — the chain ROOT — answering "what type is `svc`?"
+  when the receiver is `svc.db`, a property path CHA never types at all; and
+  `buildClassHierarchy`'s `typeOfVar` walker accepted any PascalCase callee as
+  a constructor, so `const q = BuildCache()` was confidently mistyped as class
+  `BuildCache`. All three were name-or-shape guesses being trusted as
+  resolutions.
+
+  Rather than a fourth one-off patch, `_receiverTypeFor` now states the one
+  thing CHA can actually verify and refuses everything else: a receiver chain
+  of exactly two dot-separated parts (`x.method`), resolved through
+  `classOfVar`. `this`-rooted and multi-segment chains return `null` —
+  unknown, permissive. `parser-js.js` now emits the `isNew` marker on
+  `NewExpression` (matching what the Java and C# parsers already emit) and
+  `buildClassHierarchy` requires it, so a PascalCase *factory* call is no
+  longer mistaken for a constructor. Separately, the `receiverTypeIn`
+  vocabularies were exact-anchored (`^(?:db|pool|conn…)$`) from back when the
+  value reaching them could be a bare variable name; now that only real class
+  names arrive, `DatabaseConnection`, `PrismaClient` and `MySQLConnection` all
+  failed the allow-list and were suppressed, while only a class literally
+  named `Db` passed — the existing test passed solely because its fixture was
+  named `class Db`. Those four patterns are now substring matches
+  (`rb-erb-new`'s `^ERB$` stays anchored: one exact class, not a vocabulary),
+  and `Cache` still correctly suppresses.
+
+  The claim two bullets up — "unknown receiver type never suppresses a match"
+  — was false on the `this.field` path for the whole of this branch's life
+  until now. It is true again, and it is now gated rather than asserted:
+  `bench/mutation/` gained a detection dimension and four R6 cases, two of
+  them metamorphic renames (`class Db` → `class DatabaseConnection`,
+  `this.db` → `this.dbConn`) that a vocabulary-keyed gate cannot survive, plus
+  an adversarial non-DB receiver so that simply deleting the gate cannot pass
+  either. Both metamorphic cases fail on the pre-fix engine. Three rounds of
+  this same false-negative class shipped behind human review; the mutation
+  gate is what makes a fourth fail loudly instead.
+
+**Verification — Theme B+D (R6, R10, R11) only:** full test gate green
+(`npm test`, 3146 tests), corpus (214/214, no drift), mutation (9/9
+verdict-flip, and non-zero exit confirmed against the pre-fix engine) and
+layer-recall (214/214 detected, per-language taint counts equal to baseline)
+all green. These figures predate the R13 work below, which was gated
+separately; see R13's own verification paragraph for the current totals.
+
+### Theme E (R13) — flow-modeling coverage, both sub-fixes
+
+- **R13(a) — a member-write assignment target (`el.innerHTML = tainted`) is
+  now consulted against the sink catalog.** The taint engine previously only
+  checked call expressions against the sink catalog; a plain property
+  assignment with no call syntax at all — the PRD's own success metric,
+  `el.innerHTML = req.query.x` — was structurally invisible regardless of
+  taint. `dataflow/catalog.js` gains a small member-write sink table and
+  `matchMemberWriteSink(targetPath, file)`; `dataflow/engine.js` consults it
+  on assignment targets alongside the existing call-sink path.
+- **R13(b) — a for-of loop variable now carries the iterated expression's
+  taint into the loop body.** `for (const item of req.body.items) { eval(item) }`
+  — the PRD's other stated success metric — previously read `item` as clean:
+  the shared Babel loop visitor never bound the for-of loop variable to what
+  it iterates. `ir/parser-js.js`'s loop visitor now synthesizes an
+  `item = <iterated expr>` assignment in its `enter()` hook, scoped strictly
+  to `ForOfStatement`; the other four loop-statement types that funnel
+  through the same shared visitor (`for`, `while`, `do-while`, `for-in`) are
+  pinned byte-identical in CFG output by a dedicated regression test, since
+  a shared-visitor edit is the single riskiest shape of change this plan
+  made.
+
+  **This one took three extra fix rounds, and all three are worth recording
+  honestly.** First: a second, generic Babel visitor
+  (`VariableDeclarator`) also fires for the for-of binding's own
+  `const item` declarator and runs after the loop visitor's `enter()` but
+  before the body, silently overwriting the just-synthesized assignment
+  with `source:unknown` — fixed with a guard skipping that declarator.
+  That guard's first version was over-broad: it skipped *any*
+  `ForOfStatement` `left` declarator, which also deleted the same visitor's
+  pre-existing destructuring taint-KILL nodes and regressed
+  `for (const {cmd} of SAFE) eval(cmd)` to a false positive (the
+  destructured `cmd` should shadow and clear an outer tainted `cmd` of the
+  same name, and briefly stopped doing so). Narrowed to
+  `path.node.id?.type === 'Identifier'` so only the simple-identifier shape
+  the loop visitor actually synthesizes for is skipped; destructuring falls
+  through unaffected, now pinned by a regression test.
+
+  Second, and unrelated to the guard bug: R13(b)'s new taint capability made
+  a genuinely pre-existing, independent bug newly reachable inside the
+  scanner's *own* `ir/type-stubs.js` — `catalog.js`'s `js-exec` entry
+  matches any `X.exec(tainted)` by bare property name with no receiver-type
+  check, so `RegExp.exec()` calls newly carrying taint via the for-of fix
+  got misidentified as `child_process.exec` command injection. Confirmed
+  independent of the loop change (reproduces on a trivial non-loop fixture)
+  and traced to a catalog entry that predates this PRD entirely
+  (`f0d7e03`). Required a `bench/self-scan/BASELINE.json` update
+  (`dataflow/index.js: 0→5`, `ir/type-stubs.js: 6→10`), not a code fix —
+  logged as its own open gap in `docs/DETECTION_GAP_REMEDIATION_PRD.md`
+  rather than patched here, since the real fix needs CHA to type
+  regex-literal-assigned variables first.
+
+  Third, found by the final whole-branch review: narrowing the guard fixed
+  destructuring but left the shape the guard now *owns* with no kill at all.
+  `const`/`let` in a for-of head is a **block-scoped** binding, and this
+  engine's taint model has no block scoping — so once the loop variable was
+  bound to the iterable's taint, that state flowed straight past the loop's
+  exit and over-tainted a same-named OUTER variable:
+  `let item = 'safe'; for (const item of req.body.items) {} eval(item)`
+  reported a Code Injection finding that the pre-R13 engine correctly called
+  clean, because the generic `VariableDeclarator` visitor used to emit a
+  taint-KILL there and the guard suppresses it. That directly violated this
+  work's own "strictly additive — never remove or alter an existing finding"
+  constraint. The loop visitor now records the bound name in `enter()` and
+  re-emits the kill in `exit()`, on the loop's normal exit edge
+  (`header → exit-noop → kill → post-loop code`), so in-loop taint
+  reachability is untouched and only the post-loop read is cleared. The
+  bare-assignment form (`for (x of ...)`, no `const`/`let`) deliberately gets
+  **no** kill — that binding is function-scoped and its value legitimately
+  survives the loop; killing it would itself have been a regression. Both
+  directions are now pinned by tests.
+
+Both sub-fixes are covered end-to-end and at the unit level by
+`test/member-write-and-loop-taint.test.js` (12 tests), wired into
+`test:dataflow`.
+
+**Verification — R13 only:** full gate green — `npm test` (3158 tests, 0
+failures), corpus (214/214, no drift), mutation (12/12 mutant verdicts
+correct, of which 9/9 are verdict-flip cases), layer-recall (js/ts taint recall unchanged at 7/38 vs. baseline's 7/36 — R13
+lands via dedicated unit tests rather than new corpus entries, so no
+taint-layer increase was expected or observed here) and self-scan (green
+against the baseline this same work already updated).
+
+### Theme E (R14(b)) — non-JS top-level IR
+
+Closes the other half of Theme E's R14 item: Python (CST parser and regex
+fallback), PHP, and Ruby now synthesize a `<module>` function wrapping
+top-level statements, mirroring the JS `<module>` pattern
+(`ir/parser-js.js:264,557`) that already existed. Before this, a flat
+vulnerable script with no wrapping function or class — `<?php
+system($_GET['cmd']);`, a bare `system(params[:cmd])` in Ruby, a bare
+`os.system(request.args)` at Python module scope — had zero Layer-2
+taint-analysis coverage in these three languages, regardless of how
+obviously tainted the flow was, simply because the IR layer never extracted
+top-level statements into any CFG at all. Unlike JS's unconditional
+`<module>` creation, all three new paths only synthesize the function when
+the file actually has top-level statements worth lowering, to keep the
+change's blast radius on existing function-only fixtures at zero.
+
+Landing this also surfaced (and fixed) a real, independent severity bug:
+the dead-code demotion in `dataflow/engine.js` only exempts functions whose
+name matches `/handler|route|controller|middleware|endpoint/i` from being
+downgraded one severity tier when the call graph records no caller — but a
+synthetic `<module>` function is *never* called by anything (module scope
+has no caller by construction), so every finding this work would have added
+was about to land one tier too low (critical → high, etc.) the moment it
+shipped. `<module>`-scoped findings are now exempt from dead-code demotion
+outright. **This is a severity-tier fix for existing JS `<module>` findings
+too** — nothing new is detected by it, but any JS top-level finding that was
+previously silently demoted now reports at its correct severity.
+
+End-to-end coverage: `test/r14b-module-level-e2e.test.js` runs a real
+`runScan` against a minimal flat script in each of the three languages
+(plus Python's regex-fallback path separately) and asserts an `IR-TAINT`
+finding comes back — proving the PRD's actual success metric, not just
+correct IR shape. Wired into `test:dataflow`.
+
+**Verification — R14(b) only:** `test:dataflow` (625/625, includes the 4 new
+end-to-end tests), `npm test` (3176 tests, 0 failures on an isolated rerun —
+two transient `spawnSync`-timeout failures surfaced under heavy parallel
+system load on the first two attempts, in `audit-cli.test.js` and
+`triage-command.test.js`, neither of which this work touches, and both
+cleared on rerun), corpus (214/214, no drift), mutation (9/9 verdict-flip
+correct), layer-recall (no taint-layer regression; python/php/ruby taint
+counts unchanged from baseline, as expected — this work lands via dedicated
+unit tests, not new corpus entries) and self-scan (no drift).
+
+### Theme E (R14(a)) — annotation/decorator-shaped framework sources
+
+Closes the other half of Theme E's R14 item, left open when R14(b) landed.
+Framework sources expressed as parameter annotations/decorators — Spring's
+`@RequestParam`/`@PathVariable`/`@RequestBody`/`@RequestHeader`, ASP.NET
+Core's `[FromQuery]`/`[FromBody]`/`[FromForm]`/`[FromRoute]`/`[FromHeader]`,
+NestJS's `@Query()`/`@Body()`/`@Param()`/`@Headers()` — had no catalog
+representation at all: the catalog only matched callables and member reads,
+and an annotation is neither. A controller method whose only taint source
+was a decorated parameter was invisible to deep mode regardless of how
+directly it flowed to a sink.
+
+A new `annotation` catalog match kind (`dataflow/catalog.js`) is now
+consulted at every one of the taint engine's 8 `analyzeFunction` entry
+points via `_unionAnnotationTaint` (`dataflow/engine.js`), against a new
+IR side-channel field, `fn.paramAnnotations`, populated by three language
+extractors: `ir/parser-cs.js` (C#/ASP.NET Core attributes), `ir/parser-js.js`
+(NestJS decorators), and `ir/parser-java.js` (Spring annotations). The Java
+extractor also fixes a genuine, independent gap-fill that came bundled with
+the annotation work: Java parameter names were never extracted at all
+before this (`params: []` unconditionally) — real parameter names and
+Spring annotations are now both pulled from the same `formalParameterList`
+CST walk.
+
+**Accepted false-positive risk, documented rather than silently shipped:**
+matching is on the *bare* decorator/attribute name only (`ANNOTATION_INDEX`
+is keyed by `pa.decorator`, `dataflow/catalog.js`'s `matchAnnotationParams`)
+— there is no import-binding or namespace/package check confirming the
+decorator actually came from Spring/ASP.NET Core/NestJS. A user-defined
+decorator or attribute that happens to share one of these names (a custom
+`@Query()` in an unrelated JS library, a hand-rolled `[FromHeader]`
+attribute) would be treated as a tainted parameter source. This is the same
+risk class R6 (`docs/DETECTION_GAP_REMEDIATION_PRD.md`) already accepted and
+documented for bare-name sink matching before it grew a `receiverTypeIn`
+companion gate; R14(a) has no equivalent gate yet, and none of the three
+extractors have the type/import information available to build one today.
+Left as a known, accepted gap rather than blocking the whole feature on it.
+
+Per-task summary: Task 1 (catalog schema) needed one fix round (a missing
+provenance filter, a latent bug). Task 2 (engine plumbing across all 8
+`analyzeFunction` call sites) needed two: round 1's own review found the
+wiring solid but test coverage only jointly proved 2 of 8 sites, and while
+closing that gap it also made two wrong "impossible to isolate" claims about
+two further sites that the re-review refuted with real repros and round 2
+fixed properly. Two genuinely pre-existing, unrelated bugs were found along
+the way and logged in the PRD rather than fixed: a class-field cross-taint
+pass that has been dead code since v0.66.0, and a cross-file finding
+line-number mis-attribution bug. Task 3 (C# extraction) needed one fix round
+(stacked attributes on one parameter only captured the first) and surfaced a
+third data point for the PRD's own R8 item (parenthesized attribute
+arguments break the pre-existing C# method-detection regex), logged not
+fixed. Task 4 (JS/TS extraction) needed one fix round (a defaulted-parameter
+decorator was silently dropped by a type-check bug). Task 5 (Java extraction
++ real parameter extraction) needed one fix round (fully-qualified
+annotations recorded the wrong decorator name); its own review specifically
+investigated whether Java's dropped varargs parameters could cause
+positional param/annotation misattribution and confirmed they cannot, for
+any code that actually compiles.
+
+Task 6 (this entry) ran the full verification gate rather than trusting each
+task's own scoped tests, and it earned its keep twice over — two genuinely
+new, real issues, both fixed, neither papered over.
+
+First, the full `npm test` run (not exercised by any single task in
+isolation) surfaced a real gap: the four new NestJS catalog entries
+(`js-nestjs-query`, `js-nestjs-body`, `js-nestjs-param`, `js-nestjs-headers`)
+were missing the `provenance` label every JS source entry is required to
+carry (`test/phase7-extensions.test.js`, scoped to `test:sast`, which none
+of Tasks 1-5's own isolated `test:dataflow` runs exercised). Fixed by adding
+the same provenance values already used for the equivalent Express `req.*`
+sources (`url-param`/`http-body`/`path-param`/`header`).
+
+Second, `bench:self-scan:check` flagged a brand-new finding in
+`ir/parser-cs.js` itself: Task 3's new `attrRegex` had two independent
+`\s*` quantifiers both able to consume the same whitespace run when the
+overall match fails (no closing `]`) — a textbook adjacent-quantifier
+ReDoS. Verified as a genuine vulnerability, not a detector false positive,
+by direct timing measurement, end-to-end reachable through
+`parseCSharpFile` on an adversarial `.cs` file, not just an isolated
+microbenchmark: 2.4 seconds on a 64,000-character input, extrapolating to
+roughly ten minutes at 1MB.
+
+The first fix round moved the leading `\s*` inside the optional
+parenthesized-argument group — genuinely linear (re-verified: 0.49ms at
+200,000 chars) — but the engine's own `safe-regex`-backed ReDoS heuristic
+still flagged that version, so that round accepted a
+`bench/self-scan/BASELINE.json` bump (`ir/parser-cs.js: 3→4`) as the
+resolution. A task review caught that this repo already has precedent for
+a cleaner fix to the exact same situation: commit `6bd394c`
+(`class-hierarchy.js`) hit an identical "safe-regex flags a pattern that's
+actually safe" case and resolved it by restructuring into two
+independently-safe alternatives rather than accepting the drift, reasoning
+explicitly that this "avoids relying on any one detector's judgment call."
+Applying that same pattern here — two alternatives (no-args and
+with-args) instead of one optional group, decorator name read from
+`match[1] || match[2]` — passes `safe-regex` as `true`, independently
+re-verified linear (0.63ms at 256,000 chars), and produces byte-identical
+matches across a 12-shape sweep against the first round's already-fixed
+version. **No baseline bump was needed after all**:
+`bench/self-scan/BASELINE.json` was reverted to its pre-Task-6 state
+(`ir/parser-cs.js: 3`, `scanner/src` total 621) once the restructured
+regex stopped tripping the heuristic.
+
+**Verification — full gate re-run after all fixes:** `test:dataflow`
+670/670. `npm test` — all 12 scoped sub-scripts report `fail 0`
+(`test:smoke` 28, `test:glob`, `test:sast` 553, `test:posture` 1330,
+`test:dataflow` 670, `test:mcp` 102, `test:report` 111, `test:bench-modules`
+70, `test:lifecycle`, plus C++-dataflow and Python suites), no `npm error`
+anywhere in the run. `bench:cve-replay:check` 214/214 baselined entries, no
+drift. `bench:mutation:check` 9/9 verdict-flip correct (5/5 metamorphic
+hold, 4/4 adversarial flip). `bench:layer-recall:check` reports no
+taint-layer recall regression across any language — expected, since R14(a)
+lands via dedicated unit tests, not new corpus entries, matching R13's and
+R14(b)'s own precedent. `bench:self-scan:check` clean with **zero drift
+from the pre-Task-6 baseline** — the ReDoS false positive is gone rather
+than accepted, matching commit `6bd394c`'s own outcome exactly.
+`test/parser-cs-annotations.test.js` 5/5 after the restructure. Bundle
+rebuilt (`dist/agentic-security.mjs` + `.sha256`) after each regex change;
+`npm run smoke` against the rebuilt bundle correctly reports critical/high
+findings on the deliberately-vulnerable fixture (exit code 3, this CLI's
+documented "critical findings present" convention), and the underlying
+`test:smoke` suite (28/28) already passed as part of the full gate above.
+
+**Full Theme E (R13 + R14) is now complete.**
+
+### Theme C (R8) — braced control-flow body recursion, four languages
+
+Closes the single highest-leverage IR defect this project's whole
+detection-gap audit found. Java, C#, Kotlin, and PHP's statement splitters
+previously dropped or mangled the body of any braced control-flow statement
+(`if`/`for`/`try`/`switch`/`while`/`do`/`when`) — not just losing branch
+structure, but silently deleting the statements inside, or folding them into
+a bogus node. Since real-world sinks in these languages overwhelmingly sit
+inside exactly this shape (try-with-resources in Java, `using`/`try` in C#,
+`try`/`when` in Kotlin, `try`/`foreach` in PHP), this capped deep-mode taint
+recall near zero for all four regardless of any catalog or interprocedural
+work already landed elsewhere in this PRD. All four now recurse into these
+bodies with a real (statement-linear) CFG walk.
+
+- **Java** (`ir/parser-java.js`) — `walkStmts` additively extended to also
+  recurse into `for`/`try`/`switch`/`do`/bare-block statements. Fixed a
+  self-caught bug in the implementation plan's own draft code before it
+  shipped: try-with-resources' `catch`/`finally` were being read off the
+  wrong CST node, which would have silently dropped catch/finally for the
+  single most idiomatic JDBC pattern. One fix round closed two further
+  gaps: enhanced-for's loop variable now carries real taint provenance
+  (synthesized assign, mirroring `parser-js.js`'s `ForOfStatement`
+  pattern), and Java 14+ arrow-form `switch` (`case 1 -> …`) is now
+  recognized.
+- **PHP** (`ir/parser-php.js`) — the statement splitter now flushes on a
+  closing `}` (previously only `;`), with `try`/`switch` recognizers and a
+  recursion guard added. This was the hardest task in the plan (3 fix
+  rounds, all substantially about line-number precision, not detection
+  shape) — see `docs/DETECTION_GAP_REMEDIATION_PRD.md`'s R8 status entry
+  for the full round-by-round narration. Fixing the splitter this way also
+  resolved a pre-existing bug where `if`/`while`/`foreach` bodies were
+  already being mis-split before this task touched them.
+- **C#** (`ir/parser-cs.js`) — C# had no control-flow handling at all
+  before this; `_buildCfg` was built from scratch, ported from
+  `parser-cpp.js`'s proven recurse-into-braces pattern. One fix round:
+  `using (...) { }` and `lock (...) { }` bodies were invisible — `using`
+  being the canonical ADO.NET wrapper around exactly the sinks this task
+  targets, this was a real, significant gap.
+- **Kotlin** (`ir/parser-kt.js`) — new recursive `_buildCfg` mirroring C#'s,
+  with Kotlin-specific adaptations for its trailing-lambda call syntax and
+  `when` expression arms. Zero fix rounds during implementation — the
+  cleanest of the four tasks, in part because each implementer was briefed
+  on the previous tasks' hard-won lessons before starting.
+
+**Verification found and fixed a genuine regression this PRD's own new code
+introduced**, not papered over: `bench:self-scan:check` flagged
+`ir/parser-kt.js`'s new trailing-lambda regex as a ReDoS — the identical
+defect class as this same changelog's R14(a) C# `attrRegex` finding (an
+optional group sandwiched between two `\s*` quantifiers), independently
+confirmed genuinely quadratic by direct timing. Fixed the same way that
+precedent was: restructured into two mutually-exclusive alternatives,
+re-verified linear and byte-identical across a 15-shape sweep. A second,
+unrelated ReDoS in the same file's variable-declaration regex was found
+during that investigation and traced to a commit five months predating this
+PRD — left unfixed and logged as a candidate future item, since it wasn't
+introduced by this work.
+
+**Measured `bench/layer-recall` impact: 0 of 4 languages — an honest
+result, not the one originally expected, and corrected once more after
+this entry's first draft mis-attributed PHP's gain.** Baseline before:
+`java 1/25, kotlin 0/20, c# 1/21, php 1/23`. Measured after: `java 1/25
+(unchanged), kotlin 0/20 (unchanged), c# 1/21 (unchanged), php 2/23 (+1)`.
+PHP's `+1` is real, but it is **not R8's** — commit-swap A/B testing shows
+the pre-R8 `parser-php.js` still reproduces 2/23, while the pre-R14(b)
+`parser-php.js` (an earlier, unrelated PRD item — PHP's `<module>`
+top-level lowering) drops it back to 1/23. None of the corpus's `pre/`
+fixtures — the state the benchmark actually scores — place a sink
+genuinely inside a control-flow body for any of the four languages this
+task touched. The underlying capability this task fixed is completely real
+and independently proven, just not by this corpus: each language's own new
+dedicated `runScan` unit test (`test/parser-{java,cs,kt,php}-control-flow.test.js`)
+directly asserts a sink nested inside an `if`/`try`/`for`/`switch` body is
+now detected where it wasn't before. `bench/layer-recall/baseline.json`
+still updated to the measured counts (`entriesScored` 210→214, `php` 1→2,
+plus an unrelated `js/ts` 7→8 catch-up from this baseline file not having
+been regenerated since 2026-08-11 — no language decreased) — the baseline
+update is correct regardless of attribution, since it reflects the
+engine's actual current state. A follow-up item: this corpus needs a
+fixture per language with a sink genuinely inside a control-flow body (not
+a guard clause) before it can measure R8's impact at all.
+
+**Full gate:** `test:dataflow` 725/725 (rerun clean after the ReDoS fix).
+`npm test` — all 12 scoped sub-scripts green (`test:smoke` 28, `test:glob`
+13, `test:sast` 553, `test:posture` 1330, `test:dataflow` 725, `test:mcp`
+102, `test:report` 111, `test:bench-modules` 70, `test:lifecycle` 216,
+`test:eval` 23, `test:discovery` 79, C++-dataflow 26, plus the Python script
+suite). `bench:cve-replay:check` 214/214, no drift. `bench:mutation:check`
+9/9 verdict-flip correct. `bench:self-scan:check` clean with zero drift
+from the pre-R8 baseline after the fix.
+
+## 0.136.10 — detection-gap remediation Theme A: dedup, family, and calibration for deep mode
+
+An architectural audit of the SAST/taint pipeline (`docs/DETECTION_GAP_REMEDIATION_PRD.md`)
+found nine structural gaps behind missed real-world vulnerability classes. This
+release lands Theme A, the fixes on the production detection path:
+
+- **Dead-code demotion silently downgraded nearly every finding.** A field-name
+  mismatch (`.to`/`.size` vs the real `.callee`/Array shape) meant `calledQids`
+  was always effectively empty, so any function not named `handler`/`route`/
+  `controller`/`middleware`/`endpoint` — including most real sinks — got
+  demoted one severity notch on every deep-mode scan that ever ran.
+- **Half the sanitizer catalog was unreachable.** 191 of 381 sanitizer entries
+  use dotted callees (`Encode.forHtml`, `filepath.Clean`, `validator.isEmail`)
+  indexed under the full dotted key, but every lookup path reduced to the
+  callee's last segment — so these entries could never be retrieved. Catalog
+  lookup now tries the full dotted key before falling back to the last segment,
+  the behavior its own header comment already promised.
+- **A sanitizer-blind kill switch.** `builtin-summaries` deleted taint outright
+  at ~15 name-matched builtins (`parseInt`, `encodeURIComponent`,
+  `DOMPurify.sanitize`...) regardless of threat family, contradicting the
+  engine's own documented doctrine that sanitizers demote, never kill —
+  `x = encodeURIComponent(t); db.query(x)` silently lost its SQLi finding.
+  Now demotes through the same family-scoped sanitizer gate every other path
+  uses.
+- **Three bench-shape leaks were opt-out instead of opt-in**, violating this
+  repo's own documented convention (`AGENTIC_SECURITY_BENCH_SHAPE=1` to enable,
+  never `AGENTIC_SECURITY_BLIND_BENCH` to disable): a Juliet path-prefix
+  category filter with no env check at all, and two Java answer-key mechanisms
+  gated the wrong direction.
+- **Cross-file import resolution was dead code with zero callers.** `fileContents`
+  was never threaded into `buildCallGraph`, so its re-export/import-binding
+  resolution never ran — two same-named functions in unrelated files collided
+  by bare name on every scan.
+- **The points-to graph was built and then never wired in.** `AGENTIC_SECURITY_POINTS_TO=1`
+  computed a real alias graph but `runTaintEngine` never copied it onto
+  `callContext`, so the opt-in flag caught nothing. A second bug in
+  `aliasesForVar` (stripping only the first `::` instead of the qid's full
+  prefix) was fixed alongside it, since the qid itself always contains
+  multiple `::` segments.
+- **Guard recognition was flow-insensitive.** `dropGuardedFindings` matched a
+  guard-shaped regex anywhere in a −25/+5 line window with zero correlation to
+  the sink's actual tainted identifier, killing real SSRF/path findings
+  whenever unrelated guard-shaped text sat nearby. Rewritten to require the
+  guard match to appear near one of the sink's own argument identifiers.
+  Reachability annotation was also fixed to record "unknown" rather than
+  "unreachable" for languages with no call-graph data — only a strict `false`
+  should demote a finding, and absence of evidence isn't evidence of absence.
+- **Deep mode was unreachable from the MCP and LSP integration surfaces.**
+  `scan_diff` and `scanFile` never enabled deep mode, so the interprocedural
+  taint engine — the thing most likely to catch a real cross-function
+  vulnerability — never ran from either integration.
+- **Deep-mode (IR-TAINT) findings bypassed the entire finding pipeline.** They
+  were appended *after* dedup, clustering, stable-ID assignment, family
+  backfill, confidence, and calibration had already run once, so a sink caught
+  by both the regex layer and deep mode produced two findings — one of them
+  permanently unscored (no family, no calibrated confidence, no reachability
+  demotion, no mitigation annotation). Deep-mode findings now enter the same
+  pre-dedup pool as every other detector's output and ride the identical
+  pipeline. Fixing this exposed two further latent bugs it's now safe to state
+  plainly: dedup's winner-selection didn't prefer a real interprocedural
+  taint-walk finding over a same-severity flat pattern match at the same sink
+  (an IR-TAINT finding could lose a tie and take its sanitizer/chain evidence
+  down with it), and root-cause clustering keyed its "same sink" bucket on a
+  generic catalog rule id rather than a per-line signal, so two unrelated
+  `eval()` calls in one file could collapse into a single reported finding the
+  moment deep-mode findings started reaching that annotator. Both are fixed.
+
+Verification for all nine items: full test gate green, CVE-replay corpus
+214/214 with zero drift, metamorphic/adversarial mutation gate 6/6, self-scan
+precision gate re-baselined against three fully root-caused (not blindly
+accepted) drifts, and the pre-push gate's per-language taint-recall check
+confirmed no regression. `@vercel/ncc` (dev-only build dependency) was also
+bumped 0.44.1 → 0.45.0 to clear the release gate's dependency-currency check.
+
+R3 (route deep-mode findings through the full annotator pipeline) was the last
+item in Theme A. Themes B–E of the same PRD — semantic type/import-aware
+matching, control-flow-blind-parser fixes for Java/C#/Kotlin/PHP, deeper
+interprocedural completeness, and DOM/loop-element flow modeling — remain open
+and are tracked in `docs/DETECTION_GAP_REMEDIATION_PRD.md`.
+
 ## 0.136.9 — the real bug: the single-file bundle was never actually self-contained
 
 0.136.8's diagnostic logging answered the question immediately: