voidforge-build 23.19.0 → 23.21.0

package/dist/docs/patterns/nginx-vhost.conf

@@ -0,0 +1,156 @@
+# nginx vhost — Cloudflare-Flexible-compatible reverse proxy with ACME passthrough
+#
+# Reference implementation for a per-tenant origin vhost that sits behind
+# Cloudflare in *Flexible* SSL mode (browser<->Cloudflare is HTTPS, but
+# Cloudflare<->origin is plain HTTP on :80). Use this when the origin app
+# does NOT terminate TLS itself and Cloudflare fronts the zone.
+#
+# Evidence: field report #344 F2 (origin 301 HTTP->HTTPS redirect loops on
+# Cloudflare Flexible zones) and #344 F4a (missing/origin-level security header
+# stack + per-tenant log isolation).
+#
+# When to use it:
+#   - Cloudflare zone SSL mode = Flexible, origin speaks HTTP only.
+#   - You want the security header stack applied at the origin so it survives
+#     even if a Cloudflare Transform/Response-Header rule is removed.
+#   - You need Let's Encrypt http-01 (ACME) to keep working through the proxy.
+#
+# When NOT to use it (use a TLS-terminating vhost instead):
+#   - Cloudflare SSL mode = Full or Full (strict): the origin must serve HTTPS
+#     and you SHOULD redirect HTTP->HTTPS. Adding the 301 below would NOT loop
+#     in that mode. This template deliberately omits the redirect for Flexible.
+#
+# Install:
+#   - Copy to /etc/nginx/sites-available/<tenant>.conf, edit the @@PLACEHOLDERS@@,
+#     symlink into sites-enabled/, then `nginx -t && systemctl reload nginx`.
+#   - Replace @@SERVER_NAME@@, @@UPSTREAM@@, @@TENANT@@ before loading.
+#
+# Placeholders:
+#   @@SERVER_NAME@@  -> e.g. app.example.com
+#   @@UPSTREAM@@     -> origin app host:port, e.g. 127.0.0.1:3000
+#   @@TENANT@@       -> short slug used for log filenames, e.g. acme-corp
+
+# ---------------------------------------------------------------------------
+# Rate-limit zone declaration.
+#
+# IMPORTANT (field report #344 F4a): limit_req_zone is an http{}-context-only
+# directive. It MUST live in the top-level http{} block (e.g. nginx.conf or a
+# file in conf.d/ that is included at http scope) — it is NOT valid inside a
+# server{} or location{} block and `nginx -t` will reject it there with
+# "limit_req_zone directive is not allowed here".
+#
+# Declare the zone ONCE at http{} scope, then *apply* it per-location with
+# `limit_req` (which IS valid in server{}/location{}). The line below is shown
+# here for reference only — move it to your http{} context:
+#
+#   limit_req_zone $binary_remote_addr zone=@@TENANT@@_perip:10m rate=20r/s;
+#
+# The WebSocket upgrade map below is ALSO http{}-context-only — declare it once
+# at http{} scope alongside the rate-limit zone, not inside server{}:
+#
+#   map $http_upgrade $connection_upgrade {
+#       default upgrade;
+#       ''      close;     # plain HTTP keep-alive: send Connection: close-able
+#   }
+# ---------------------------------------------------------------------------
+
+upstream @@TENANT@@_origin {
+    # Origin application. keepalive reduces TCP churn on the proxy hop.
+    server @@UPSTREAM@@;
+    keepalive 32;
+}
+
+server {
+    listen 80;
+    listen [::]:80;
+    server_name @@SERVER_NAME@@;
+
+    # --- Per-tenant access/error logs (field report #344 F4a) -------------
+    # Isolated per tenant so one tenant's traffic/errors never contaminate
+    # another's audit trail. Ensure /var/log/nginx exists and is writable.
+    access_log /var/log/nginx/@@TENANT@@.access.log combined;
+    error_log  /var/log/nginx/@@TENANT@@.error.log warn;
+
+    # --- ACME http-01 passthrough (field report #344 F4a) -----------------
+    # Let's Encrypt validates by fetching /.well-known/acme-challenge/<token>
+    # over plain HTTP. This location MUST be reachable on :80 and MUST NOT be
+    # redirected or proxied to the app, or certificate issuance/renewal fails.
+    # Point root at the webroot your ACME client writes challenges into.
+    location ^~ /.well-known/acme-challenge/ {
+        default_type "text/plain";
+        root /var/www/acme;
+        # No proxy here — serve the challenge token straight from the webroot.
+        # NOTE: nginx add_header inheritance is replace-not-merge, but a block
+        # with zero add_header of its own inherits the parent's. The security
+        # headers declared at server{} scope below are thus also emitted here;
+        # that is harmless for a bare token response. If you must strip them on
+        # this path, redeclare the headers you want (or none) inside this block.
+        try_files $uri =404;
+    }
+
+    # --- Security header stack (field report #344 F4a) --------------------
+    # Applied at the origin so the posture survives even if a Cloudflare
+    # response-header rule is later removed. `always` ensures the headers are
+    # emitted on error responses (4xx/5xx) too, not just 2xx/3xx.
+    #
+    # HSTS-aware: behind Cloudflare Flexible the browser<->edge leg is HTTPS,
+    # so advertising HSTS is correct for the public hostname. Start with a
+    # short max-age while validating, then raise to 1y + preload once certain
+    # the apex and every subdomain are HTTPS-only at the edge.
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    # frame-ancestors is the modern replacement for X-Frame-Options; both are
+    # sent for backward compatibility with older user agents.
+    add_header Content-Security-Policy "frame-ancestors 'self'" always;
+    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+
+    # --- Reverse proxy to the origin app ----------------------------------
+    # NOTE (field report #344 F2): there is deliberately NO
+    #   `return 301 https://$host$request_uri;`
+    # and NO `if ($http_x_forwarded_proto != "https") { return 301 ...; }`
+    # here. On a Cloudflare *Flexible* zone the edge talks HTTP to the origin,
+    # so any origin-level HTTP->HTTPS redirect produces an infinite redirect
+    # loop (ERR_TOO_MANY_REDIRECTS). Let Cloudflare handle the HTTPS upgrade
+    # at the edge. If you switch the zone to Full/Full-strict, terminate TLS
+    # at the origin and add the redirect in a separate :80 server block.
+    location / {
+        # Apply the http{}-scoped rate-limit zone here (this is the valid
+        # context for limit_req; the zone itself is declared at http{} scope
+        # per the note at the top of this file).
+        limit_req zone=@@TENANT@@_perip burst=40 nodelay;
+
+        proxy_pass http://@@TENANT@@_origin;
+        proxy_http_version 1.1;
+
+        # Preserve client + protocol context for the app. X-Forwarded-Proto is
+        # taken from Cloudflare's CF-Visitor / the edge; default to https since
+        # the public-facing leg is HTTPS even though this hop is HTTP.
+        proxy_set_header Host              $host;
+        proxy_set_header X-Real-IP         $remote_addr;
+        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_set_header X-Forwarded-Host  $host;
+
+        # WebSocket / upgrade support. $connection_upgrade is the http{}-scoped
+        # map declared at the top of this file: it sends "upgrade" for WS and
+        # "close" for plain HTTP. This single directive replaces the conflicting
+        # `Connection "upgrade"` + `Connection ""` pair and lets keepalive to
+        # the upstream coexist with WebSocket upgrades.
+        proxy_set_header Upgrade    $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+
+        proxy_connect_timeout 5s;
+        proxy_send_timeout    60s;
+        proxy_read_timeout    60s;
+
+        proxy_buffering on;
+    }
+
+    # Lightweight health endpoint that bypasses the app, for the edge/monitor.
+    location = /healthz {
+        access_log off;
+        default_type "application/json";
+        return 200 '{"status":"ok"}';
+    }
+}

package/dist/docs/patterns/oauth-token-lifecycle.ts

@@ -8,6 +8,20 @@
  * - Failure escalation: retry 3x → pause platform → alert → requires_reauth
  * - Token stored as encrypted blob in vault, keyed by platform name
  * - Session token (daemon) rotates every 24 hours (§9.19.15)
+ * - VERIFY EXPIRY + REFRESH-GRANT BEHAVIOR AGAINST THE PROVIDER'S LIVE DOCS AT
+ *   INTEGRATION TIME. The PLATFORM_CONFIGS TTLs below are STARTING ASSUMPTIONS,
+ *   not ground truth — providers change them and "no refresh token / never
+ *   expires" is a common false assumption. Field report #373: a Todoist
+ *   integration shipped on "tokens don't expire," but the modern API issues
+ *   ~1h access tokens WITH a refresh token; the code discarded the refresh
+ *   token + expiry and registered no refresher, so it died ~1h after every
+ *   connect across four sessions — looking exactly like intermittent
+ *   revocation. At integration time: (1) read the provider's OAuth docs and
+ *   quote the verified access-token TTL + whether a refresh_token is issued;
+ *   (2) if a refresh_token exists, PERSIST it and register a refresher — never
+ *   discard it; (3) distinguish "expired" from "revoked" via the API's OWN
+ *   error body, not by inference (an expired token that mimics revocation will
+ *   send you reauth-hunting instead of refreshing).
  *
  * Agents: Breeze (platform relations), Dockson (vault)
  *
@@ -50,6 +64,13 @@ interface PlatformTokenConfig {
   revokeEndpoint?: string;
 }
 
+// ASSUMPTIONS, NOT GROUND TRUTH (field report #373). These TTLs and the
+// "refreshTokenTtlDays: 0 = never expires" entries are starting points. At
+// integration time, VERIFY each value against the provider's current OAuth
+// docs and the live token response (`expires_in`, presence of `refresh_token`)
+// — a provider that "doesn't expire" today may issue ~1h tokens tomorrow, and
+// a missing refresher then surfaces as recurring prod token-death that mimics
+// revocation. Treat any new platform here the same way before shipping.
 const PLATFORM_CONFIGS: PlatformTokenConfig[] = [
   { platform: 'meta',     accessTokenTtlHours: 1440, refreshTokenTtlDays: 0,  refreshEndpoint: 'https://graph.facebook.com/v19.0/oauth/access_token' },
   { platform: 'google',   accessTokenTtlHours: 1,    refreshTokenTtlDays: 0,  refreshEndpoint: 'https://oauth2.googleapis.com/token' },

package/dist/docs/patterns/post-deploy-probe.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# Post-Deploy Probe — Assert sensitive paths are NOT publicly served.
+#
+# Reference implementation for .claude/commands/deploy.md Step 4.5.
+# Probes a denylist of paths against a live deploy URL.
+#
+# CONTENT-AWARE, NOT STATUS-ONLY (field report #371). A Single-Page App with a
+# catch-all route returns HTTP 200 for EVERY path — /.env, /.git/config,
+# /id_rsa — by serving index.html. A status-only probe reads those 200s as
+# "EXPOSED" and would trigger a ROLLBACK of a clean deploy (false positive),
+# while a real leak that happens to 200 looks identical to the shell. So we
+# assert on CONTENT and Content-Type, not status alone:
+#   - 200 + text/html shell (<!doctype html> / <html)            -> PASS  (SPA fallback)
+#   - 200 + non-HTML body (KEY=VALUE, JSON, PEM, "ref:", binary) -> EXPOSED (real leak)
+#   - non-200                                                    -> PASS  (not served)
+# A real .env leak is text/plain `KEY=VALUE`; a .git/config is an INI `[core]`
+# block; an id_rsa is a `-----BEGIN ... PRIVATE KEY-----` PEM. None are HTML.
+#
+# Evidence: field reports #305 (32-day credential leak), #303 (methodology
+# exposure), #371 (SPA catch-all status-only false-positive → would-be rollback).
+#
+# Usage:
+#   DEPLOY_URL=https://example.com bash docs/patterns/post-deploy-probe.sh
+#   DEPLOY_URL=https://example.com DEPLOY_PROBE_EXTRA=$'/admin\n/private.key' bash docs/patterns/post-deploy-probe.sh
+
+set -euo pipefail
+
+: "${DEPLOY_URL:?DEPLOY_URL is required (e.g. https://example.com)}"
+
+# Strip trailing slash for clean URL composition.
+DEPLOY_URL="${DEPLOY_URL%/}"
+
+TMP="$(mktemp -t postdeploy-probe.XXXXXX)"
+BODY="$(mktemp -t postdeploy-body.XXXXXX)"
+cleanup() { rm -f "$TMP" "$BODY"; }
+trap cleanup EXIT INT TERM
+
+# Fixed denylist — mirrors Step 4.5 in .claude/commands/deploy.md.
+DENYLIST=(
+  "/.env"
+  "/.env.production"
+  "/.env.local"
+  "/.git/config"
+  "/.git/HEAD"
+  "/.claude/agents/silver-surfer-herald.md"
+  "/docs/methods/FORGE_KEEPER.md"
+  "/HOLOCRON.md"
+  "/CHANGELOG.md"
+  "/VERSION.md"
+  "/package.json"
+  "/tsconfig.json"
+  "/id_rsa"
+  "/.ssh/id_rsa"
+)
+
+# Optional extensible denylist (newline-separated).
+if [[ -n "${DEPLOY_PROBE_EXTRA:-}" ]]; then
+  while IFS= read -r extra; do
+    [[ -n "$extra" ]] && DENYLIST+=("$extra")
+  done <<< "$DEPLOY_PROBE_EXTRA"
+fi
+
+# Decide whether a fetched path is a REAL leak vs an SPA HTML fallback.
+# Inputs: $1 status, $2 content-type header, body file at $BODY.
+# Echoes "leak" or "ok".
+classify() {
+  local status="$1" ctype="$2"
+  # Only a 200 can possibly be a leak; anything else is not served.
+  [[ "$status" == "200" ]] || { echo "ok"; return; }
+
+  # Lowercase the content-type for matching.
+  local ct; ct="$(printf '%s' "$ctype" | tr '[:upper:]' '[:lower:]')"
+
+  # An HTML response is the SPA catch-all shell, not the sensitive file. PASS.
+  if [[ "$ct" == *"text/html"* ]]; then echo "ok"; return; fi
+  # Body-sniff fallback when the server omits/mislabels Content-Type: a leading
+  # <!doctype html> or <html is the SPA shell.
+  if head -c 256 "$BODY" | tr '[:upper:]' '[:lower:]' | grep -qE '<!doctype html|<html'; then
+    echo "ok"; return
+  fi
+
+  # 200 + non-HTML body = the real file is being served. EXPOSED.
+  echo "leak"
+}
+
+hits=0
+checked=0
+
+for path in "${DENYLIST[@]}"; do
+  checked=$((checked + 1))
+  url="${DEPLOY_URL}${path}"
+  # Capture status + content-type, and the body (capped) for sniffing.
+  read -r status ctype < <(
+    curl -s -o "$BODY" --max-time 10 \
+      -w '%{http_code} %{content_type}\n' "$url" 2>/dev/null || echo "000 -"
+  )
+  verdict="$(classify "$status" "$ctype")"
+  if [[ "$verdict" == "leak" ]]; then
+    hits=$((hits + 1))
+    printf 'LEAK     %s  %-24s  -> %s\n' "$status" "$ctype" "$url" | tee -a "$TMP" >&2
+  else
+    printf 'ok       %s  %-24s  -> %s\n' "$status" "$ctype" "$url"
+  fi
+done
+
+printf '{"action":"post-deploy-probe","url":"%s","checked":%d,"hits":%d,"mode":"content-aware"}\n' \
+  "$DEPLOY_URL" "$checked" "$hits"
+
+if (( hits > 0 )); then
+  echo "[post-deploy-probe] ${hits} sensitive path(s) served as non-HTML content. Rollback and fix deploy surface." >&2
+  exit 1
+fi
+
+echo "[post-deploy-probe] clean (SPA HTML fallbacks treated as PASS)"
+exit 0

package/dist/docs/patterns/rls-test-fixture.py

@@ -0,0 +1,140 @@
+"""
+Pattern: RLS Test Fixture (db_as_app SAVEPOINT)
+
+Source: Field report #318 §5. Cara Dune (Union Station, M-05) discovered that
+Testcontainers' default `us_test` user is `SUPERUSER + BYPASSRLS=t`.
+Superusers bypass FORCE RLS at the engine level — the policy doesn't fire.
+Any test using the shared `db` fixture for cross-tenant assertions will
+silently pass even when the policy is broken.
+
+Without this pattern, RLS tests that pass in development WILL silently fail
+in production under the runtime non-owner role.
+
+Use this pattern in every Python/asyncpg + pytest project with FORCE RLS.
+The same shape ports to SQLAlchemy + sync sessions, psycopg, and Django ORM.
+"""
+
+import pytest
+import pytest_asyncio
+import asyncpg
+from contextlib import asynccontextmanager
+from typing import AsyncIterator
+
+# ── Fixtures ──────────────────────────────────────────────────────────────
+
+
+@pytest_asyncio.fixture
+async def db_as_app(db: asyncpg.Connection) -> AsyncIterator[asyncpg.Connection]:
+    """
+    Wrap the standard `db` fixture so RLS-sensitive tests run under the app
+    role (BYPASSRLS=f), not the SUPERUSER bootstrap role. Connection state
+    is restored on test teardown.
+
+    Use this fixture for any test that asserts an RLS policy fires. Use the
+    standard `db` fixture only for schema setup or admin-only operations.
+
+    Pairs with a `pg_container_app` fixture (below) that provisions an
+    app-level role with `LOGIN NOBYPASSRLS NOSUPERUSER` matching the
+    runtime DSN identity.
+    """
+    await db.execute("SAVEPOINT rls_test")
+    try:
+        await db.execute(f"SET LOCAL ROLE {APP_ROLE_NAME}")
+        # If the test sets a tenant ContextVar, wire it through:
+        #   await db.execute("SELECT set_config('app.current_org_id', $1, true)", org_id)
+        yield db
+    finally:
+        await db.execute("ROLLBACK TO SAVEPOINT rls_test")
+
+
+@pytest.fixture(scope="session")
+def app_role_name() -> str:
+    return APP_ROLE_NAME
+
+
+# ── Container provisioning (run once per test session) ────────────────────
+
+APP_ROLE_NAME = "unionstation_app"  # Match production DSN identity
+
+
+async def provision_app_role(admin_conn: asyncpg.Connection) -> None:
+    """
+    Create the runtime non-owner role inside the test container. Mirrors
+    production: NOLOGIN if password-less; LOGIN with a fixed test password
+    if the test harness needs to connect as this role directly.
+
+    NOSUPERUSER and NOBYPASSRLS are the load-bearing settings. Without these,
+    the role retains FORCE RLS bypass and the fixture buys you nothing.
+    """
+    await admin_conn.execute(f"""
+        DO $$
+        BEGIN
+            IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = '{APP_ROLE_NAME}') THEN
+                CREATE ROLE {APP_ROLE_NAME}
+                    LOGIN
+                    NOSUPERUSER
+                    NOBYPASSRLS
+                    NOCREATEDB
+                    NOCREATEROLE
+                    PASSWORD 'test_app_password';
+                GRANT USAGE ON SCHEMA public TO {APP_ROLE_NAME};
+                GRANT SELECT, INSERT, UPDATE, DELETE
+                    ON ALL TABLES IN SCHEMA public TO {APP_ROLE_NAME};
+                GRANT USAGE ON ALL SEQUENCES IN SCHEMA public TO {APP_ROLE_NAME};
+            END IF;
+        END $$;
+    """)
+
+
+# ── Usage example ─────────────────────────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_rls_blocks_cross_org_select(db_as_app: asyncpg.Connection) -> None:
+    """
+    Use db_as_app — NOT db — for any RLS-policy assertion. Under the
+    SUPERUSER `db` fixture, this test would pass even if the policy were
+    deleted.
+    """
+    await db_as_app.execute(
+        "SELECT set_config('app.current_org_id', '1', true)"
+    )
+    rows = await db_as_app.fetch("SELECT id, org_id FROM people")
+    assert all(row["org_id"] == 1 for row in rows), \
+        "RLS allowed cross-org rows under FORCE — policy is broken or role has BYPASSRLS=t"
+
+
+# ── Asynccontextmanager variant for non-pytest contexts ───────────────────
+
+
+@asynccontextmanager
+async def as_app_role(conn: asyncpg.Connection) -> AsyncIterator[asyncpg.Connection]:
+    """
+    Imperative variant of the fixture for scripts and one-off RLS exercises.
+    """
+    await conn.execute("SAVEPOINT as_app_role")
+    try:
+        await conn.execute(f"SET LOCAL ROLE {APP_ROLE_NAME}")
+        yield conn
+    finally:
+        await conn.execute("ROLLBACK TO SAVEPOINT as_app_role")
+
+
+# ── Anti-patterns ─────────────────────────────────────────────────────────
+#
+# 1. Using `db` fixture for RLS assertions. SUPERUSER bypass means
+#    every test passes regardless of policy correctness. Production blows up.
+#
+# 2. Provisioning the app role with BYPASSRLS=t "for convenience." Defeats
+#    the entire FORCE RLS deployment.
+#
+# 3. SET ROLE without SAVEPOINT. Test pollution: subsequent tests run under
+#    whichever role the previous test ended in.
+#
+# 4. Skipping ROLLBACK TO SAVEPOINT in the finally branch. Connection
+#    pooling will hand out a connection still scoped to APP_ROLE_NAME.
+#
+# 5. SET LOCAL ROLE inside an asyncpg pool callback (which runs outside any
+#    transaction). Use SET ROLE (session-scoped) plus explicit RESET ROLE
+#    on connection release. See field report #319 §1 — same trap surfaced
+#    in M-04c W3.

package/dist/docs/patterns/structural-sql-sentinel.py

@@ -0,0 +1,134 @@
+"""
+Pattern: Structural SQL Sentinel (with adversarial-test discipline)
+
+Source: Field report #319 §3. V083 sentinel #2 originally used a single regex
+matching `current_setting(...) = ''`. Three Wave 3 reviewers independently
+flagged that the regex misses commuted (`'' = current_setting(...)`),
+cast (`current_setting(...)::text = ''`), IS NULL canonical
+(`current_setting(...) IS NULL`), and coalesce-wrapped variants. Each missed
+form is a future fail-open re-introduction the sentinel is supposed to block.
+
+A single-form structural sentinel is a single point of failure. This pattern
+documents the discipline: every structural sentinel has positive controls,
+adversarial alternation tests, AND fixture-bindability proof.
+
+Use this pattern for any SQL-shape policing — fail-open detection in RLS
+policies, dangerous catalog reads, deprecated function calls, plaintext
+storage in encrypted columns.
+"""
+
+import re
+import pytest
+from typing import Iterable
+
+
+# ── The Sentinel ──────────────────────────────────────────────────────────
+
+# Comprehensive regex that matches all known fail-open forms. Each
+# alternation is a CVE-class pattern that has bitten production at least once.
+FAIL_OPEN_RE = re.compile(
+    r"""
+    (
+        # Direct equality
+        current_setting\([^)]*\)\s*=\s*''            |
+        # Commuted (Postgres doesn't canonicalize operand order)
+        ''\s*=\s*current_setting\([^)]*\)            |
+        # Cast on the function call
+        current_setting\([^)]*\)\s*::\s*\w+\s*=\s*'' |
+        # IS NULL form (treats unset GUC as fail-open)
+        current_setting\([^)]*\)\s*IS\s+NULL         |
+        # COALESCE wrap
+        coalesce\(\s*current_setting\([^)]*\)\s*,\s*''\s*\)\s*=\s*''
+    )
+    """,
+    re.IGNORECASE | re.VERBOSE,
+)
+
+
+def policy_is_fail_open(policy_qual: str) -> bool:
+    """Return True if the policy expression contains a known fail-open arm."""
+    return bool(FAIL_OPEN_RE.search(policy_qual))
+
+
+# ── Positive controls (must trigger) ─────────────────────────────────────
+
+POSITIVE_FORMS = [
+    # Direct
+    "current_setting('app.current_org_id', true) = ''",
+    # Whitespace tolerance
+    "current_setting('app.current_org_id', true)   =   ''",
+    # Commuted
+    "'' = current_setting('app.current_org_id', true)",
+    # Cast
+    "current_setting('app.current_org_id', true)::text = ''",
+    # IS NULL
+    "current_setting('app.current_org_id', true) IS NULL",
+    # COALESCE wrap
+    "coalesce(current_setting('app.current_org_id', true), '') = ''",
+]
+
+
+# ── Negative controls (must NOT trigger) ──────────────────────────────────
+
+NEGATIVE_FORMS = [
+    # The legitimate org_id check the sentinel is protecting
+    "org_id = current_setting('app.current_org_id', true)::int",
+    "org_id::text = current_setting('app.current_org_id', true)",
+    # Other unrelated comparisons
+    "deleted_at IS NULL",
+    "tenant_id = (SELECT id FROM tenants WHERE name = 'system')",
+]
+
+
+# ── Adversarial-bindability test ──────────────────────────────────────────
+
+
+@pytest.mark.parametrize("form", POSITIVE_FORMS)
+def test_sentinel_catches_fail_open_form(form: str) -> None:
+    """Every known fail-open variant must trip the sentinel."""
+    assert policy_is_fail_open(form), \
+        f"SENTINEL GAP: form did not trip — '{form}'"
+
+
+@pytest.mark.parametrize("form", NEGATIVE_FORMS)
+def test_sentinel_does_not_false_positive(form: str) -> None:
+    """Legitimate policy expressions must not trip the sentinel."""
+    assert not policy_is_fail_open(form), \
+        f"FALSE POSITIVE: legitimate form tripped — '{form}'"
+
+
+# ── Fixture-bindability proof ─────────────────────────────────────────────
+#
+# A structural sentinel is meaningful only if it can FAIL on a deliberate
+# regression. Test that, too:
+
+
+def test_sentinel_can_bind() -> None:
+    """
+    Construct a deliberate regression and assert the sentinel catches it.
+    If this assertion ever flips, either the regex was changed silently
+    or the fail-open form is no longer detectable. Either way, an alert
+    is mandatory.
+    """
+    deliberate_regression = "current_setting('x', true) = ''"
+    assert policy_is_fail_open(deliberate_regression), \
+        "BINDABILITY FAILURE: sentinel cannot fail under any input — it's a no-op"
+
+
+# ── Anti-patterns ─────────────────────────────────────────────────────────
+#
+# 1. SUBSTRING match instead of regex (LIKE '%...%'). Misses commuted, cast,
+#    and IS NULL forms. Field report #319 §3.
+#
+# 2. Single regex variant without alternation. The first migration author who
+#    writes a different form silently re-introduces the class.
+#
+# 3. Positive controls only. Without negative controls, false positives
+#    flood the alert channel and reviewers learn to ignore them.
+#
+# 4. No bindability proof. A sentinel that algebraically cannot fail is a
+#    no-op. See /docs/patterns/adr-verification-gate.md.
+#
+# 5. Sentinel lives in one place (CI grep) without a database-side mirror.
+#    Belt-and-suspenders: lint the policy text in CI AND assert
+#    policy_is_fail_open() against pg_policies.qual at runtime.

package/dist/scripts/statusline/README.md

@@ -0,0 +1,38 @@
+# Context Meter — status line + awareness hook
+
+Two small scripts that surface how full the context window is — one for the human, one for the model.
+
+| Script | Wired to | Audience | What it does |
+|--------|----------|----------|--------------|
+| `voidforge-statusline.sh` | `statusLine` (settings.json) | you | Renders one line: model + a colored meter (`⟦████████░░⟧ 78%`) + tokens remaining. Green → yellow → red as the window fills. |
+| `context-awareness-hook.sh` | `UserPromptSubmit` hook | Claude | Once usage crosses a threshold, injects "you have ~X% left, checkpoint soon" into the model's own context each turn. Silent below the threshold. |
+
+The model can't see its own remaining context. The status line tells *you*; the hook tells *Claude* — so it can wrap up open loops and suggest `/vault` or `/seal` before compaction instead of being surprised by it.
+
+## Install
+
+**Default-on.** `npx voidforge-build init` already wires both scripts into a new project's `.claude/settings.json` (warn 80% / crit 92%). Nothing to do for a fresh project.
+
+To re-install, retune, or activate on a project that predates this feature, run **`/contextmeter`** — it chmods these scripts and merges the right block into `.claude/settings.json`. Or wire it by hand: merge `settings-snippet.json` into `.claude/settings.json`. Remove with `/contextmeter --uninstall`.
+
+## How it reads context
+
+- **Status line:** prefers the native `context_window` object Claude Code pipes on stdin (`used_percentage`, `context_window_size`). Falls back to deriving usage from the most recent assistant `message.usage` in `transcript_path` on older Claude Code that doesn't send the field.
+- **Hook:** the hook stdin has no `context_window` object, so it always derives from `transcript_path` (`input_tokens + cache_read_input_tokens + cache_creation_input_tokens`).
+- 1M-token sessions are detected automatically (usage above 200k ⇒ 1,000,000 denominator), or set `VOIDFORGE_CONTEXT_WINDOW`.
+
+## Tuning (env)
+
+| Var | Default | Effect |
+|-----|---------|--------|
+| `VOIDFORGE_CONTEXT_WINDOW` | `200000` | Denominator when the size field is absent. |
+| `VOIDFORGE_CONTEXT_WARN_PCT` | `80` | Hook starts speaking — and the meter turns yellow — at this % used. |
+| `VOIDFORGE_CONTEXT_CRIT_PCT` | `92` | Hook escalates to "checkpoint NOW" — and the meter turns red — at this %. |
+
+Both scripts read the same two thresholds, so the meter's yellow/red bands stay in lockstep with the hook's warn/critical bands. `/contextmeter --warn-pct N` / `--crit-pct N` bake these into the command strings in settings.json so they persist without a shell export.
+
+## Requirements & caveats
+
+- **`jq`** is required. Without it the status line prints a one-line "install jq" notice and the hook no-ops — neither ever breaks your session.
+- Only the **first line** of status-line stdout is shown by Claude Code, so the meter is deliberately single-line.
+- **Name:** this ships as `/contextmeter`, not `/statusline` — Claude Code's native `/statusline` and `/context` commands always shadow a same-named project command (see `docs/NATIVE_CAPABILITIES.md`).