Repository navigation
test(docs): make startup-reason vocabulary extraction exhaustive #4055
Description
Parent: #4045
Purpose
literalMembers regex reads only single-quoted lowercase/underscore strings and selected spreads. Valid literals with digits/hyphens or alternate quoting can be silently ignored while the nonempty check passes.
Owner and scope
test/repo-guards/runner-startup-reason-docs.test.ts and local parser support if needed. Reuse existing exports/parser; retain documentation completeness.
Required behavior
Prefer importing the exported RUNNER_STARTUP_FAILURE_REASONS runtime vocabulary and delete the regex path while retaining independent documentation comparison. If a concrete layering constraint prohibits that import, use the repository parser and reject every unsupported member exhaustively. Do not add a compatibility fallback or general source-evaluation framework; choose one justified construction path. Do not change production reason vocabulary.
API or evidence example
A valid added reason such as 'phase-2' must either be included in the checked vocabulary or cause an explicit unsupported-shape failure.
Observable completion
- Valid literals cannot silently disappear because of spelling/quote format.
- Unknown spread/member syntax fails explicitly if it cannot be interpreted safely.
- Existing reason-doc coverage still detects a missing documented reason; parser tests prove nearest ignored-literal case.
Dependencies and sequencing
Blocked by: none.
Validation
Focused repo guard and isolated planted new-reason experiment; preserve runner inclusion; format and selected checks.
Base audit SHA: 144bd59890277fd4717995588ad817597c9d6552. Re-read the issue and all Decision: comments before work. Read applicable AGENTS.md routes. Keep one owner boundary per PR. Independent review and serialized exact-head validation are coordinated by the umbrella orchestrator.
Activity
thymikee commentedon Oct 29, 2026
Decision: the direct-import preference is blocked by R11.
RUNNER_STARTUP_FAILURE_REASONSis exported only from the private source modulepackages/platform-apple/src/runner/runner-error-classification.ts; the package exports neither that module nor the value through its public runner facade. The worker import from roottest/intopackages/*/srcwould fail the relative-tunnel invariant. Do not add a test-only production export or bypass the boundary dynamically.Use the alternative explicitly permitted by this issue: the existing OXC parser, confined to this guard, reads the two known exported array declarations. Accept string literals and only the known readiness spread from the startup list; reject every unsupported member, spread, array hole or declaration shape. Add nearby positive/negative parser cases while retaining the independent two-doc comparison. No production vocabulary changes. Parent will prove a double-quoted hyphen/digit reason is detected in disposable checkouts after the host gate lock clears.
thymikee commentedon Oct 29, 2026
Current state: head
59d1aba75ba66c57d84b379b6e4eed4fee782d9chas independent Sonnet approval and3focused tests passing. Parent isolated proof used frozen install/build and identical two-worker guard command filtered to the production docs comparison. On unchanged base144bd59890, adding double-quoted"phase-2"still passed1test: the original regex silently missed it. At the current head, baseline1passed /2skipped; the same added reason failed1 /2skipped withinstallation.md must document the phase-2 reason. After adding the reason only to that sentence, the identical command still failed1 /2skipped withcli-help.ts must document the phase-2 reason. Detection is proven at both independent surfaces. All disposable checkouts were removed; reviewed SHA/status unchanged. No production reason or documentation mutation was retained. Exact-head affected validation/publication remain pending.