docs: reflect security posture — TS 6.0, CodeQL hardening, dependency triage (#28)

Additive docs for this session's security work: AGENTS.md stack TS 5.9->6.0 +
Security automation subsection; SECURITY.md least-privilege workflow permissions
note + new "Dependency security & vulnerability triage" policy (in-range fixes,
execution-path triage, dismiss "not used"). No content removed.

Author: adammerrill

AGENTS.md

@@ -4,7 +4,7 @@
 
 **astro-gcp-cloudrun-starter** is a production-ready, open-source GitHub template that deploys an **Astro v6 + Tailwind CSS v4** static site to **Google Cloud Run** with a zero-secrets, keyless, Terraform-managed foundation. The front end is derived from the AstroWind theme; the project adds a complete GCP/IaC/CI layer and a 5-phase web-optimization pass (performance, GEO, styling, components, conversion).
 
-**Stack:** Astro v6 | Tailwind CSS v4 | TypeScript 5.9 | MDX | Sharp · Docker (nginx:8080) · Google Cloud Run · Terraform · GitHub Actions (keyless WIF)
+**Stack:** Astro v6 | Tailwind CSS v4 | TypeScript 6.0 | MDX | Sharp · Docker (nginx:8080) · Google Cloud Run · Terraform · GitHub Actions (keyless WIF)
 
 **Public-repo rule:** nothing sensitive ever enters files, history, or CI logs. Identity is keyless (Workload Identity Federation, scoped to this repo); only `.example` placeholders are committed. App runtime secrets → Google Secret Manager.
 
@@ -112,9 +112,17 @@ Hero images use `loading="eager"` and `fetchpriority="high"` (LCP). Non-hero ima
 - `.github/workflows/ci.yml` runs on PRs: `npm run check`, Docker build, `terraform validate` (all envs), and a **Lighthouse CI** Core Web Vitals budget.
 - `deploy-dev/staging/prod.yml` are **app-deploy-only** (build image → push to Artifact Registry → deploy Cloud Run revision → smoke test). Terraform is run deliberately, not from CI.
 
+### Security automation
+
+Layered, defense-in-depth scanning — full runbook in `SECURITY.md`:
+
+- **Secret scanning** — `.github/workflows/secret-scan.yml` (Gitleaks SARIF + TruffleHog `--only-verified`), a Gitleaks pre-commit hook (`.githooks/pre-commit` / `.pre-commit-config.yaml`), and GitHub push protection.
+- **Code scanning (SAST)** — CodeQL on every PR; findings surface under **Security → Code scanning**. Keep it clean: workflows declare least-privilege `permissions:` (e.g. `ci.yml` is `contents: read`), and avoid the patterns CodeQL flags (e.g. complete, case-insensitive URL-scheme checks in `src/utils/permalinks.ts`).
+- **Dependencies** — Dependabot **version updates** (`.github/dependabot.yml`, weekly grouped: npm / github-actions / docker) plus security updates. See `SECURITY.md` → "Dependency security & vulnerability triage" for how transitive, dev/build-only advisories are assessed (execution-path exposure) and remediated or dismissed.
+
 ## Documentation
 
-All guides live in `docs/` and are indexed in `README.md` (deploy/infra + the 5-phase web-optimization docs).
+All guides live in `docs/` and are indexed in `README.md` (deploy/infra + the 5-phase web-optimization docs). Security tooling and the dependency/vulnerability response runbook are in `SECURITY.md`.
 
 ## Verification Checklist
 

SECURITY.md

@@ -68,6 +68,10 @@ Security**). Current state:
   on enablement). Findings appear under **Security → Code scanning**, alongside
   the Gitleaks SARIF from Layer 2.
 - ✅ **Copilot Autofix** — AI-suggested fixes for CodeQL alerts.
+- ✅ **Least-privilege workflows** — CI workflows declare an explicit
+  `permissions:` block (e.g. `ci.yml` is `contents: read`) so `GITHUB_TOKEN`
+  isn't granted broad default scopes. This clears CodeQL's "Workflow does not
+  contain permissions" alerts and is the standard for any new workflow.
 - Check-runs failure threshold: Security = **High or higher**, Standard = **Only
   errors**. To _block merges_ on these alerts, create a branch ruleset
   (**Settings → Rules**) that requires the code-scanning check.
@@ -87,6 +91,36 @@ Security**). Current state:
 
 > To review or change any of these: **Settings → Advanced Security**.
 
+## Dependency security & vulnerability triage
+
+Dependabot opens **version-update** PRs (weekly, grouped) and **security-update**
+PRs. Routine flow: let CI (`npm run check` + Docker build + Lighthouse + CodeQL)
+gate each PR, then merge group/patch/minor bumps when green; review majors
+(e.g. TypeScript 6.0) deliberately before merging.
+
+Not every alert has a clean fix — especially **transitive, dev/build-only**
+packages pinned by a parent (e.g. `esbuild` via `vite`). Triage by **execution
+path**, not severity label alone:
+
+1. **Is a non-breaking fix in range?** Prefer it. A locked transitive version can
+   lag the allowed range — `npm update <pkg>` bumps it without changing
+   `package.json` (this is how `vite` was moved 7.3.3 → **7.3.5** to fix
+   CVE-2026-53571, within the existing `^7` override). **Never** take a fix that
+   force-downgrades a core dep (e.g. `npm audit fix --force` proposing an ancient
+   `astro`).
+2. **Is the vulnerable code actually reachable here?** This ships as a **static
+   site** — Astro builds HTML in Linux CI, served by **nginx with no Node
+   runtime**. Advisories that only affect a dev server, a non-npm runtime
+   (Deno), or an OS we don't build on are **not in the execution path**. If so,
+   and no in-range fix exists, **dismiss the alert** in **Security → Dependabot
+   alerts** with reason **"Vulnerable code is not actually used"** and a one-line
+   justification. Re-evaluate if the dependency later enters a runtime path.
+3. **Stale alerts** (the flagged package is no longer in `package-lock.json`)
+   auto-close on the next dependency-graph scan; dismiss if they linger.
+
+Record non-obvious decisions in the PR or the dismissal note so the rationale is
+auditable.
+
 ## Allowlist rationale (why the gate isn't noisy)
 
 `.gitleaks.toml` allowlists values that match secret-shaped patterns but are