Promote the safety-kit README update to main (#452)

[ptr727]

Promotes #452 - the agent write-safety kit README updated to document Rule 4 (branch-rule bypass + the unconditionally-denied verification-skipping flags), the fail-closed behavior on the protected-default branches, and an explicit Refreshing After an Upstream Change section (re-run the installer = the refresh mechanism #365 tracks).

Docs only - no release. Restores develop==main after the guard/runbook promotion (#451).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Promotes the agent write-safety kit README update to main, documenting the expanded guard behavior (Rule 4 branch-rule bypass + unconditionally denied verification-skipping flags), the fail-closed behavior on protected-by-default branches, and the refresh procedure for updating deployed copies across machines.

Changes:

• Document the hook’s additional protection surface: branch-rule bypass detection plus explicit-bypass flags (--admin, --no-verify).
• Add a “Refreshing After an Upstream Change” section clarifying that re-running the installer is the update mechanism (tracked in #365).
• Clarify scope notes around precision/recall for different rule classes and the fail-closed behavior.

Comments suppressed due to low confidence (1)

host-setup/agent-safety/README.md:72

• This fail-closed description mentions only unreadable branch rules, but the guard also fails closed for protected-by-default branches when it cannot determine the checkout's origin repo (so it cannot query rules at all). Including that case makes the documentation match the actual deny conditions.

- **The branch-bypass rule fails closed.** Unlike the write-footgun rules, a push to `main`/`master`/`develop` is denied even when the branch rules cannot be read, because the harm there is a silent success under the maintainer's admin bypass. The rule reads each branch's live rules, so it adapts to every repo (a code-style `develop` denies, a config-style `develop` allows) with no per-repo configuration, and hands the exact command to the maintainer to run when a bypass is genuinely intended.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

host-setup/agent-safety/README.md:3

• This sentence calls out a "git operation" and an "override a required check", but the examples include gh pr merge --admin, which is a GitHub operation (not a git operation) and bypasses the server-side merge gate. Rewording avoids conflating git, GitHub, and the specific enforcement points.

Per-machine, user-account-scoped guards against an agent making a mis-targeted GitHub **write** under the maintainer's identity, or a **git operation that bypasses a branch rule or overrides a required check** - a push, force-push, or delete that an active branch rule forbids, or an override flag (`--admin` past the server-side merge gate, `--no-verify` past the local git hooks). Deploy it as the **first thing on any new system** where Claude Code runs with the `gh` credentials logged in (WSL, Linux, macOS, Proxmox, Windows).

host-setup/agent-safety/README.md:9

• This bullet describes the second class as a "git operation", but it later includes gh pr merge --admin as an explicit bypass flag. Changing this to "an operation (git or gh)" keeps the classification technically accurate.

- **`hooks/gh-write-guard.py`** - a PreToolUse hook that denies two classes of dangerous action. First, the GitHub **write** footguns behind the cross-repo comment incident: a state-changing `gh` call whose output is discarded, a GraphQL mutation passing a **literal** node id instead of a `$variable`, and a `gh` write whose explicit target is outside the checkout's `origin`. Second, a **git operation that bypasses a repository protection**. The branch-rule cases - a direct push to a branch that requires a pull request, a force-push where history is protected, a branch delete where deletion is blocked - are judged against the branch's **live** rules, so a code-style `develop` is denied while a config-style `develop` is allowed with no per-repo configuration. A push to a protected-default branch fails closed when its rules cannot be determined - the API is unreachable, or the checkout's origin cannot be resolved to query them. The explicit-bypass flags are denied **unconditionally**, since the flag is itself the bypass and needs no branch query: `gh pr merge --admin` overrides the server-side merge gate, and `git commit`/`git push --no-verify` skips the local git hooks. Reads and everything else pass through. It fires even in autonomous / bypass-permissions sessions, which is how the incident happened.