fix(codeql): bootstrap versioned dispatch handler

CHANGELOG.d/20260917-codeql-versioned-handler-bootstrap.md

@@ -0,0 +1,14 @@
+## Changed
+
+- Add a backward-compatible `codeql-scan`/`codeql-scan-v2` protocol bridge to
+  the single protected CodeQL dispatch handler. Legacy clients keep their
+  exact title, payload, and status context while v2 requires source/base/head
+  provenance. Language scans are `actions:read`; one post-matrix settlement
+  revalidates the live PR, required run/jobs, handler gate steps, and SARIF
+  artifacts before one run-wide rerun. The legacy path has an explicit
+  protected-v2/in-flight-drain/zero-caller removal condition. Failed
+  credential attempts retain their diagnostics but cannot leak an HTTP error
+  body into a later successful API response. Nested rerun authority is bound
+  to string schema `"1"`, and settlement stops before mutation when the
+  required run reaches attempt 48, preserving capacity below GitHub's limit of
+  50 re-runs. ADR-0025.

docs/adr/0025-codeql-required-workflow-dispatch-architecture.md

@@ -1,6 +1,6 @@
 # 0025 — Restore central CodeQL as a required workflow via repository_dispatch
 
-**Status:** Proposed, amended 2026-09-07 (one dispatch per pull request; language independence is the handler job matrix) · **Date:** 2026-09-03 · **Owner intent recorded:** loop-brief item 41
+**Status:** Proposed, amended 2026-09-12 (versioned handler-first bootstrap) · **Date:** 2026-09-03 · **Owner intent recorded:** loop-brief item 41
 
 ## Problem
 
@@ -306,3 +306,55 @@ blocker for this one.
    required `workflows` list (admin:org PUT, same mechanism used to remove
    it) and verify a real PR observes a successful, correctly-named required
    check before declaring this ADR's status Accepted.
+
+## 2026-09-12 amendment: versioned handler-first bootstrap
+
+The initial rollout created a protected-branch/client dependency cycle. A
+candidate producer can dispatch a stronger evidence envelope, but
+`repository_dispatch` always executes the handler from protected `main`.
+Conversely, landing the stronger handler first would reject the protected
+client's legacy payload and status context. This ADR therefore adopts a
+staged protocol on the single canonical handler; it does not create a copied
+workflow or permit branch-selected execution.
+
+The protected bootstrap accepts exactly two event types:
+
+- `codeql-scan` is temporary legacy v1. It keeps the protected client's
+  current run title, top-level `required_jobs`, and
+  `codeql-dispatch/<language>` status context. It rejects nested `pr_head`,
+  `producer_source_sha`, `rerun_request`, and explicit `rerun_mode` fields so
+  a v2 caller cannot downgrade its identity checks.
+- `codeql-scan-v2` is the proposed v2 contract. The event type is the version
+  discriminator and consumes no `client_payload` property. It requires the
+  versioned head envelope, exact synthetic merge `producer_source_sha`, live
+  base/head parent binding, base-bound status context, and exact handler
+  gate/SARIF/artifact evidence.
+
+Both modes share one repository-and-PR concurrency group and one post-matrix
+`settle-required-run` job. The matrix scan has `actions:read`; only settlement
+has `actions:write`. Settlement revalidates the open PR, repository, base ref
+and SHA, head ref and SHA, required run, complete required-job map, terminal
+handler jobs, gate steps, and non-expired SARIF artifacts before issuing one
+run-wide rerun request. The common concurrency identity prevents v1 and v2
+from becoming simultaneous writers during cutover.
+
+Live evidence for the amendment is recorded in
+`docs/doctoring/codeql-versioned-handler-bootstrap-20260912.md`. In short,
+handler run `34684228601` completed both language scans but its matrix-owned
+legacy wakes raced: Actions started the required run and Python received HTTP
+403. Later same-tuple handler runs were repeatedly cancelled by concurrency,
+including `34684575249`, leaving a clean scan without a converged terminal
+receipt. This is a settlement-timing defect, not a CodeQL finding.
+
+Landing sequence is normative:
+
+1. Land this dual-event, legacy-compatible handler from fresh protected main.
+2. Non-force restack the complete successor (#2040), switch its producer to
+   `codeql-scan-v2`, and generate fresh exact-head end-to-end evidence.
+3. Keep legacy v1 until the protected v2 producer is live, all in-flight v1
+   required runs are terminal, and repository-wide caller inventory is zero;
+   then remove v1 with its bridge tests in a separate proven cleanup.
+
+The ADR remains **Proposed** until that sequence passes ordinary protection
+and a real consumer reaches a successful required CodeQL conclusion. Open PR
+code is not production authority.

docs/doctoring/codeql-versioned-handler-bootstrap-20260912.md

@@ -0,0 +1,96 @@
+# CodeQL versioned handler bootstrap — 2026-09-12
+
+## Status
+
+Proposed repair from protected `main@691fb78932eff5fbe52db69077848134b0b4e053`.
+No merge or production claim is made here. The complete consumer successor is
+PR #2040, revalidated at current head
+`6476b919d3febf79cc53e71d6d60f15d7e83ced4`.
+
+## Exact live evidence
+
+PR #2040 predecessor head `a9b18b4b24980c7ceb8b8cc0d143a24db20c90bf`
+had successful Runtime Quality run `34684155351` (3,127 passed, 1 skipped,
+21 subtests; 100% statement, branch, and public-doc coverage), Security run
+`34684356405`, SAST run `34684356377`, and Python Security run `34684356416`.
+It had no unresolved review threads. The later current head `6476b919...`
+moves replay-guard tests without changing this handler source, but historical
+hosted results are not inherited. The current head is Draft and had no
+associated pull-request workflow runs in the connector snapshot. It therefore
+remains unmergeable through ordinary protection.
+
+Protected handler run `34684228601` is the smallest causal trace. Its Actions
+and Python scan, SARIF gate, artifact preservation, and status paths reached
+terminal completion. The Actions shard then woke the shared required run. The
+Python shard's independent wake received HTTP 403 because that run was no
+longer in the terminal-failed state. Same-repository/PR handler runs
+`34684373526`, `34684458709`, `34684518320`, and `34684575249` were then
+cancelled by the stable concurrency group while retries kept dispatching. In
+`34684575249`, Python produced clean scan evidence while its sibling and wake
+path did not converge. The repeated consumer symptom was a dispatched success
+with a pending terminal verdict.
+
+## Root cause
+
+The protected handler woke the required run independently from each matrix
+scan job. The first wake changed the run state before the second language
+could validate and mutate it. In addition, a candidate stronger consumer
+could not prove itself against protected `main`: the old handler lacked its
+source-bound title and base-bound receipt, while replacing the handler in one
+step would reject the still-protected legacy producer. Re-running either side
+alone reproduces the dependency cycle.
+
+## Repair contract
+
+One existing handler accepts `codeql-scan` legacy v1 and `codeql-scan-v2`.
+The event type is the explicit protocol version, avoiding an eleventh
+top-level `client_payload` property. v1 retains the current title, payload,
+and status context byte-for-byte at the boundary, while rejecting all v2-only
+identity fields. v2 requires the exact source/base/head evidence implemented
+by #2040. Both use the same scan implementation and one post-matrix settlement
+writer. No scan shard has `actions:write`.
+
+The bridge removal condition is executable policy: remove v1 only after a
+protected v2 producer is live, every in-flight v1 required run is terminal,
+and a caller inventory finds zero `codeql-scan` producers. Until then, v1 is a
+bounded compatibility port, not production authority for v2 consumers.
+
+## Verification and next action
+
+The bootstrap contract executes both payload shapes, rejects v2-to-v1
+downgrade fields, verifies one actions writer after the matrix, and preserves
+the legacy and base-bound contexts separately. The full repository suite and
+hosted exact-head checks must pass before ordinary merge. After bootstrap
+merge, #2040 must non-force absorb protected main, change only its producer
+event to `codeql-scan-v2`, and generate new end-to-end evidence; existing
+failed or queued runs are not inherited.
+
+PR #2106 review then exposed a credential-fallback contamination edge case:
+`gh api` may emit an HTTP error body to stdout before returning nonzero, so a
+failed credential's JSON could precede the later credential's successful
+response. A generic `{"message":"Forbidden"}` body was already discarded by
+the current `jq` projections and therefore was not RED. The corrected RED
+fixture emits `{"state":"closed"}`, a field the PR validator consumes: before
+the repair it is concatenated with the authorized response and rejects that
+valid fallback. `run_api` now captures each attempt and emits its body only
+after that exact attempt succeeds, preserving stderr diagnostics and the
+existing credential order without a temporary-file lifecycle.
+
+The overlapping predecessor PR #2105 retained two additional fail-closed
+guards that the first #2106 tree did not carry. Nested rerun authority now
+requires the exact string schema `"1"`; missing, numeric, and unknown schemas
+are rejected before checkout or mutation. The single settlement writer also
+validates the required run's positive integer `run_attempt` and stops before
+mutation when it reaches 48. GitHub documents that `run_attempt` begins at 1
+and increments for every re-run, while one workflow run permits at most 50
+re-runs; the cutoff therefore preserves attempts 49–51 for human recovery
+rather than consuming the native allowance automatically. The structured
+failure records the run, attempt, schema, languages, and handler identity.
+This integrates the valid #2105 delta into the backward-compatible legacy/v2
+bridge rather than choosing either incomplete branch unchanged.
+
+GitHub. (2026). *Re-running workflows and jobs*.
+https://docs.github.com/en/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs
+
+GitHub. (2026). *Variables reference*.
+https://docs.github.com/en/actions/reference/workflows-and-actions/variables

docs/product-technical-gap-baseline.md

@@ -11,7 +11,7 @@
 
 | Gap ID | 상태 | exact-head evidence | causal owner / next gate |
 |---|---|---|---|
-| CONTROL-OPENCODE-VCS-PYROOT-01 | **Source repaired on `main` (#2123 `ebc69a401`); image-path helper extracted + offline-proven under #2157 follow-up; hosted consumer step-#17 link still required to close the issue** | `contextual-orchestrator#1149@684cf28f`의 중앙 [OpenCode run 34701472466](https://github.com/ContextualWisdomLab/.github/actions/runs/34701472466) `coverage-evidence` job `103574547257`은 PR 코드를 실행하기 전에 immutable `fast-mlsirm@09f762d`의 `python/fast_mlsirm` import root를 찾지 못해 종료했다. 같은 head의 제품 테스트는 `3602 passed, 2 skipped`, native CodeQL·fuzz·SBOM·SAST·Strix는 성공했다. | `.github`의 `opencode-review-dispatch.yml`이 root/`src/`만 허용한 계약 drift를 소유했다. #2123이 `python/` candidates를 추가해 `main`에 병합했고, #2157 follow-up은 동일 로직을 `scripts/ci/resolve_opencode_base_vcs_import_root.sh`로 추출해 `tests/test_opencode_vcs_python_source_root_contract.py` fixture로 증명한다. Issue #2157 종료는 post-`ebc69a401` consumer `coverage-evidence`가 docker step #17을 통과한 job id를 문서에 링크한 뒤에만 한다. |
+| CONTROL-OPENCODE-VCS-PYROOT-01 | **Source repaired on `main` (#2123 `ebc69a401`); image-path helper extracted + offline-proven under #2157 follow-up; hosted consumer step-#17 link still required to close the issue** | `ContextualWisdomLab/contextual-orchestrator#1149@684cf28f`의 중앙 [OpenCode run 34701472466](https://github.com/ContextualWisdomLab/.github/actions/runs/34701472466) `coverage-evidence` job `103574547257`은 PR 코드를 실행하기 전에 immutable `ContextualWisdomLab/fast-mlsirm@09f762d`의 `python/fast_mlsirm` import root를 찾지 못해 종료했다. 같은 head의 제품 테스트는 `3602 passed, 2 skipped`, native CodeQL·fuzz·SBOM·SAST·Strix는 성공했다. | `.github`의 `opencode-review-dispatch.yml`이 root/`src/`만 허용한 계약 drift를 소유했다. #2123이 `python/` candidates를 추가해 `main`에 병합했고, #2157 follow-up은 동일 로직을 `scripts/ci/resolve_opencode_base_vcs_import_root.sh`로 추출해 `tests/test_opencode_vcs_python_source_root_contract.py` fixture로 증명한다. Issue #2157 종료는 post-`ebc69a401` consumer `coverage-evidence`가 docker step #17을 통과한 job id를 문서에 링크한 뒤에만 한다. |
 
 ## 1. 근거와 범위
 
@@ -2784,6 +2784,41 @@ prose" convention already stated in `CLAUDE.md`.
 
 ## Item 41: CodeQL PR `startup_failure` blocking merges org-wide — dispatch-safe re-admission in progress
 
+**2026-09-12 control-plane update — handler-first bootstrap Proposed.**
+Protected `main@691fb78932eff5fbe52db69077848134b0b4e053` still runs the
+legacy handler while complete successor #2040 is open at
+`6476b919d3febf79cc53e71d6d60f15d7e83ced4` (Draft at the latest live
+revalidation). Exact predecessor run `34684228601`
+proved the current per-language wake cannot converge: Actions woke the shared
+required run, then Python received HTTP 403; subsequent same-tuple handler
+runs were cancelled and redispatched, including `34684575249`. This is a
+canonical `.github` control-plane defect, not a consumer CodeQL finding.
+
+The minimum repair is one versioned handler, not a workflow copy. Temporary
+`codeql-scan` v1 preserves the protected client title/payload/status contract;
+`codeql-scan-v2` requires the source/base/head/SARIF evidence carried by
+#2040. Both share one repository/PR concurrency identity and a single
+post-matrix `actions:write` settlement. The scan matrix is read-only. v1 is
+removed only after the protected v2 producer lands, all v1 attempts terminate,
+and caller inventory reaches zero. Current status remains **Proposed**:
+bootstrap PR ordinary merge, #2040 non-force restack, and a fresh successful
+exact-head required CodeQL run are still required. ADR-0025 and
+`docs/doctoring/codeql-versioned-handler-bootstrap-20260912.md` carry the
+decision and exact evidence. Settlement credential fallback releases only the
+successful `gh api` body; its RED fixture uses a rejected
+`{"state":"closed"}` document because a generic error message does not exercise
+the consumed-field contamination path.
+
+The first overlapping successors were each incomplete in a different way:
+#2105 required v2-only producer provenance from the still-protected legacy
+client, while #2106 initially omitted #2105's nested-rerun schema and
+attempt-exhaustion guards. The canonical #2106 integration preserves its
+legacy/v2 event bridge and carries forward both valid #2105 guards: only string
+schema `"1"` grants nested rerun authority, and the settlement writer stops
+before mutation at required-run attempt 48. Status remains **Proposed** until
+the integrated exact head passes hosted checks and independent review, lands
+on protected `main`, and a fresh #2040 producer canary converges.
+
 **2026-09-04 correction.** The emergency ruleset removal below fixed the old
 entrypoint, but became stale after `.github#1778` moved `github/codeql-action`
 into the native `codeql-scan-dispatch.yml` handler. Seven current PR heads then