docs(#2665): document the two live-config-guard env vars

The changeset for this PR is typed `Added`, and CONTRIBUTING requires a docs/
change for that type. The only docs/ file in the diff was CONTEXT-INDEX.json --
a GENERATED index -- so the Docs Required gate passed while no human-readable
documentation existed for either new variable. A gate satisfied by a generated
artifact is satisfied vacuously.

docs/TESTING-SUITES.md now carries a section on the guard: what it watches and
why it is ownership-scoped rather than whole-root, the two env vars in a table,
why the default is report-only and what the promotion condition is, and what
each violation label means (including that UNVERIFIED is not clean).

GSD_SKIP_LIVE_CONFIG_GUARD is named explicitly because it is a bypass on a
safety check. An undocumented bypass is one people eventually set without
knowing what they turned off.

A test asserts both variables appear in that doc -- checked as permitted by
local/no-source-grep before writing it, rather than assumed forbidden. It fails
when the section is removed, so the doc cannot rot back to the state the review
found.

Addresses review finding: Major 4.
This commit is contained in:
0xdhx
2026-08-06 16:40:34 -05:00
parent f0ef9063d5
commit e31f706ceb
2 changed files with 52 additions and 0 deletions

View File

@@ -606,6 +606,17 @@ describe('#2665 round 4: CI wires the guard to strict mode', () => {
// green. Windows lanes are deliberately report-only until the documented
// pre-existing USERPROFILE leak class is swept (SEVERITY note in
// scripts/live-config-guard.cjs) — so the assertion is per-OS, not global.
test('both guard env vars are documented for humans, not just in the source', () => {
// A skip-switch on a safety guard has to be discoverable: an undocumented
// bypass is one people eventually set without knowing what they turned off.
// The Docs Required gate gets satisfied by ANY docs/ file in the diff --
// including a generated index -- so it cannot stand in for this.
const doc = fs.readFileSync(path.join(__dirname, '..', 'docs', 'TESTING-SUITES.md'), 'utf8');
for (const v of ['GSD_STRICT_LIVE_CONFIG_GUARD', 'GSD_SKIP_LIVE_CONFIG_GUARD']) {
assert.ok(doc.includes(v), `${v} must be documented in docs/TESTING-SUITES.md`);
}
});
// DERIVED, not hand-listed. The previous version named three jobs as literals,
// so it could not see a FOURTH lane that runs the suite — and there was one:
// qa-loop-walk reaches run-tests.cjs through `npm run test:qa` and escaped