feat: Add Homebrew support and automated tests

.github/ISSUE_TEMPLATE/defect.md

@@ -0,0 +1,77 @@
+---
+name: Defect
+about: Something behaves wrongly. Written so a stranger can reproduce it and a gate can prove it fixed.
+title: ""
+labels: ""
+---
+
+<!--
+Two rules, and everything below is only their shape:
+
+1. THE REPLICATION IS SOMETHING A STRANGER CAN RUN. Not a path on your machine.
+   Not a private store, a worktree, a scratchpad, a `do.log`, a `/tmp` anything.
+   Whoever picks this up has none of them, and a bug that can only be seen on
+   your box is a bug that gets closed unfixed.
+2. THE ACCEPTANCE IS END-TO-END FOR BEHAVIOUR THAT ONLY SHOWS END TO END.
+   A unit test around a wedge that only appears through the real door proves the
+   unit, not the fix. Name the door.
+
+Delete these comments as you fill it in. Issues #185 and #207 are the worked
+examples; open either one if a heading here is not obvious.
+-->
+
+## What happened
+
+<!-- Quote the log or the screen — its own words, in a fenced block. Say the
+date, the base sha (`dev@1140a075`), and the exact command with every flag and
+model on it. "It hangs sometimes" is not an observation; the line the run
+printed while it hung is. -->
+
+## Replication
+
+**Deterministic (no model).**
+
+<!-- The one a reviewer can run at their desk this minute: a stub worker, a
+fixture, `go test -tags e2e`, `codeaf do --json` with a short `--timeout`.
+Say what a developer sees TODAY when they run it — the wrong output is the
+evidence, so quote it — and where it is driven from. -->
+
+**Field (real models).**
+
+<!-- The full-fat version: the real command, which keys it needs
+(`OPENROUTER_API_KEY`), and roughly how much wall time and money to budget. Say
+what makes it fire — "any task whose first attempt fails" — and name the control
+run if you have one. -->
+
+<!-- If the forensics only exist on your machine, they get ONE line and no more:
+*Owner's forensics, may be gone:* the run's private store and log were kept on
+the benchmark box. Then say whether anything in them is actually needed, or
+whether the replication above stands in for it. Never make it the replication. -->
+
+## Where
+
+<!-- File and function names — `settlementWatch` in `cmd/codeaf/do.go`, the
+escalation site in `cmd/codeaf/chat.go` (search `escalated from`). Not line
+numbers: they move, and a stale one sends the next reader to the wrong code.
+Give the searchable string. -->
+
+## The fix
+
+<!-- What the behaviour should be, in the product's own words, not a patch.
+If a flag or a person-facing string is involved, spell it exactly as it will
+read. If there is a choice to make, make it and say why. -->
+
+## Acceptance
+
+<!-- e2e FIRST, and each line says what is asserted, not that a test exists. -->
+
+- **e2e:** <!-- through the real door — `codeaf do --json`, the tmux suite,
+  `go test -tags e2e ./internal/e2e/` — with the exact text or receipt field
+  asserted, and the exit code. One test, no model where a stub will do. -->
+- **e2e:** <!-- the second case, usually the control: the same run without the
+  flag, or the path that must keep working. Delete if there is genuinely one. -->
+- **Unit:** <!-- the part that is a pure function or a structural law — a
+  derived bound, "every path that assigns X goes through this one check". -->
+- The manual page that covers this quotes the new wording
+  (`internal/manual/chat/`), and the change entry's `invalidates` names what
+  people believed before.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+<!-- Base this on `dev`. docs/rules/branching.md if that is a surprise. -->
+
+## What changed
+
+## How it was checked
+
+<!-- What you actually ran, and what it said. "Tests pass" is not a report.
+     CI (`check`) runs on this pull request whatever you ran; a suite that
+     skipped for want of a provider key is one line here, not a gap. -->
+
+## Checklist
+
+- [ ] A change entry — `make changelog-new PR=<n> KIND=<kind> SLUG=<slug>`. What
+      it carries is not what shipped but what somebody now believes wrongly.
+      `kind: internal` with just a title is fine; `no-changelog` is the way out.
+- [ ] The manual knows about it — `internal/manual/chat/` updated in this change
+      if a slash command, key, tool, default, limit or refusal moved. CLAUDE.md
+      states the law; three gates fail the build if it is skipped.
+- [ ] Only my own paths are staged — no `git add -A`.

.github/rulesets/README.md

@@ -0,0 +1,44 @@
+# The branch rules, checked in
+
+GitHub keeps branch rules in its own database, where they are invisible to the
+tree they govern and changeable by anyone with admin from a settings page that
+records no reason. These files are the same rules as a diff: what is enforced,
+when it changed, and who signed for it.
+
+They are **not applied automatically.** Apply them by hand:
+
+This repository is public. The live `protection` ruleset covers `main`, `dev`,
+and `staging`. The checked-in `promotion-pointers.json` has no bypass actors.
+Whoever applies it must add the owner of `PROMOTION_TOKEN` (or that account's
+role) to its bypass list; otherwise Friday's push is refused. The token also
+needs Contents and Workflows read and write to publish the staging release.
+
+```sh
+gh api -X POST repos/Agent-Field/codeaf/rulesets --input .github/rulesets/dev.json
+gh api -X POST repos/Agent-Field/codeaf/rulesets --input .github/rulesets/promotion-pointers.json
+```
+
+To update one that already exists, find its id and PUT over it:
+
+```sh
+gh api repos/Agent-Field/codeaf/rulesets --jq '.[] | "\(.id)\t\(.name)"'
+gh api -X PUT repos/Agent-Field/codeaf/rulesets/<id> --input .github/rulesets/dev.json
+```
+
+## Inspect the live rules
+
+The repository is public and its `protection` ruleset is live. Inspect the
+rulesets and confirm the promotion account can bypass the pointer rules before
+enabling the Friday workflow:
+
+```sh
+gh api repos/Agent-Field/codeaf/rulesets
+gh api repos/Agent-Field/codeaf/rulesets/<id> --jq .current_user_can_bypass
+```
+
+## `required_status_checks` names are job names
+
+The contexts named in `dev.json` and `promotion-pointers.json` are the `name:`
+fields of jobs in `.github/workflows/`. Rename a job and the check it was
+standing in for silently stops being required — the branch is then unprotected
+and nothing says so. The two move in the same commit.

.github/rulesets/dev.json

@@ -0,0 +1,38 @@
+{
+  "name": "dev",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": {
+      "include": ["refs/heads/dev"],
+      "exclude": []
+    }
+  },
+  "rules": [
+    { "type": "deletion" },
+    { "type": "non_fast_forward" },
+    {
+      "type": "pull_request",
+      "parameters": {
+        "required_approving_review_count": 1,
+        "dismiss_stale_reviews_on_push": false,
+        "require_code_owner_review": false,
+        "require_last_push_approval": false,
+        "required_review_thread_resolution": true,
+        "automatic_copilot_code_review_enabled": false,
+        "allowed_merge_methods": ["squash"]
+      }
+    },
+    {
+      "type": "required_status_checks",
+      "parameters": {
+        "strict_required_status_checks_policy": false,
+        "do_not_enforce_on_create": false,
+        "required_status_checks": [
+          { "context": "check" }
+        ]
+      }
+    }
+  ],
+  "bypass_actors": []
+}

.github/rulesets/promotion-pointers.json

@@ -0,0 +1,27 @@
+{
+  "name": "promotion pointers",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": {
+      "include": ["refs/heads/staging", "refs/heads/main"],
+      "exclude": []
+    }
+  },
+  "rules": [
+    { "type": "deletion" },
+    { "type": "non_fast_forward" },
+    { "type": "required_linear_history" },
+    {
+      "type": "required_status_checks",
+      "parameters": {
+        "strict_required_status_checks_policy": false,
+        "do_not_enforce_on_create": false,
+        "required_status_checks": [
+          { "context": "cross build" }
+        ]
+      }
+    }
+  ],
+  "bypass_actors": []
+}