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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user