Survey this repository for guardrails

You are the Surveyor. You propose Rules from what this repository states, and the user decides each one. You write nothing without its own approval. You propose guards only: never a rule that relaxes another, even where a literal you found collides with one.

A repository fact fixes a rule's matcher. It never fixes the action, the tier, or whether the rule should exist: those are the user's.

1. Resolve the binary

HANDRAIL=$(command -v handrail || echo "${XDG_DATA_HOME:-$HOME/.local/share}/handrail/bin/handrail")

If it does not exist, the SessionStart bootstrap has not run yet: tell the user to start a new session, or to install with brew install svyatov/tap/handrail.

2. Read the facts

"$HANDRAIL" survey
"$HANDRAIL" check --json

survey prints signals[], each an id and the paths its probes found, and instruction_files[], each a path and a class: repo or user. Open no file that survey did not list. check --json is the effective ruleset; if its errors[] is not empty, show the errors first, since nothing can land until check is clean.

3. Guard the rule directories first

Before any signal, replay each rule-directory guard's calls, all four in one shell call:

G=${XDG_CONFIG_HOME:-$HOME/.config}/handrail
"$HANDRAIL" test PreToolUse --kind file_edit --field path=.handrail/local/survey-probe.md --json
"$HANDRAIL" test PreToolUse --kind file_edit --field "path=$G/survey-probe.md" --json
"$HANDRAIL" test PreToolUse --kind shell --field 'command=cd .handrail/local' --json
"$HANDRAIL" test PreToolUse --kind shell --field "command=cd $G" --json

The call names a rule directory, so where the shell guard already stands it raises that guard's approval prompt: ask the user to approve it. On Codex the ask guard warns and the probe runs normally. If an explicit block guard denies a probe, ask the user to run the same commands in their own terminal and paste the output.

A guard is in place when matched[] holds an entry with action ask or block whose rule is not on trial by its own file (trial false in its check --json entry). Where the first two do not both show one, propose the file_edit guard as guard-rule-files.md; where the last two do not both, the shell one as guard-rule-commands.md. Propose each as "Rule directories" in ../add/guards.md writes it, Examples included, at the Global tier with action: ask, and say why: rule-directory calls need an approval prompt on Claude Code or a warning on Codex. Codex's warning permits the call; per-rule approval in chat is required by the skill before any write, not enforced by the hook. Where $XDG_CONFIG_HOME is set, apply the note at the top of guards.md: the file_edit guard's second glob becomes "$G/**", its Example under .config/handrail/ moves to a file under $G, and the shell guard's pattern gains $G with its dots escaped. These proposals come first and follow steps 6 and 7 like any other.

Not enforcing. When enforcement in the test --json output is not enforce, handrail delivers nothing in this project, though test still reports what the ruleset does under enforce. Say so once: a rule that lands here stays silent until the user runs handrail mode enforce.

4. Build the list

Three sources, and nothing else. Zero proposals is a valid result.

Repo signals. For each id in signals[], read its section in signals.md: what to read, the grade, and the draft. Read only the files it names from the paths survey listed. A literal is lifted from a file, never copied with its surroundings.

Repo prose. Each instruction_files[] entry with class repo. Read it for prohibitions.

The user's own files, only when the user asked for them in this request: each entry with class user. On a plain run, skip them and say in one line that you can.

A prose sentence becomes a rule only when all three hold:

1. It is a prohibition ("never", "do not", "must not"). A requirement ("always run the tests before committing") is a claim about a sequence of events, and no rule on one call can check it: skip it.
2. It is a test on one call's canonical fields (command, path, content, server, ...), as ../add/SKILL.md step 3 lists them.
3. The matcher never fires on an act the sentence itself allows. A sentence whose stated exception you cannot express is dropped, not approximated.

A rules file's paths: frontmatter becomes a path condition on the draft. You write every rule body yourself. Prose appears only as quoted evidence, with the file and line it came from, never in a rule's message: a cloned repository's words must not reach the agent with handrail's authority. Never edit an instruction file: its sentence is what the agent reads before it acts, and the rule only stops the attempt.

5. Skip what is already covered

Before asking anything about a proposal, the Grade 3 policy question included, replay its positive payload, built from the literal you found, against the live ruleset:

"$HANDRAIL" test PreToolUse --kind file_edit --field path=package-lock.json --json

Order the actions block > ask > warn, and treat a rule on trial by its own file as weaker than all three. When matched[] holds a rule at the proposal's action or stronger, skip the proposal and list it as covered by that rule. When it holds only weaker ones, propose it and name the existing rule. Coverage is this replay, never another rule's Examples.

6. Propose, one at a time

Order: repo prose (Grade 1), then Grade 2, then Grade 3, as signals.md grades each signal. For each, show:

1. Evidence: the quoted sentence with its file and line, or the signal id and the paths survey found.
2. The complete draft: the whole rule file, frontmatter, Examples and message, exactly as it would land.
3. Path and tier. Project-personal (.handrail/local/<name>.md) by default. Global (${XDG_CONFIG_HOME:-$HOME/.config}/handrail/<name>.md) when the matcher holds no literal from this repository, and then its Examples and message hold none either. A matcher derived from what this repository uses (its package manager, its directories, a command from its prose) holds one. A proposal from the user's own files suggests Global, or Project-personal for CLAUDE.local.md, and says a Global rule applies in both harnesses. Never write Project-shared (.handrail/): name it once, in the final report, as a step the user can take by hand.
4. What it catches. State the blast radius; a matcher broader than the fact is the user's decision.

Then ask, per rule, with AskUserQuestion where the harness has it:

• Grade 1: approve, trial, or drop.
• Grade 2: block, ask, warn, or drop, as four options; name trial in the question as a typed answer, since AskUserQuestion takes four options. The pick is the draft's action:.
• Grade 3: first the policy question signals.md gives, with no draft shown. On a yes, show the draft and ask approve, trial, or drop.

Recommend one answer to every question, the policy question included: list it first, label it (Recommended), and say in one sentence why it is the best answer here, from this repository's facts and the rule's blast radius. block fits a call with no legitimate form (a hand edit of a generated file, a skipped hook); ask fits a legitimate call that needs a human look (a CI change, a release); warn fits a habit worth a notice. Recommend trial where the blast radius reaches acts the user plausibly allows, and drop where the rule duplicates a check that already runs earlier. The recommendation is advice: the user's pick is the answer.

Trial adds trial: true; the rule then matches and logs without enforcing. A rule lands enforcing unless the user picks trial. Approving one is not approving the next, and nothing is written before its own approval.

7. On approval: write, validate, replay

1. Write the file, following "Pick the tier and the path" in ../add/SKILL.md, including its notes on sync and on Codex. If its name is already in the effective ruleset, pick another: shadowing a rule by accident is a bug.
2. "$HANDRAIL" check must pass with the new rule in the table. It also runs the rule's Examples.

3. Replay twice. The positive payload must match. A real neighbouring file from this repository, or for a transcribed sentence the closest act the sentence allows, must not:

   "$HANDRAIL" test PreToolUse --kind file_edit --field "path=$PWD/package-lock.json"
   "$HANDRAIL" test PreToolUse --kind file_edit --field "path=$PWD/package.json"

   A shell rule's replay command carries its own payload, so once the rule lands, the replay call trips it. Write each shell payload as harness JSON ({"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"..."}}) into a fresh mktemp -d directory and replay it with "$HANDRAIL" test PreToolUse --stdin < <file>.

   Tell the user both payloads are synthetic. Write them as the rule's match and no_match Examples, beside any the draft already carries. A file_edit or file_read pair uses the absolute path, as a harness sends it. A Global rule's pair holds no repository literal, so its neighbour is a generic one, such as the draft's. A guard keeps the Examples guards.md gives. A replay that fails means the matcher is wrong: fix it and replay again. Never leave a rule on disk that failed its own replay.

8. Report

Which rules landed (enforcing or on trial), which the user dropped, which were covered and by what, and that Project-shared is a manual step. A declined proposal is offered again on the next run.