chore(vocabulary): add the retired-sense vocabulary checker with its allowlist #13178

Parent

Refs: #12750. Epic: #12646. Source: PLAN Phase 10, topic planning-chain-consolidation.

Depends on

None.

Outcome

A vocabulary checker script reports each use of AC3's six retired senses in the files it is given, and skips every sense on its allowlist, each allowlist entry named with its reason. It takes --sense <id> (repeatable; all six when absent) and path arguments (the whole repository when absent), always excludes docs/adr, docs/upstream, docs/standards and CHANGELOG files, prints path:line: <sense>: <text> per match, and exits 1 on any match, 0 on none. It is not yet a required check: the sense slices of #12750 use it as their done-when, and the last slice wires it into CI.

Demo: run the checker over docs/contracts/rendered-views/README.md: it reports the "Choosing the rung" heading and the "Default ladder" heading and exits 1; run it over plugins/session-flow/skills/find-handoff: it exits 0 (rung-N files are allowlisted).

The Brief (Problem, Goal, Constraints) is in the epic body.

Decisions

• Q5-Q12: Retired senses and their replacements: rung for the view form or medium choice (now form, or medium / fallback chain step); default ladder (now fallback chain); overlay for the config cascade's personal layer (now personal override); tier for precedence (now scope, ADR 0075's word); surface for a config file (name the file or setting); contract for the Brief (now Brief). The workflow stage reads Interview.
• D8: The checker carries an allowlist of senses that stay.
• Allowlist rule (agent choice recorded on chore(vocabulary): retire rung, default ladder, overlay and the other clashing senses with a checker #12750): every use of these words that is not one of the six retired senses stays, and the issue's Out of scope bars renaming it.

Key interfaces

check-vocabulary [--sense <id>]... [<path>...]
sense ids: rung, default-ladder, overlay, tier-precedence, surface-config, contract-brief
output: <path>:<line>: <sense>: <matched text>      exit 1 on any match, 0 on none
rules and allowlist: one data file beside the script; each rule a pattern for the retired
sense (matched in context, for example overlay beside personal, layer, .local, cascade, or
gitignore; rung beside text, diagram, page, video, medium or view), each allowlist entry a
path glob or phrase plus its reason

Allowlist entries to ship, each with its reason (not the retired sense):

• rung: the autonomy ladder (D8); enforcement-ladder rungs and ids; the toolchain resolution ladder; the github method ladder; loop-lane and pr-pipeline rungs; find-handoff's rung-N reference files; the education explanation rung (a layer of explanation, not a view form); recommend-skills' candidate ladder.
• overlay: disk-hygiene's policy overlay; machine-health's catalog overlay (both their own plugin-local mechanism, not the config cascade's personal layer); visual overlays (CSS, UI, video, image, brand) in user-interface, planning's page styles, playwright, animation, pixel-art, ai-briefing's brand overlay, gaming; songwriting's research text; developer-experience's agentic overlay harness; testing's judge-calibration fixtures (verbatim copies of other plugins' code).
• tier: the rendered-views View tiers (the page's interactivity level); enforcement-ladder tiers; memory tier; model tiers.
• surface: the interview surface (terminal, page, shared session); a plugin's skills and commands as its surfaces; emitting surfaces.
• contract: versioned docs/contracts, and interface contracts at design.

Done when

• The checker and a test of it ship; the test covers one hit and one allowlisted miss per sense, the always-excluded paths, --sense, path arguments and both exit codes.
• Each allowlist entry above is in the data file with its reason; the Demo commands print what it says.
• No workflow runs the checker yet.

Out of scope

• Fixing any match (the sense slices of chore(vocabulary): retire rung, default ladder, overlay and the other clashing senses with a checker #12750)
• Wiring the checker into CI (the last slice of chore(vocabulary): retire rung, default ladder, overlay and the other clashing senses with a checker #12750)
• Renaming any allowlisted sense