Commit df28bfb

and gate their steps instead, because GitHub evaluates job conditions before

expanding a matrix. Skipping the matrix job itself may leave its named

required contexts unreported.

expensive steps are gated. This preserves the existing check names without a ruleset change; live

verification is still pending.

The audit at `687f8489d` checked references to the allowlisted paths and their

file names across tracked source, tests, build scripts, and CI configuration.

It also checked package build entry points, test discovery, asset copying,

Turbo inputs, and VSIX packaging rules.

| Surface | Evidence | Result |

| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| Extension bundling | `src/esbuild.mjs` calls `copyPaths()` with an explicit source list. `packages/build/src/esbuild.ts` copies only those configured paths. | Root `README.md` and `CHANGELOG.md` are package inputs and remain outside the allowlist. No allowlisted documentation is copied. |

| VSIX packaging | `src/.vscodeignore` excludes everything, then includes the built extension, webview, assets, and release metadata. | Root `docs/`, `.github/`, and the four allowlisted root files are not packaged. |

| Webview and package builds | `webview-ui/vite.config.ts`, `apps/cli/tsup.config.ts`, and `packages/types/tsup.config.ts` select code entry points and assets. | No imports, raw-file loads, or asset rules select allowlisted documentation. |

| Tests and models | Vitest configurations select code tests. Searches covered `docs/`, current documentation basenames, Markdown imports, and filesystem readers. | Documentation references are comments, temporary repository files, mocked paths, or workspace examples. Tests do not read the checked-in allowlisted documents. |

| Turbo and Knip | Root and package Turbo files define package-local inputs. `knip.json` selects code entry points and projects. | No explicit input reaches the root documentation tree. Default package inputs can include package-local Markdown, which remains outside the allowlist. |

| Release validation | `.github/workflows/release-validation.yml` builds the extension and compares root `README.md` with the copied package README. | Release inputs retain full validation. The release workflow is unchanged. |

Generic runtime tools can read Markdown in a user's workspace. This does not

make repository documentation a build or test input. The audit found no reason

to narrow the current allowlist further. This is source-level evidence for the

current tree, not a guarantee about future consumers. A new documentation

reader must update the classification policy and its regression tests.

No live docs-only PR run has confirmed the two platform check contexts yet.

Local workflow tests verify their names and wiring; this does not establish

GitHub's live check-reporting behavior.

`format-check` and all `validation-gate` jobs are not required checks in the

current ruleset. Formatting and policy-test failures block via required

`compile`. Making audit-gate failures block directly still requires a separate

ruleset update. The gate reads job results and cannot observe step-level gating

inside `compile` or `unit-test`; workflow tests pin those step conditions.

All label changes currently start all five workflows and may cancel in-flight

PR validation, including mutation testing. This runner-time cost is accepted

for now to keep override event handling simple and consistent. A shared gate

action and broader Stryker integration remain follow-ups.

const characters = Array.from(String(value))

// Encode punctuation before Markdown parsing; cap individual paths in summaries.

const text = characters.slice(0, 500).join("")

return (

text.replace(/[^\p{L}\p{N} /-]/gu, (character) => `&#${character.codePointAt(0)};`) +

(characters.length > 500 ? "…" : "")

)

assert.ok(summary.includes("docs/pr.md"))

assert.ok(summary.includes("docs/`<details>|
forged.md"))

const cases = [

{ name: "docs skip", actual: "skipped", status: 0 },

{ name: "unexpected run", actual: "success", status: 1 },

{ name: "label", actual: "success", category: "full", reason: "override-label", label: "true", status: 0 },

{

name: "variable",

actual: "success",

category: "full",

reason: "override-variable",

variable: "true",

status: 0,

},

{

name: "label wins",

actual: "success",

category: "full",

reason: "override-label",

label: "true",

variable: "true",

status: 0,

},

{

name: "draft",

actual: "skipped",

rule: "pr-non-draft",

draft: "true",

category: "full",

reason: "override-label",

label: "true",

status: 0,

},

{

name: "ready",

actual: "success",

rule: "pr-non-draft",

category: "full",

reason: "override-label",

label: "true",

status: 0,

},

{ name: "missing event", actual: "skipped", event: "", error: /EVENT_NAME is required/, status: 1 },

{ name: "missing watches", actual: "skipped", watch: "", error: /WATCHED_JOBS is empty/, status: 1 },

{ name: "missing needs", actual: "skipped", needs: "{}", error: /missing/, status: 1 },

{ name: "missing base", actual: "skipped", base: "", error: /--base and --head are required/, status: 1 },

]

for (const testCase of cases) {

const { actual, status } = testCase

const summary = path.join(tempRepo, `summary-${testCase.name}.md`)

testCase.base ?? base,

EVENT_NAME: testCase.event ?? "pull_request",

WATCHED_JOBS: testCase.watch ?? `expensive:${testCase.rule ?? "always"}:gated`,

NEEDS_JSON:

testCase.needs ??

JSON.stringify({

classify: {

result: "success",

outputs: {

category: testCase.category ?? "docs-only",

"reason-code": testCase.reason ?? "allowlisted-documentation",

},

},

expensive: { result: actual },

}),

FORCE_FULL_LABEL: testCase.label ?? "false",

PR_DRAFT: testCase.draft ?? "false",

FORCE_FULL_VARIABLE: testCase.variable ?? "false",

assert.equal(result.status, status, `${testCase.name}: ${result.stderr}`)

if (testCase.error) {

assert.match(result.stderr, testCase.error)

continue

}

for (const filename of ["docs/space name.md", "docs/日本語.md", "docs/line\nbreak.md", "docs/UPPER.MD"]) {

it(`classifies the real git path ${JSON.stringify(filename)}`, () => {

const tempRepo = createTempRepository()

try {

const base = git(tempRepo, ["rev-parse", "HEAD"]).trim()

fs.writeFileSync(path.join(tempRepo, filename), "# documentation")

git(tempRepo, ["add", "."])

git(tempRepo, ["commit", "-m", "add unusual path"])

const head = git(tempRepo, ["rev-parse", "HEAD"]).trim()

const { entries } = changedEntries(tempRepo, base, head)

assert.deepEqual(entries, [{ status: "A", path: filename }])

assert.equal(classifyEntries(entries).category, filename.endsWith(".MD") ? "full" : "docs-only")

} finally {

fs.rmSync(tempRepo, { recursive: true, force: true })

}

})

it("requires full validation for a real documentation-to-source rename", () => {

const tempRepo = createTempRepository()

try {

const base = git(tempRepo, ["rev-parse", "HEAD"]).trim()

fs.mkdirSync(path.join(tempRepo, "src"))

git(tempRepo, ["mv", "docs/base.md", "src/source.md"])

git(tempRepo, ["commit", "-m", "move documentation into source"])

const head = git(tempRepo, ["rev-parse", "HEAD"]).trim()

const { entries } = changedEntries(tempRepo, base, head)

assert.deepEqual(entries, [{ status: "R", oldPath: "docs/base.md", path: "src/source.md" }])

assert.equal(classifyEntries(entries).category, "full")

} finally {

fs.rmSync(tempRepo, { recursive: true, force: true })

}

it("fails closed when a shallow clone lacks the base commit", () => {

const tempRepo = createTempRepository()

const clone = fs.mkdtempSync(path.join(os.tmpdir(), "classification-shallow-"))

try {

const base = git(tempRepo, ["rev-parse", "HEAD"]).trim()

fs.writeFileSync(path.join(tempRepo, "docs/base.md"), "updated")

git(tempRepo, ["add", "."])

git(tempRepo, ["commit", "-m", "docs"])

const head = git(tempRepo, ["rev-parse", "HEAD"]).trim()

git(tempRepo, ["clone", "--depth=1", `file://${tempRepo}`, clone])

assert.equal(git(clone, ["rev-parse", "--is-shallow-repository"]).trim(), "true")

assert.throws(() => changedEntries(clone, base, head), /Could not resolve base commit/)

assert.equal(validationPolicyChanged(clone, base, head), true)

} finally {

fs.rmSync(tempRepo, { recursive: true, force: true })

fs.rmSync(clone, { recursive: true, force: true })

}

it("renders formatting and autolink punctuation as literal filename characters", () => {

const filename = "docs/[link](https://example.com)*_~#@!\\.md"

const summary = formatSummary(classifyEntries([{ status: "M", path: filename }]))

const line = summary.split("\n").find((line) => line.startsWith("- docs/"))

assert.equal(

line,

"- docs/[link](https://example.com)*_~#@!\.md",

)

it("caps long filename summaries", () => {

const filename = `docs/${"a".repeat(600)}.md`

const summary = formatSummary(classifyEntries([{ status: "M", path: filename }]))

const line = summary.split("\n").find((line) => line.startsWith("- docs/"))

assert.equal(line, `- docs/${"a".repeat(495)}…`)

assert.deepEqual(

Object.keys(jobs).sort(),

["classify", "validation-gate", ...expectation.jobs.map((job) => job.id)].sort(),

)

assert.equal(jobs.compile.name, undefined)

assert.equal(jobs["unit-test"].name, "platform-unit-test (${{ matrix.name }})")

assert.equal(

jobs[id].env.RUN_VALIDATION,

"${{ needs.classify.result != 'success' || github.event_name != 'pull_request' || needs.classify.outputs.category != 'docs-only' }}",

)