feat(hcg): add surface-drift check script (standards#100 §1.5) (#228)

## Summary

Adds `scripts/hcg-surface-drift-check.sh`: a static, source-only audit
that asserts every wired `BojRest.Router` route is covered by at least
one rule in the HCG live Verb Governance Spec
(`config/gateway-policy-boj.yaml`).

The ADR's largest declared risk is **"policy lagging the surface"** —
a wired route landing without a matching policy rule would default-deny
in production (an outage on a route that should be live). The live
policy header carries a manual re-verification stamp
(`Re-verified 2026-05-28 against BojRest.Router`) which is the only
check today that catches this; the §1.5 prerequisite checklist relies
on the same manual procedure. This script makes the check
machine-checkable without changing any policy content, runbook
procedure, or gateway code.

### What the script does

1. Extracts `(verb, path-template)` tuples from
   `elixir/lib/boj_rest/router.ex` (Plug.Router `get "/…"` / `post "/…"`
   etc.).
2. Extracts `(verb, path-pattern)` tuples from
   `config/gateway-policy-boj.yaml`.
3. For each wired route, concretises `:name`-style placeholders with a
   known probe segment and asserts at least one policy rule matches
   (literal equality for non-regex paths; ERE `grep -E` match against
   the concrete URL for `^…` regex paths).
4. Exit 0 on no drift, 1 on drift detected, 64 on bad usage.

### Bracket-style relationship with `hcg-policy-smoke.sh`

- **Smoke script** (`hcg-policy-smoke.sh`) — runs against a *live
  gateway* to confirm the policy enforces as declared (deny/allow
  paths, stealth-status canaries, default-deny no-match canary).
- **Drift check** (this PR) — runs against the *source files* to
  confirm the policy still covers the wired surface.

Together they cover both halves of the §1.5 pre-rollout verification:
surface→policy coverage (drift) and policy→gateway enforcement (smoke).

### What this PR does NOT do

- Does **not** modify the rollout runbook §1.5. Adoption as the §1.5
  surface-drift check is a separate, owner-driven PR; this PR lands
  the artefact only so the runbook update is a one-line wiring change.
- Does **not** wire the script into CI. Boj-server's CI discipline
  (`docs/wikis/CI-and-Required-Checks.adoc` / `.claude/CLAUDE.md`)
  requires path-filtered required checks to use the "always-trigger +
  changes job" pattern; a CI wiring PR should follow that pattern.
  Out of scope here.
- Does **not** modify any policy file. Today's surface and today's
  policy are in agreement (the 2026-05-28 re-verification still holds;
  the script run on this commit's working tree returns OK on the seven
  wired routes: `/.well-known/boj-node-pubkey`, `/health`, `/menu`,
  `/cartridges`, `/cartridge/:name`, `/cartridge/:name/invoke`,
  `/cartridge/:name/sse`).
- Does **not** pre-empt the §6.4 Trustfile flip
  (`tier_2_gateway.status` stays `PENDING`).
- Per single-lane HCG channel discipline (pattern set in
  `http-capability-gateway` PRs #14, #22, #26, #30, #38 and `boj-server`
  PRs #168, #173, #224, #226): joint-close is owner-only. **This PR
  refs but does not close `standards#100`.**

### Channel state note

This session could not read `hyperpolymath/standards#91` / `#100` (the
session's repository scope is restricted to `http-capability-gateway`
and `boj-server`), so the brief's instructed status comment on
`standards#91` could not be posted. State was reconstructed from the
canonical sources in this repo (ADR-0004, the integration plan, the
audit, the rollout runbook, the live policy, and the merged-PR
commit history) plus the current `main` of both in-scope repos. The
analysis: Phase A/B/C/D are closed (artefacts merged, runbook §1.2 and
the Phase-D status note in the runbook header confirm); Phase E
(`standards#100`) is the only open phase; all remaining §1 checklist
items are owner-driven (`!OWNER:` placeholders, D-4 rebaseline
workflow_dispatch, cerro-torre `.ctp` signing, the §6.4 Trustfile flip).
This PR advances Phase E §1.5 ("Gateway-side prerequisites") by
converting one manual sub-check into an executable artefact, without
crossing into any owner-input territory.

## Test plan

- [ ] Run the script on this branch's working tree: `bash
  scripts/hcg-surface-drift-check.sh` — expect exit 0, "OK: every wired
  router route is covered by at least one policy rule." with the
  wired-count = 7 and the policy-count matching the rule total in
  `config/gateway-policy-boj.yaml`.
- [ ] Run `bash scripts/hcg-surface-drift-check.sh -v` — expect the
  same exit 0 plus a `Matched:` block listing each of the seven wired
  routes against its policy rule (literal `/health` → literal rule;
  `/cartridge/:name/invoke` → `^/cartridge/[A-Za-z0-9_.-]+/invoke$`
  regex; etc.).
- [ ] Synthetic drift test: temporarily add a wired route to the
  router (e.g. `get "/__drift_test__" do …`) without a policy rule;
  re-run and expect exit 1 with the route listed under `DRIFT:`.
  Revert before merge.
- [ ] Confirm `shellcheck scripts/hcg-surface-drift-check.sh` is clean
  (matches `scripts/hcg-policy-smoke.sh`'s shellcheck posture).
- [ ] Confirm SPDX header + Owner copyright match the canonical estate
  format (matches `scripts/hcg-policy-smoke.sh`'s header shape).
- [ ] Verify no Hypatia / governance / spdx gates fire on the new
  script file.

Refs hyperpolymath/standards#91
Refs hyperpolymath/standards#100

🤖 Generated with [Claude Code](https://claude.com/claude-code)


---
_Generated by [Claude
Code](https://claude.ai/code/session_01JuztZ5kyDr3AqGtUsBipDL)_

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: hyperpolymath

scripts/hcg-surface-drift-check.sh

@@ -0,0 +1,259 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+#
+# hcg-surface-drift-check.sh — Asserts that every wired BoJ HTTP route
+# is covered by at least one rule in the HCG live Verb Governance Spec.
+#
+# The HCG live policy file (`config/gateway-policy-boj.yaml`) carries a
+# manual re-verification stamp ("Re-verified DATE against BojRest.Router
+# for HCG tier-2 rollout"). The ADR's largest declared risk is "policy
+# lagging the surface": a wired route landing without a matching policy
+# rule would default-deny in production (an outage on a route that
+# should be live), and the manual stamp is the only check today that
+# catches this.
+#
+# This script automates the same check so the stamp becomes machine-
+# checkable. Algorithm:
+#
+#   1. Extract (verb, path-template) tuples from
+#      `elixir/lib/boj_rest/router.ex` — every `get "/..."`,
+#      `post "/..."`, etc. at the top level of the router module.
+#   2. Extract (verb, path-pattern) tuples from
+#      `config/gateway-policy-boj.yaml` — every `- path: "..."` /
+#      `verbs: [...]` pair under `governance.routes`.
+#   3. For each wired route, concretise its `:name`-style placeholders
+#      with a known probe segment (`probe`, matching the smoke
+#      script) and assert at least one policy rule matches:
+#        * literal policy path → exact equality with the concrete URL
+#        * regex policy path (leading `^`) → `grep -E` match against
+#          the concrete URL
+#      The router method must be in the policy rule's verb list.
+#   4. Report any wired-but-ungoverned routes (drift) and exit 1; or
+#      exit 0 if every wired route is covered.
+#
+# Bracket-style relationship with `scripts/hcg-policy-smoke.sh`:
+#   * Smoke script runs against a *live gateway* to confirm the policy
+#     enforces as declared (deny path / allow path / stealth status).
+#   * Drift check runs against the *source files* to confirm the policy
+#     still covers the wired surface.
+# Together they cover both halves of the §1.5 pre-rollout verification:
+# surface→policy coverage (this script) and policy→gateway enforcement
+# (the smoke script).
+#
+# Usage:
+#   ./scripts/hcg-surface-drift-check.sh          # uses repo defaults
+#   ./scripts/hcg-surface-drift-check.sh -v       # verbose; list matches
+#
+# Exit codes:
+#   0  — no drift; every wired route is covered.
+#   1  — drift detected; at least one wired route has no matching rule.
+#   64 — bad usage.
+#
+# Limitations (called out so the operator does not over-trust the
+# OK result):
+#   * Parses the router with regex, not the Elixir AST. Routes declared
+#     via macros, list comprehensions, or runtime registration are NOT
+#     seen. The current router declares every route at the top level
+#     with the Plug.Router DSL, which the regex handles correctly; a
+#     future indirection would require this script to evolve.
+#   * The "concretise `:name` with a fixed probe" step assumes the
+#     policy regex character class accepts the probe segment. The
+#     current policy uses `[A-Za-z0-9_.-]+`, which accepts `probe`;
+#     a tightened class might not. Change the probe via `PROBE=` env
+#     var if needed.
+#   * Does NOT report orphan policy rules (rules with no matching
+#     router route). This is intentional: the policy governs declared-
+#     not-yet-wired routes per contract §8 (`http-capability-gateway-
+#     boj-contract.md` §8). An orphan-rule check would have to also
+#     consult `docs/specification/openapi.yaml` to suppress those
+#     intentional cases; out of scope for this script.
+#
+# Cross-refs:
+#   docs/integration/hcg-tier2-rollout-runbook.md   §1.5
+#   docs/integration/http-capability-gateway-boj-contract.md §8 ("Surface drift caveat")
+#   docs/integration/http-capability-gateway-policy-authoring.md §5 ("Review & versioning discipline")
+#   config/gateway-policy-boj.yaml                  source of truth
+#   scripts/hcg-policy-smoke.sh                     companion enforcement check
+#   standards#100                                   tracking issue
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+ROUTER_FILE="${ROUTER_FILE:-${REPO_ROOT}/elixir/lib/boj_rest/router.ex}"
+POLICY_FILE="${POLICY_FILE:-${REPO_ROOT}/config/gateway-policy-boj.yaml}"
+PROBE="${PROBE:-probe}"
+VERBOSE=0
+
+usage() {
+    cat >&2 <<'EOF'
+hcg-surface-drift-check.sh — assert wired-router-route ⊆ policy-rules.
+
+USAGE:
+  hcg-surface-drift-check.sh [-v] [-h]
+
+OPTIONS:
+  -v        Verbose; print each wired route and the policy rule
+            that matches it.
+  -h        Show this help.
+
+ENV:
+  ROUTER_FILE   Override router path (default elixir/lib/boj_rest/router.ex).
+  POLICY_FILE   Override policy path (default config/gateway-policy-boj.yaml).
+  PROBE         Placeholder segment substituted for `:name`-style
+                router parameters (default "probe").
+
+EXIT CODES:
+  0  no drift; every wired route covered by a policy rule.
+  1  drift detected (at least one wired route has no match).
+  64 bad usage.
+
+Cross-refs:
+  docs/integration/hcg-tier2-rollout-runbook.md §1.5
+  scripts/hcg-policy-smoke.sh                   companion check
+EOF
+    exit 64
+}
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        -v) VERBOSE=1; shift ;;
+        -h|--help) usage ;;
+        *) echo "unknown arg: $1" >&2; usage ;;
+    esac
+done
+
+[ -f "$ROUTER_FILE" ] || { echo "router file not found: $ROUTER_FILE" >&2; exit 1; }
+[ -f "$POLICY_FILE" ] || { echo "policy file not found: $POLICY_FILE" >&2; exit 1; }
+
+# 1. Wired routes from router.ex.
+#
+# Plug.Router DSL: top-level `get "/foo"` / `post "/foo"` etc. Output
+# format: VERB<TAB>/path/template, one route per line. The router's
+# `match _` catch-all is intentionally not captured.
+wired=$(
+    grep -E '^[[:space:]]*(get|post|put|delete|patch|head|options)[[:space:]]+"[^"]+"' "$ROUTER_FILE" \
+    | awk '{
+        verb_lc = $1
+        # POSIX-portable upper-case via tr in a subshell.
+        cmd = "printf %s " verb_lc " | tr a-z A-Z"
+        cmd | getline VERB
+        close(cmd)
+        # Extract the path inside the first pair of double quotes.
+        line = $0
+        sub(/^[^"]*"/, "", line)
+        sub(/".*/, "", line)
+        print VERB "\t" line
+      }'
+)
+
+# 2. Policy rules from gateway-policy-boj.yaml.
+#
+# Each rule is a `- path: "..."` line under `governance.routes:`,
+# followed (on a later indented line) by `verbs: [GET, POST, ...]`.
+# We expand the verb list to one row per (verb, path) so the matching
+# loop below stays a single nested for-loop. Comments outside the
+# routes block are skipped because the regexes do not match them.
+policy=$(
+    awk '
+    /^[[:space:]]*-[[:space:]]+path:[[:space:]]*"/ {
+        line = $0
+        sub(/^[^"]*"/, "", line)
+        sub(/".*/, "", line)
+        cur_path = line
+        next
+    }
+    /^[[:space:]]+verbs:[[:space:]]*\[/ {
+        line = $0
+        sub(/^[^\[]*\[/, "", line)
+        sub(/\].*/, "", line)
+        gsub(/[[:space:]]/, "", line)
+        n = split(line, vs, ",")
+        for (i = 1; i <= n; i++) {
+            print vs[i] "\t" cur_path
+        }
+    }
+    ' "$POLICY_FILE"
+)
+
+# 3. For each wired route, find a covering policy rule.
+#
+# Concretise `:name`-style segments with $PROBE so regex policy paths
+# (`^/cartridge/[A-Za-z0-9_.-]+/invoke$` etc.) can be tested against
+# a real URL string. The PROBE default ("probe") is shared with the
+# smoke script so a future tightening of the regex character class
+# fails both checks in lock-step instead of one silently.
+drift=0
+drift_msgs=()
+match_msgs=()
+while IFS=$'\t' read -r verb tmpl; do
+    [ -z "${verb:-}" ] && continue
+    # Substitute `:identifier` segments with the probe placeholder.
+    # `:name` → `probe`, `:cartridge_id` → `probe`, etc.
+    concrete=$(printf '%s' "$tmpl" | sed -E "s|:[a-zA-Z_][a-zA-Z0-9_]*|${PROBE}|g")
+
+    matched_rule=""
+    while IFS=$'\t' read -r p_verb p_path; do
+        [ -z "${p_verb:-}" ] && continue
+        [ "$verb" = "$p_verb" ] || continue
+        case "$p_path" in
+            \^*)
+                # Regex pattern — ERE match against the concrete URL.
+                if printf '%s' "$concrete" | grep -qE "$p_path"; then
+                    matched_rule="$p_verb $p_path"
+                    break
+                fi
+                ;;
+            *)
+                # Literal pattern — exact string equality.
+                if [ "$concrete" = "$p_path" ]; then
+                    matched_rule="$p_verb $p_path"
+                    break
+                fi
+                ;;
+        esac
+    done <<< "$policy"
+
+    if [ -z "$matched_rule" ]; then
+        drift_msgs+=("$verb $tmpl  (concrete: $concrete)")
+        drift=$((drift + 1))
+    else
+        match_msgs+=("$verb $tmpl  →  $matched_rule")
+    fi
+done <<< "$wired"
+
+echo "==> HCG surface drift check"
+echo "    Router file: $ROUTER_FILE"
+echo "    Policy file: $POLICY_FILE"
+echo "    Probe placeholder: '$PROBE'"
+wired_count=$(printf '%s\n' "$wired" | grep -c . || true)
+policy_count=$(printf '%s\n' "$policy" | grep -c . || true)
+echo "    Wired (router) routes:    $wired_count"
+echo "    Policy (verb,path) rules: $policy_count"
+echo
+
+if [ "$VERBOSE" = "1" ] && [ ${#match_msgs[@]} -gt 0 ]; then
+    echo "Matched:"
+    for m in "${match_msgs[@]}"; do
+        printf '  %s\n' "$m"
+    done
+    echo
+fi
+
+if [ "$drift" -eq 0 ]; then
+    echo "OK: every wired router route is covered by at least one policy rule."
+    echo "The §1.5 re-verification stamp in config/gateway-policy-boj.yaml"
+    echo "can be advanced safely after manual review of any policy edits."
+    exit 0
+fi
+
+echo "DRIFT: $drift wired router route(s) are not covered by any policy rule:"
+for m in "${drift_msgs[@]}"; do
+    printf '  - %s\n' "$m"
+done
+echo
+echo "Resolution: add a matching rule to config/gateway-policy-boj.yaml"
+echo "(and config/gateway-policy-boj-example.yaml if the route is part of"
+echo "the pedagogical surface). See docs/integration/http-capability-"
+echo "gateway-policy-authoring.md §5 for the co-change discipline."
+exit 1