bash-policy

Bash Policy

Core Workflow

1. Find the repo root and inspect current policy state.

   • Use git status --short -- .bash-policy.yaml .bash-policy-candidates.yaml before edits.
   • Treat .bash-policy.yaml as curated source of truth; .bash-policy-candidates.yaml is generated evidence.
   • Keep policy-artifact-root distinct from safe-root: the artifact root is the durable project root where .bash-policy.yaml, dry-run logs, and candidates live; the safe root is the active checkout/worktree used for path validation.
   • For interactive curation, use an absolute --policy-artifact-root. Do not rely on hook cwd or an auxiliary worktree root.

2. Generate or refresh Claude candidates.

   • Bash-policy curation is mostly for Claude permission telemetry.

   • Use this exact export shape by default:

     bash-policy export --provider claude --policy-artifact-root "$repo_root" --claude-settings .claude/settings.json
     

   • If .claude/settings.json is missing, ask or locate the intended Claude settings file before guessing.

   • bash-policy export regenerates .bash-policy-candidates.yaml from current sources; previous candidate-file contents are not policy state.

   • Export sources are aggregated dry-run evidence and optional Claude settings. Claude settings contribute Bash(...) permission-family candidates; dry-run evidence contributes command-shape candidates.

   • Use bash-policy report --provider claude --policy-artifact-root "$repo_root" when frequency, proposed status, or examples from .bash-policy-dry-run.jsonl would improve curation.

   • Generated evidence artifacts are not intended policy deliverables: .bash-policy-candidates.yaml, .bash-policy-dry-run.jsonl, .bash-policy-dry-run.jsonl.lock, and .bash-policy-dry-run.jsonl.lock.owner.json should be ignored or worktree-excluded.

3. Curate command-shape candidates.

   • Add runtime command-shape rules only for safe, read-only inspection commands.
   • A command-shape rule may use decision: allow, decision: deny, or decision: manual.
   • Configured command-shape rules override built-in defaults, but never override the non-overridable safety floor: secret exposure, credential paths, safe-root escape, verified bypasses, unsupported redirections, dynamic shell forms, and destructive irreversible operations must not become auto-allowed.
   • Prefer a built-in profile over a custom rule when the current evaluator already allows a representative command. Export should omit built-in-covered shapes; if a candidate appears anyway, behavior-check before adding a redundant rule.
   • Prefer normalized placeholders:
     • <safe-path> for a single normalized safe path.
     • <safe-path>... for one or more final path operands.
     • <pattern> for non-sensitive search patterns.
     • <number> and <fields> for numeric and field-list values.
     • <safe-glob> for constrained non-sensitive filename globs such as *.go in supported option-value positions.
     • <safe-pathspec> when the engine emits pathspec-shaped operands.
   • Generalize command shapes whenever the broader rule is still safe. Replace specific single-path or literal-value rules with placeholder or terminal-variadic forms, then remove narrower rules covered by the general rule.
   • Do not copy highly specific literals such as project regexes, command names, timestamps, local absolute paths, or generated line ranges when a placeholder rule captures the intent.
   • Do not keep literal glob tokens such as *.go or *.py in command-shape identities. For git pathspec operands, including git grep ... -- *.go and git diff ... -- *.go, expect current bash-policy to normalize safe extension globs to <safe-path> and cover repeated operands with <safe-path>....
   • For grep filename filters, use --include=<safe-glob> only when current validation/evaluation supports it. Do not rewrite include globs as --include=<pattern>; if <safe-glob> is unsupported in the installed binary, omit the rule and leave that command manual.
   • For sed read-range forms, prefer normalized rules such as sed -n <number>,<number>p <safe-path>... over literal line ranges and filenames when current evaluation emits that shape. Do not add sed rules for -e, --expression, -f, --file, -i, or --in-place forms; those can execute commands, read scripts, or write files and must remain manual.
   • Do not emit display summaries, transcript fragments, or truncation markers such as standalone ... as policy identities. Export should canonicalize full legacy summaries when possible and omit unreconstructable truncated identities.
   • Curate compound command evidence as leaf command-shape rules. Do not add whole-compound rules for ;, &&, ||, or |; every leaf must pass the safety floor and resolve through a built-in, configured command-shape rule, or admissible Claude setting.
   • rtk is a wrapper. Candidate and policy identities should use the wrapped command shape when recoverable, not an rtk-prefixed rule.
   • Never add rules containing <redacted> or secret-looking values.
   • Keep state-changing commands manual unless the user explicitly approves a narrow rule. Be skeptical of candidates like python3 <safe-path> ..., git add, git commit, package managers, broad shell wrappers, and tool invocations that mutate coordination state.