my-pi/pi-permission-system/docs/plans/0387-clarify-bash-rule-precedence-docs.md

---
issue: 387
issue_title: "pi-permission-system: clarify bash rule precedence for broad rules and exceptions"
---

# Clarify bash rule precedence for broad rules and exceptions

## Problem Statement

The bash-surface documentation contradicts itself and ships mis-ordered examples.
`docs/configuration.md` correctly states the model once — "Last matching rule wins within a single command — put broad catch-alls first, specific overrides after" — but a few lines later says "Use a more specific pattern before it to carve out exceptions," which is the opposite.
Every full example then orders the specific carve-outs (`git status`, `git diff`) *before* the broad `git *`, so under last-match-wins the broad `git *` rule wins and the carve-outs never take effect.
A user who copies the documented example expecting `git status` to be allowed will instead be asked, because the later `git *` rule overrides the earlier allows.

This is a documentation/example defect, not an evaluator defect.
The evaluator (`src/rule.ts`) deliberately resolves with `rules.findLast(...)` — last-match-wins — and this is a load-bearing, tested invariant across all surfaces (bash, path, mcp, skill).
Resolution direction was confirmed with the user: keep last-match-wins and fix the docs/examples (non-breaking).

## Goals

- Remove the contradictory "before it to carve out exceptions" wording so the docs state last-match-wins consistently.
- Reorder every bash example so the broad rule (`*` / `git *`) precedes the specific carve-outs (`git status`, `git diff`), making each example actually produce its intended exceptions.
- Keep all four config-surface artifacts aligned: `docs/configuration.md`, `config/config.example.json`, `schemas/permissions.schema.json`, and `README.md`.
- Non-breaking: no runtime, evaluator, schema-shape, or default-policy change.

## Non-Goals

- Do not change the evaluator's precedence model.
  Switching to most-specific-wins (the issue's rejected Option 2) is a breaking semantic change across every surface and is out of scope.
- Do not change any TypeScript source under `src/`, any loader, or any test.
- Do not change the schema's structure, field set, or validation rules — only the illustrative `examples`/`markdownDescription` example block within it.
- Do not touch the already-correct prose at `docs/configuration.md` line 188, the `path`-surface note around line 322, the "Restricted Bash Surface" example (already broad-first), or `README.md` line 87.

## Background

Relevant modules and artifacts:

- `src/rule.ts` — `evaluate()` resolves via `rules.findLast(...)`; the type doc on `Ruleset` reads "Later rules take priority (last-match-wins)."
  This is the authority; the docs must describe it, not contradict it.
- `src/wildcard-matcher.ts` — `wildcardMatch()` backs `*`/`?` semantics; unchanged.
- `docs/configuration.md` — the bash-surface section (`### bash Surface`) and several full config examples.
- `config/config.example.json` — the shipped example config; its `bash` block carries the mis-ordering.
- `schemas/permissions.schema.json` — an `examples`/`markdownDescription` JSON example carries the same mis-ordering; its prose `markdownDescription` (around line 120) already states broad-first correctly.
- `README.md` — line 87 already states "put broad catch-alls first and specific overrides after" (correct); line 18 is a feature bullet (correct).

Constraint from the package skill (AGENTS.md / `package-pi-permission-system`): "Keep schema, example config, `docs/configuration.md`, `README.md`, and TypeScript types/loaders aligned — changing one without the others is a bug."
This plan touches docs/config/schema examples only; types and loaders need no change, so alignment is satisfied by fixing all example sites together.

The package skill also records "pattern ordering is last-match-wins" as a core invariant — confirming Option 1 (docs fix) over Option 2 (evaluator change).

## Design Overview

The fix is editorial.
Two changes of kind:

1. Prose correction (one site): `docs/configuration.md` line ~202.
   Replace "Use a more specific pattern before it to carve out exceptions." with wording that matches last-match-wins, e.g.: "Place a more specific pattern *after* it to carve out exceptions — the later matching rule wins."

2. Example reordering (five sites): move the broad rule above its specific carve-outs so the later, more-specific rule wins.

Canonical corrected bash block (used where a surface-wide `*` is present):

```jsonc
"bash": {
  "*": "ask",
  "git *": "ask",
  "git status": "allow",
  "git diff": "allow",
  "rm -rf *": "deny"
}
```

Resolution trace under last-match-wins, confirming intent:

- `git status` → matches `*`, `git *`, and `git status`; last match is `git status` → **allow**.
- `git diff` → last match is `git diff` → **allow**.
- `git push` → last match is `git *` → **ask**.
- `rm -rf foo` → last match is `rm -rf *` → **deny**.

Design note on the `git *: ask` line in blocks that also have `*: ask`: the two have the same action, so `git *` is action-redundant with the surface-wide `*`.
It is retained deliberately because it is *pattern*-distinct: it demonstrates scoping a broad rule to a command family, which is the exact teaching point of "broad rule first, specific carve-out after."
This matches the user's confirmed Option 1 snippet.

For the minimal inline example that has no surface-wide `*` (configuration.md line ~61), use the two-line form directly:

```jsonc
"bash": { "git *": "ask", "git status": "allow" }
```

No type/interface changes; no code-fenced TS types apply (docs-only change).

## Module-Level Changes

No `src/` files change.
Documentation and config-example artifacts only:

- `docs/configuration.md`
  - Line ~61 (full `permission` example): reorder inline bash to `{ "git *": "ask", "git status": "allow" }`.
  - Line ~202 (prose): replace "before it to carve out exceptions" with the last-match-wins wording above.
  - Lines ~211–217 (bash example block): reorder to broad-first (`*`, `git *`, then `git status`, `git diff`, `rm -rf *`).
  - Lines ~443–444 (global agent YAML override): reorder to `git *: ask` then `git status: allow`.
- `config/config.example.json`
  - `bash` block (lines ~23–28): reorder to `*`, `git *`, `git status`, `git diff`.
- `schemas/permissions.schema.json`
  - The example JSON block (lines ~87–91): reorder its `bash` map to `*`, `git *`, `git status`, `git diff`.
- `README.md` — no change (lines 18 and 87 are already correct); verify only.

Grep sweep already performed for the affected example shape (`git status` / `git *` / "carve out" / "last-match") across `docs/configuration.md`, `README.md`, `config/`, and `schemas/`.
No occurrences exist under `src/`, `test/`, or `.pi/skills/package-pi-permission-system/SKILL.md` that need editing.
No `docs/architecture/` layout/metrics file references these example blocks.

## Test Impact Analysis

Not an extraction or refactor — no test surface changes.

- New tests enabled: none.
  The evaluator already encodes last-match-wins and is covered (e.g. existing `rule`/wildcard tests).
- Tests made redundant: none.
- Tests that must stay as-is: existing last-match-wins evaluator tests in `test/` remain the behavioral source of truth; this plan documents that behavior rather than altering it.
- No test references `config/config.example.json` or the schema example block (verified by grep), so reordering JSON keys cannot break a test.
  JSON object key order is semantically insignificant; schema validity is unaffected.

## Build Order

This is a docs/config-only change with no red→green test cycles — route to `/build-plan`, not `/tdd-plan`.
Land as a single reviewable commit (all example sites must agree to satisfy the alignment constraint).

1. Edit `docs/configuration.md`: fix the line ~202 prose and reorder the three bash examples (inline ~61, block ~211–217, agent YAML ~443–444).
2. Edit `config/config.example.json`: reorder the `bash` block to broad-first.
3. Edit `schemas/permissions.schema.json`: reorder the example `bash` block to broad-first.
4. Verify `README.md` needs no change (lines 18, 87 already correct).
5. Run `pnpm --filter @gotgenes/pi-permission-system run check` and `pnpm run lint:md` to confirm JSON validity and markdown lint pass.
   Re-grep for any remaining `git status` … `git *` (specific-before-broad) ordering to confirm none survive.
6. Commit: `docs: fix bash rule precedence examples and wording (#387)`.

(No `feat`/`fix` code change; the suggested commit type is `docs:`.
Non-breaking, so no `!` and no `BREAKING CHANGE:` footer.)

## Risks and Mitigations

- Risk: another example or doc still teaches specific-before-broad and slips through.
  Mitigation: the closing grep sweep (step 5) re-checks all surfaces; the inventory above is grep-derived, not memory-derived.
- Risk: reordering JSON keys breaks schema validation or an example-loading test.
  Mitigation: key order is JSON-insignificant; grep confirmed no test loads these artifacts.
  `pnpm run check` validates JSON parse.
- Risk: editing the schema's `examples` block accidentally touches schema structure.
  Mitigation: change is confined to values inside the example object; no `properties`/`required`/`type` edits.

## Open Questions

None.
Resolution direction (Option 1, docs-only, non-breaking) was confirmed with the user.
The retained-but-action-redundant `git *: ask` line is an intentional, documented pedagogical choice, not an open question.