Document env-gating tradeoff and AUDIT_PAT provisioning

SECURITY.md gets two new paragraphs in the CI Validation Contract:

- An "as a consequence of env-gating" note: workflow_dispatch from a
  non-`main` ref is rejected by the deployment-policy. Audit changes
  iterate on main, or via a temporary policy widening.
- AUDIT_PAT provisioning: what it is, what UNVERIFIABLE looks like
  without it, the exact permissions to mint on a fine-grained PAT,
  and the env-scoped `gh secret set` command.

AGENTS.md gets a one-section pointer at SECURITY.md so that any
agent or maintainer touching workflow files, dependabot, the tend
config, the lockfile, or the sign script knows the policy exists
and where its failures are tracked.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: nedtwigg

AGENTS.md

@@ -43,6 +43,10 @@ The primary job of a spec is to be an accurate reference for the current state o
 
 When updating code covered by a spec, update the spec to match. When the two specs overlap (e.g. pane header elements appear in both), layout.md documents placement and sizing while alert.md documents behavior and visual states.
 
+## Security
+
+See [SECURITY.md](SECURITY.md). It enumerates concrete `FAIL IF` checks across dependencies, GitHub Actions, release pipelines, and the tend automation surface, and it is enforced by `.github/workflows/security-audit.yaml` (nightly + as a required gate before VS Code publish). Read it before touching: `.github/workflows/`, `.github/dependabot.yml`, `.config/tend.yaml`, `pnpm-workspace.yaml`, `scripts/sign-and-deploy.sh`, or anything that introduces a new secret, workflow trigger, or environment. Failures are tracked under the `security-audit-failure` issue label.
+
 ## Design
 
 See [DESIGN.md](DESIGN.md) for full design context. Key principles:

SECURITY.md

@@ -76,5 +76,13 @@ The `security-audit` workflow at `.github/workflows/security-audit.yaml` enforce
 
 The audit job declares `environment: security-audit`, whose deployment-branch-policy admits only `main` and `v*` tags. Both ref classes are admin-only by §3's rulesets, so a write-scoped bot cannot reach the env's secrets (most importantly `AUDIT_PAT`, when provisioned) by pushing a workflow file to a feature branch.
 
+As a consequence of that env-gating, audit changes are iterated on `main` directly. A `workflow_dispatch` from any other ref is rejected by the environment's deployment-policy before any step runs. To experiment on a branch, widen the env's policy temporarily and revert after.
+
+`AUDIT_PAT` itself is optional. Without it, the audit's `gh` queries against `/rulesets`, `/actions/secrets`, and `/environments/*` return 403 and the affected checks are recorded as `UNVERIFIABLE` rather than `FAIL`. To upgrade them to `PASS`, mint a fine-grained PAT on an admin's account with read-only `Administration` + `Secrets` + `Environments` scoped to `diffplug/dormouse` only, then store it env-scoped:
+
+```bash
+gh secret set AUDIT_PAT --env security-audit --repo diffplug/dormouse --body 'github_pat_…'
+```
+
 - FAIL IF `.github/workflows/security-audit.yaml` is missing, disabled, or no longer invoked from `release.yml`'s publish path.
 - FAIL IF the audit has been weakened — e.g. the prompt no longer requires the qualitative pass, a `FAIL IF` can be ignored, or the failure-reporting step that opens a `security-audit-failure` issue and exits non-zero has been removed.