@kavishdua/proctor 1.5.0 → 1.6.0

package/README.md

@@ -478,6 +478,35 @@ jobs:
 The example pins the commit behind the `v1.0.0` release. You can use the `v1.0.0` tag instead, but
 a full commit SHA is immutable, so it keeps builds reproducible.
 
+### Make the gate independent
+
+Local hooks are agent-writable; only CI outside the agent's write scope is an independent check.
+For that to hold, the workflow itself must survive the agent:
+
+1. Require the proctor status check on the protected branch (repo Settings > Branches), so a red
+   proctor run blocks merging.
+2. Cover `.github/` in `CODEOWNERS` (for example `/.github/ @you`) AND enable "require review
+   from code owners", so a pull request that weakens or deletes the workflow needs your review.
+3. Keep the agent's own credentials away from repo settings: nothing the agent can authenticate
+   as should be able to edit branch protection or dismiss the required check.
+
+`proctor doctor` audits what it can see: ruleset deployed and undrifted, pre-commit hook and
+unresolved gate installed, agent Stop hooks, the CI workflow, and CODEOWNERS coverage. It reports
+each layer as MISSING, CONFIGURED, or UNVERIFIED. CONFIGURED means the file exists - it never
+means independently verified, because branch protection, required review, and who holds admin
+cannot be checked from a working tree.
+
+Doctor is offline by default. With explicit `proctor doctor --github` opt-in and a github.com origin remote, doctor asks the owning source: it
+makes read-only GET requests to the GitHub API for repository metadata, branch rules, and ruleset
+configuration, and reports what the server actually enforces as SERVER-OK (or MISSING when the
+server confirms a rule is absent). SERVER-OK means server-verified configuration, not proof of
+agent-independent enforcement: an agent whose credentials have admin or settings write access
+could still change or bypass those rules, and doctor cannot see the agent's credentials. Only the
+repository owner and name appear in the request URLs; no file contents or block records are sent. If you already have `GITHUB_TOKEN` or `GH_TOKEN` set, it is sent as an Authorization
+header so private repositories can be read; without one, only public rulesets are visible and
+anything unreadable is reported UNVERIFIED, never as absent. Redirects outside the HTTPS GitHub API origin are refused before following them. The number of requests is printed
+with each run, and `--offline` skips the network entirely.
+
 ## Dynamic checks
 
 `proctor check --dynamic` runs extra checks using a runnable project test suite. The default