docs: document BRANCH and DEBUG, and info as a severity threshold

[joeymussalli]

Three gaps in the root README's inputs table, all cases where the script reads something the table does not mention.

BRANCH and DEBUG are both read (the script's own header comment lists them) but neither appears in the table, so the only way to discover them is to read the source.

BRANCH is not a nicety. The script works out the branch and repository three ways and on CodePipeline -- the primary integration here -- all three miss. CODEBUILD_WEBHOOK_HEAD_REF is documented as the head ref "of the webhook event that triggers the current build", so it is unset for pipeline-triggered builds. CODEBUILD_SOURCE_REPO_URL "may be empty" when the build originates from CodePipeline. And a pipeline source artifact is an unzipped snapshot with no .git for the final fallback. So every report and every trustabl-summary.md in that integration reads Repository: . / Branch: unknown, and the one variable that fixes it was undocumented.

SEVERITY_THRESHOLD was documented as accepting
none/low/medium/high/critical, but sev_rank ranks info at 0 and MAX_SEV can be info, so SEVERITY_THRESHOLD=info is accepted and does fail the build on info-only findings. Worth stating, because docs/EVALUATION.md says "info and META signals never fail a build on their own" -- true of the default, not true once you set this.

• Add BRANCH and DEBUG rows.
• Add info to the documented severity set.
• Add a short section explaining why BRANCH is needed on CodePipeline, with the reasoning rather than just the instruction.

Documentation only; no code changes.

Refs: https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html

[joeymussalli]

Closing as a duplicate of #19 (bradAGI) documenting BRANCH and DEBUG.

[joeymussalli]

Reopened — closed earlier by mistake. Leaving this up per author request.

[sairenchristianbuerano]

Thanks @joeymussalli. Flagging that this is being read rather than sitting unlooked-at.

We are reviewing all 52 open PRs together instead of one at a time. 31 of them edit scan/trustabl-scan.sh, so merge order decides as much as any individual verdict — GitHub reports almost all of these as mergeable, but that is each PR against main in isolation, not against each other. The first merge makes most of the rest conflict.

Reading against #19, which documents the same two inputs.

The order we are working to: the test harness in #1 first, since twelve PRs depend on it and nothing is verifiable without it, then the fixes that close fail-open paths, then behaviour changes, then docs. A verdict on this one follows once its cluster is read.

Apologies for the wait, and thanks for the contribution.

[sairenchristianbuerano]

Thanks @joeymussalli — the change looks good, but it needs a rebase.

Several PRs touching scan/trustabl-scan.sh have landed on main since you opened this, so it no longer merges cleanly. Could you rebase and resolve?

bash test/run-tests.sh will confirm it — 19 passing on main right now.

Ping me when it's up.