fix(schema-hygiene): retire //-stub pattern + drop unvalidatable skillOverrides

[tigers1997]

Summary

Dogfood from upgrading an adjacent project surfaced two real Claude Code settings-validator complaints. Both are configurator bugs introduced by PRs #17, #18, #56, and #57.

Bug 1 — skillOverrides: "name-only" (string form, PR #57). The current Claude Code schema requires the per-skill object map ({"skill-name": "name-only"}); the string form was based on an incorrect assumption documented in the tier-pro patch's // comment. Verified against code.claude.com/docs/en/settings: only object form is documented, and the setting explicitly does not apply to plugin skills, further narrowing its usefulness as a tier-wide default.

Bug 2 — // foo "commented opt-in stub" pattern (PRs #17, #18, #56). These literal top-level keys propagate from source patches into the user's .claude/settings.json, where Claude Code's editor schema rejects them as unknown properties. PR #56's _is_doc_label filter intentionally kept // foo keys while stripping bare // and //<digits>; the dogfood proves that intent was wrong.

Third bug found during verification: compute_merged_settings applies the doc-label filter to file-based patches (lines 473, 488) but bypasses inline extraSettings (line 477-478). The ui module's bare "//" keys were also leaking to user settings.json — not just the // foo stubs.

What changes

File	Change
configure.py	_is_doc_label strips ALL //-prefixed keys; new _strip_doc_labels() recursive helper applied at end of compute_merged_settings; extraSettings merge filter added; new check_settings_validates() runtime preflight; new static --check step asserts skillOverrides shape
templates/token-efficiency/settings-patch.tier-pro.json	Deleted skillOverrides: "name-only"; replaced docstring with corrected rationale
templates/safety/settings-patch.json, templates/multi-agent/settings-patch.json, templates/git-workflow/settings-patch.json	Deleted all // foo opt-in stubs; updated //N docstrings to point at the new opt-in home
config_schema.py (ui module)	Deleted inline // hideVimModeIndicator + // subagentStatusLine from extraSettings
templates/core/dot-claude/settings.local.json.example	New home for user-discoverable opt-in stubs (the .example suffix means CC doesn't parse this file directly, so // foo stubs are safe). Covers: sandbox, worktree, prUrlTemplate, subagentStatusLine + sibling notes on hideVimModeIndicator, skillOverrides
test/schema-hygiene/	4 new tests covering: no-stubs-rendered (all 5 personas), skillOverrides shape, preflight detection (4 violation classes), recursive strip invariant
CHANGELOG.md	Entry under ## Unreleased

Verification

The new static --check step fires on the current bug when run for the first time (before the fix is applied). After the fix:

✓ all checks passed
  modules: 12
  scanned: 81 files under templates/
  Claude Code compat: 2.1.116–2.1.150

Rendered settings.json under solo-experienced now has top-level keys: ['$schema', 'autoMode', 'env', 'hooks', 'model', 'permissions', 'statusLine'] — zero //-prefixed keys at any depth, no skillOverrides.

All 5 persona snapshot fixtures still match (file paths unchanged; we changed content only).

Test plan

• All 64 tests pass locally (60 existing + 4 new)
• python3 configure.py --check passes (would have failed before the tier-pro fix — verified via the new skillOverrides-shape static check fired on the bug)
• End-to-end scaffold for all 5 personas produces validator-clean .claude/settings.json
• Persona snapshot fixtures still match (content change only, no file path drift)
• Pre-commit code review (5-angle) ran via the Explore agent; two real findings addressed (broken // statusLineVim stub — uncommenting produced wrong top-level key; broken // envCap stub — synthetic key name); third finding (placeholder keys in // skillOverrides) addressed by removing the placeholders
• CI green (will verify after PR opens)

Compat for downstream users

Users on cc-configure 2.6.0 with a populated .claude/settings.json get the cleanup on next cc-configure --retrofit. The deep-merge preserves their customizations; the new strip removes the stub-leaks. Users who manually uncommented and activated an opt-in keep the activated value (it's a real key like sandbox, not a //-prefixed one).

Users who want one of the formerly-shipped opt-ins (sandbox, worktree, prUrlTemplate, subagentStatusLine, skillOverrides) can copy the stub from settings.local.json.example into their personal settings.local.json and uncomment.

🤖 Generated with Claude Code