Skip to main content
๐Ÿ—“๏ธ Schedule discussionOpens Google Calendar โ€” add attendees there.

Formalize enforcement tiers + add opt-in shell helpers (Tier 0)

DoneAuthor: @relbnsOwner: @relbnsEffort: M

Problemโ€‹

Surfaced during the PR #25 (proposals flow) review cycle on 2026-05-29. The validate-policies.mjs validator existed only at the PR-CI layer; PR #24 (capability index) added new fields to every policy YAML without updating the schema, master shipped broken, and PR #25 paid the cost โ€” its CI failed on schema violations it didn't introduce.

The bigger pattern: we have hooks at Tier 2 (pre-commit) mirrored to Tier 4 (PR CI), per ai-engineering-strategy.md ยง16. That's good, but it doesn't say anything about earlier tiers โ€” command-time interception (Tier 0) or editor-time feedback (Tier 1). Branch naming is the obvious example: branch-name-check.sh fires on the first commit, by which point the developer has already created the branch and probably has files staged. Renaming + re-committing is pure roundtrip.

The principle we're missing: every check should be evaluated for fit at Tier 0 / Tier 1, because some classes of mistake can only be prevented before state is created.

Proposalโ€‹

Three deliverables, all in one PR (matches the "implement, then present" working mode):

  1. docs/methodology/enforcement-tiers.md โ€” formalize the 5-tier ladder (Tier 0โ€“5), with a table mapping every current check to the tier(s) it runs at. Make the gaps visible.

  2. templates/shell-helpers/ โ€” new opt-in directory holding shell functions developers can source from ~/.zshrc / ~/.bashrc. First helper: git-branch-interceptor.sh โ€” wraps git checkout -b / git switch -c, validates the proposed branch name against the same lenient regex branch-name-check.sh uses, prompts with auto-derived valid options when the name is invalid. Includes a README.md with install instructions and a contributor guide for adding new helpers.

  3. Reference from the methodology doc to the helpers directory + back, so devs reading the architecture know where to install Tier 0 and devs in the helpers directory know what the broader picture is.

Explicitly opt-in. We do not override anyone's shell without consent, and Tier 0 is never a requirement โ€” the mandatory gates remain Tier 2 (hooks) and Tier 4 (CI).

Why now / Why usโ€‹

  • The PR #25 friction was a concrete data point. Without formalization, the same gap will recur the next time someone adds metadata to YAML.
  • This is platform / process work โ€” squarely in our lane. No cross-team coordination needed.
  • The "opt-in shell helper" pattern is already proven (Ariel used the equivalent at his previous company). Porting it costs ~50 lines of bash; benefit accumulates per-dev forever.

What shippedโ€‹

FilePurpose
docs/methodology/enforcement-tiers.mdFormal tier ladder + map of current checks
templates/shell-helpers/README.mdInstall guide, contributor guide
templates/shell-helpers/git-branch-interceptor.shFirst Tier 0 helper โ€” intercepts git checkout -b / git switch -c
docs/proposals/index.mdIndex updated โ€” this proposal moved to Done

Out of scope (follow-ups)โ€‹

  • active-gates-awareness.sh SessionStart hook โ€” parallel to capability-awareness.sh, tells Claude to mention to the user which gates will fire given the files they're touching. Mentioned at the bottom of enforcement-tiers.md as a planned follow-up. Worth its own proposal when we get there.
  • Tier 1 (editor) coverage โ€” the methodology doc lists tsc LSP and eslint-on-save but they depend on each dev's editor setup. Could ship per-repo .vscode/settings.json templates as a future Tier 1 push.
  • More Tier 0 helpers โ€” anything that fires at PR CI today and has a repeatable command-time mistake-mode is a candidate. Add one per PR as they prove useful.

Triage notesโ€‹

Self-triaged 2026-05-29 by the author. Category process, effort M, no cluster (no overlapping proposals at time of triage). Implemented and shipped in the same session per the working-mode preference of "implement, then present, iterate on review feedback."