enhance(#3913): docs, and the guards come down (#3994)

ADR-3889 terminal phase. Generated docs/reference/exit-codes.md from the exit-code declaration with a --check drift arm; deleted the inert soft-error-exit-zero oracle; promoted untyped-success from SMELL to VIOLATION so it can fail a build; pruned all 5 smell-baseline entries.

Fixed inline: two mis-scoped oracles (routing-validity, value-hygiene), a second source behind the band table, unescaped declaration strings reaching Markdown, and a pre-existing Windows 8.3 short-name path-comparison defect.

Guard ledger corrected from a claimed net -4 to a measured net -1.

Closes #3913
This commit is contained in:
Tom Boucher
2026-08-28 13:10:20 -04:00
committed by GitHub
parent c3e667df34
commit 12f9d1d9a0
16 changed files with 1517 additions and 152 deletions

View File

@@ -36,6 +36,62 @@ const COMMANDS_DIR = path.join(__dirname, '..', '..', 'commands', 'gsd');
// Module-level memoization — set on first call, reused thereafter.
let _cache = null;
/**
* The exhaustive set of prefixes `getLiveCommandTokens()` ever emits — kept
* here, alongside the token-emission logic itself, as the single source of
* truth so a shape-based "does this string look like a live-command token"
* check (see `tests/qa/oracles.cjs` value-hygiene) never drifts from what
* this file actually generates. Every token this module produces is exactly
* `${prefix}${slug}` for one of these three prefixes — see the `tokens.add`
* calls in `getLiveCommandTokens()` below, which is the sole producer.
*/
const LIVE_COMMAND_TOKEN_PREFIXES = Object.freeze(['/gsd-', '/gsd:', '$gsd-']);
/**
* Extract the first whitespace-delimited "word" of a string, e.g.
* `"/gsd-plan-phase 2"` -> `"/gsd-plan-phase"`. Real command-token payloads
* carry trailing arguments (`init`'s `recommended_actions[].command` is
* literally `/gsd-plan-phase 2`), so an exact-match test against the WHOLE
* string would reject every argument-carrying token — the token itself is
* always the first word.
*
* @param {string} value
* @returns {string}
*/
function firstToken(value) {
const match = value.match(/^\S+/);
return match ? match[0] : value;
}
/**
* Is `value`'s first whitespace-delimited word an EXACT member of
* `liveTokens` (a `Set<string>`, normally `getLiveCommandTokens()`)?
*
* This is the SOLE shared predicate behind every "is this string a live
* command token" check in the QA harness — `tests/qa/oracles.cjs`'s
* `value-hygiene` command-token exemption and its `routing-validity` check —
* so the two can never independently drift on what counts as a live command
* token (#3913 P9 security review: this is the THIRD iteration of that
* exemption. First it was keyed on the leaf name `command`; then on a bare
* `String.startsWith` prefix test with an unconstrained remainder, which
* exempted any string merely SHARING A PREFIX with a real token — e.g.
* `/gsd-x/../../../Users/someone/.ssh/id_rsa` or `/gsd:/etc/passwd` both
* satisfied `startsWith('/gsd-')`/`startsWith('/gsd:')`).
*
* Deliberately NOT a `startsWith` fast path over `LIVE_COMMAND_TOKEN_PREFIXES`
* short-circuiting this check: exact membership of the first word is the
* WHOLE predicate, so a leaked path can never pass merely by sharing a
* token's first few bytes.
*
* @param {unknown} value
* @param {Set<string>} liveTokens
* @returns {boolean}
*/
function isLiveCommandToken(value, liveTokens) {
if (typeof value !== 'string') return false;
return liveTokens.has(firstToken(value));
}
/**
* Parse the YAML frontmatter `name:` field from a command file's content.
* Returns the slug (e.g. "help", "plan-phase", "context") or null if the
@@ -129,4 +185,4 @@ function getLiveCommandTokens() {
return _cache;
}
module.exports = { getLiveCommandTokens };
module.exports = { getLiveCommandTokens, LIVE_COMMAND_TOKEN_PREFIXES, firstToken, isLiveCommandToken };