maven-multi-branch-license-gate-hardening

Multi-branch License Gate Hardening

Core principles

Treat each maintenance branch as an independent release line. A branch may be declared passing only when the license, SBOM, complete Reactor, remote SHA, and required CI all close on the same branch's final SHA; the overall effort may be declared complete only when all target branches pass.

This Skill is intended for Maven multi-branch release maintainers, release engineers, and auditors. It does not replace the project's own JDK/Maven/POM contract, license policy, or required CI check configuration.

Quick start

You can directly ask:

• "Audit the license gate for these three maintenance branches and provide a gap matrix."
• "Check whether the SBOM, Reactor, push, and CI evidence close on the same SHA."
• "Can this module re-run after a temporary port conflict serve as complete Reactor evidence?"

First read the project instructions, existing plan/specifications, and each branch's toolchain contract, then build an evidence matrix with one row per branch. Stay read-only when the user only requests analysis; commit, push, re-running CI, or modifying license configuration all require being within an explicitly authorized scope.

Capability boundaries

Good at

• Auditing license source evidence, selection tables, exclusion tables, and generated reports across multiple maintenance branches.
• Verifying that CycloneDX/SPDX SBOMs are consistent with the actual dependency graph, final commit, and release scope.
• Distinguishing complete Maven Reactor, target-module re-verification,-rf resume-from execution, and CI-equivalent verification.
• Checking local HEAD, tracking ref, remote SHA, and the required CI triggered by that SHA.

Materials needed

• Branch/worktree inventory, and the JDK, Maven/Wrapper, and build commands specified for each line.
• Project license policy, SBOM configuration, required CI names, and the authorized scope of changes/pushes.
• Command logs, report paths, remote SHA, or CI run/job identifiers; if missing, first output unknown gaps, do not guess.

Out of scope

• Do not disguise legal judgments as engineering conclusions; when license compatibility is disputed, refer to legal or project governance.
• Do not automatically choose licenses, fabricate evidence URLs, relax required CI, or write security scan skipped as passed。
• Do not create/switch branches, rewrite history, commit, push, re-run, or cancel CI without authorization.

Workflow

1. Freeze scope and branch contracts

For each line, record: repository root, worktree, branch, target SHA, JDK, Maven/Wrapper, POM topology, release scope, required CI. First check git status, protect the user's uncommitted changes. Multiple repositories or worktrees must not mix paths, logs, or SHAs across lines.

If the project already has a formal specification or execution plan, continue from the current stage; do not create duplicate sources of truth for the same change.

2. Build the evidence matrix

Allowed statuses are only:passed、failed、in_progress、blocked、skipped、unknown。skipped must include authorization and risk, and never equals passed。

Branch	SHA	Toolchain	Dependency sources	License policy	SBOM	Complete Reactor	local/tracking/remote	Required CI	Summary
<line>	<sha>	<state>	<state>	<state>	<state>	<state>	<state>	<state>	<state>

Attach reviewable evidence to each cell: actual commands, exit codes, report/log paths, dependency coordinates and versions, URLs and response semantics, run/job URLs or IDs, observation time. HTTP 200 only proves accessibility; it does not by itself prove that license semantics are correct.

3. Handle licenses and SBOMs

1. Locate the exact groupId:artifactId:version and introduction path from the dependency tree or the resolved model.
2. First check whether the code directly depends on the relevant API, then choose precise exclusion, upstream fix, or a governance-approved license choice.
3. The license source must be traceable to that exact version; prefer pinned versions, immutable POM/source tags, or official repository content.
4. After the change, regenerate the license report and SBOM, and prove that the old coordinates/stale choices are gone while the expected dependencies are still present.
5. When sharing scripts across branches, compare content, invocation method, and file modes; a consistent shared implementation does not mean validation from each branch can be reused.

Do not choose a license without reliable evidence just to make the gate green. If a transitive dependency is excluded, you must supplement the dependency tree, contract/integration tests, and a new SBOM to prove it no longer enters the deliverable.

4. Close the full Reactor

Each line uses its real toolchain to run the project-defined full Reactor. Record the command, tool versions, start and end times, module/test counts, and final exit code.

• Rerunning only the target module supports diagnosis only and does not automatically replace the full Reactor.
• A fresh, successful full Reactor is the clearest closure evidence after a transient environment failure.
• Only accept -rf evidence chain when it can prove the modules that succeeded before the failure, the recovery point, all subsequent modules, and that the source/SHA/parameters are unchanged; otherwise the status is still not passed。
• "Partial success before failure + single-module success" must not be pieced together into all green.

5. Commit and push

Before committing, check the diff, unexpected files, generated artifacts, byte consistency of scripts, and file modes branch by branch. Freeze the SHA after committing; any modification will require re-evaluation of that line's prior SBOM, Reactor, or CI evidence based on the old SHA.

Push proof must include at least: local HEAD, tracking ref, and remote branch SHA all match.git push Returning success only proves transmission; it does not prove the final remote state or CI passing.

6. Wait for CI

Track only the required workflow/job triggered by the final SHA. State machine:

flowchart LR
  A[最终 SHA 已推送] --> B{必需 CI 最终结论}
  B -->|queued / in_progress| C[继续等待并保持 in_progress]
  C --> B
  B -->|failure / cancelled| D[保留日志并分类根因]
  D --> E{需要修改源码或配置?}
  E -->|是| F[产生新 SHA 并使旧证据失效]
  F --> A
  E -->|否，允许重跑| B
  B -->|success| G[该 SHA 的 CI 证据闭合]

Use conditional waiting and reduce polling frequency; report substantive status changes.queued、in_progress, the job has started, a step is installing dependencies, or there is temporarily no failure signal are not passing.

7. Give a conclusion

Write the verdict first, then the evidence and gaps:

判定：passed | partial | failed | blocked
范围：<分支与最终 SHA>
已闭合：<逐项列出>
未闭合：<状态、缺少的具体证据、如何补充>
异常分类：change-related | environment-transient | infrastructure | unknown
剩余风险：<skipped/例外/法律争议/未复核项>
下一动作：<最小且可执行的动作>

The overall completion condition is that all required cells for all target lines are passed. Otherwise use partial、failed or blocked, and make clear that "committed and pushed" and "passed CI" are different stages.

Evidence stitching rules

Scenario	Can it be stitched	Condition
Local gates, remote SHA, and CI on the same branch	Yes	Same final SHA, correct toolchain, consistent scope
Multiple branches sharing the same immutable license original source	Conditional	Exact coordinates are the same; each line still independently generates an SBOM and runs the policy
Failed Reactor + -rf	Conditional	Can prove complete module coverage and that the code/parameters/SHA are unchanged
Failed Reactor + single-module re-verification	No	Can only support root cause classification
Old SHA report + new SHA CI	No	Evidence identity inconsistency
CI started/in_progress + no failures	No	No final success conclusion yet

Common mistakes and red flags

• Seeing HTTP 200 and claiming the license evidence is valid.
• Treating a generated SBOM as proof that the SBOM matches the final dependency graph.
• Using a successful result from the wrong JDK/Maven in place of the maintenance line contract.
• Using success on one branch to represent success on all branches.
• Declaring overall completion based on push output, CI startup, or partial tests.
• Directly ignoring temporary environment failures instead of closing the full Reactor.
• The log path has no branch identifier, causing evidence to be crossed.

When any red flag appears, stop the "complete" claim and return to the evidence matrix to locate the first non- passed cell.

FAQ

Q1: Can the three lines be verified in parallel? Yes, as long as the toolchain, cache, ports, logs, and worktrees are isolated, and the output can be mapped back to their respective SHAs.

Q2: Can CI replace the local Reactor? Only if the project gate allows it and that CI executes an equivalent or stronger full scope on the final SHA; the license/SBOM job name itself cannot prove full Reactor coverage.

Q3: How should delivery status be handled while CI keeps running? Write in_progress, explaining the closed items, the jobs currently executing, the latest substantive progress, and why completion still cannot be declared.

Q4: Can an old license URL be reused? Only if the exact version and content identity still match and the source can be reviewed; policy and SBOM still need to be rerun on the current branch.

Q5: What if Security is explicitly exempted? Record skipped, the authorization source, and the residual risk; it must not be written as a passed security scan.

Q6: What if the user only wants an audit and no modifications? Output only the matrix and recommendations, do not generate reports, do not modify the POM, do not commit, do not push, and do not rerun CI.

In-depth reference

• When you need the evidence fields, anomaly classification, and acceptance rules for each gate, read references/evidence-contract.md。
• When encountering partial reruns, cross-SHA, CI waiting, or security/privacy boundaries, read references/anti-patterns.md。
• When handling edge cases or custom organization gates, read references/faq-deep.md。