@oneie/claude 0.7.0 → 0.8.0

package/scripts/blocks-usage.mjs

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+// The census, regenerable — text/blocks.md deliverable 2.
+//
+// Reads every row of the `pages` table (D1, --remote by default, --local on
+// request), resolves each page's block list EXACTLY the way production does
+// (data column when present, else componentsToPuck(parseComponents(components))
+// — see one.ie/web/src/pages/u/[slug]/p/[pageSlug].astro), tallies pagesUsing
+// (distinct pages with >=1 instance) and instances (total instances) per
+// registered block name, cross-references nonPageRefs (uses of the name
+// outside one.ie/web/src/lib/puck/), and writes
+// one.ie/web/src/lib/puck/block-usage.json.
+//
+// --check: regenerate in memory and diff against the committed file's
+// `blocks` map (measuredAt excluded from the diff). Runs with NO network/D1
+// access as long as the committed file already exists.
+//
+// Usage:
+//   node .claude/scripts/blocks-usage.mjs              # --remote, write the file
+//   node .claude/scripts/blocks-usage.mjs --local       # read local D1 instead
+//   node .claude/scripts/blocks-usage.mjs --check        # diff, no write, no D1 unless file missing
+
+import { execFileSync } from 'node:child_process'
+import { writeFileSync, readFileSync, existsSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const REPO_ROOT = path.resolve(__dirname, '../..')
+const WEB_DIR = path.join(REPO_ROOT, 'one.ie/web')
+const CONFIG_PATH = path.join(WEB_DIR, 'src/lib/puck/config.tsx')
+const OUT_PATH = path.join(WEB_DIR, 'src/lib/puck/block-usage.json')
+const PUCK_LIB_DIR = path.join(WEB_DIR, 'src/lib/puck')
+// GENERATED and gitignored — `src/data/promises.json` is built from text/*.md by
+// the promise-manifest step, so every block name written into a PROMISE lands in
+// `src/` and reads as a code reference. It is not one: a block named in a
+// marketing contract is not a block anything can reach. Counting it made
+// `--check` go red on a DOC edit (measured 2026-08-19: naming HeroCentered and
+// PricingSection in text/blocks.md moved ten blocks and flipped one from
+// unchosen to chosen), and worse, made the archive verdict depend on prose.
+// Redundant since the scan intersects with `git ls-files` (the file is
+// gitignored, so it is never tracked) — kept as a backstop against a stray
+// `git add -f` making prose count again.
+const PROMISES_JSON = path.join(WEB_DIR, 'src/data/promises.json')
+
+const args = process.argv.slice(2)
+const CHECK = args.includes('--check')
+const LOCAL = args.includes('--local')
+
+function readRegisteredNames() {
+  const tmp = mkdtempSync(path.join(tmpdir(), 'blocks-census-'))
+  const runner = path.join(tmp, 'names.mjs')
+  writeFileSync(
+    runner,
+    `import { puckConfig } from ${JSON.stringify(CONFIG_PATH)}\nconsole.log(JSON.stringify(Object.keys(puckConfig.components)))\n`,
+  )
+  try {
+    const out = execFileSync('bunx', ['tsx', runner], { cwd: WEB_DIR, encoding: 'utf8' })
+    return JSON.parse(out.trim())
+  } finally {
+    rmSync(tmp, { recursive: true, force: true })
+  }
+}
+
+// The census must measure the RETIRED names too, not just the 130 that survive
+// collapseFamilies. Stored pages still carry `LandingHero`, and it resolves to
+// Hero through BLOCK_ALIASES at render — so if the census only knows canonicals,
+// every collapsed family measures 0 demand and the usage-ordered palette ranks
+// them last. Measured 2026-08-18 on the first true regeneration since the cut:
+// Hero fell to pagesUsing=0 and palette-order's family-inheritance test went red.
+function readAliasNames() {
+  const tmp = mkdtempSync(path.join(tmpdir(), 'blocks-alias-'))
+  const runner = path.join(tmp, 'aliases.mjs')
+  writeFileSync(
+    runner,
+    `import { BLOCK_ALIASES } from ${JSON.stringify(path.join(WEB_DIR, 'src/lib/puck/families.ts'))}\nconsole.log(JSON.stringify(Object.keys(BLOCK_ALIASES ?? {})))\n`,
+  )
+  try {
+    const out = execFileSync('bunx', ['tsx', runner], { cwd: WEB_DIR, encoding: 'utf8' })
+    return JSON.parse(out.trim())
+  } finally {
+    rmSync(tmp, { recursive: true, force: true })
+  }
+}
+
+function readPagesRows() {
+  const flag = LOCAL ? '--local' : '--remote'
+  const out = execFileSync(
+    'bunx',
+    ['wrangler', 'd1', 'execute', 'one-owners', flag, '--json', '--command', 'SELECT slug, workspace, components, data FROM pages'],
+    { cwd: WEB_DIR, encoding: 'utf8', maxBuffer: 1024 * 1024 * 256 },
+  )
+  const parsed = JSON.parse(out)
+  return parsed[0]?.results ?? []
+}
+
+// Mirrors one.ie/web/src/pages/u/[slug]/p/[pageSlug].astro's resolution order:
+// data column wins when present and parseable; else derive from legacy
+// components via componentsToPuck(parseComponents(...)).
+function resolveBlockNames(row) {
+  const names = []
+  let content = null
+  if (row.data) {
+    try {
+      const parsed = JSON.parse(row.data)
+      content = Array.isArray(parsed?.content) ? parsed.content : null
+    } catch {
+      content = null
+    }
+  }
+  if (!content) {
+    let sections = []
+    try {
+      const raw = typeof row.components === 'string' ? JSON.parse(row.components) : row.components
+      if (Array.isArray(raw)) {
+        sections = raw.filter((e) => e && typeof e === 'object' && typeof e.component === 'string')
+      }
+    } catch {
+      sections = []
+    }
+    content = sections.map((s) => ({ type: s.component }))
+  }
+  for (const block of content) {
+    const type = block && typeof block === 'object' ? block.type : null
+    if (typeof type === 'string') names.push(type)
+  }
+  return names
+}
+
+function computeUsage(rows, registered) {
+  const pagesUsing = new Map()
+  const instances = new Map()
+  for (const name of registered) {
+    pagesUsing.set(name, 0)
+    instances.set(name, 0)
+  }
+  for (const row of rows) {
+    const names = resolveBlockNames(row)
+    const seenOnThisPage = new Set()
+    for (const name of names) {
+      if (!instances.has(name)) continue // not a registered block (dead name, alias, etc.)
+      instances.set(name, instances.get(name) + 1)
+      seenOnThisPage.add(name)
+    }
+    for (const name of seenOnThisPage) {
+      pagesUsing.set(name, pagesUsing.get(name) + 1)
+    }
+  }
+  return { pagesUsing, instances }
+}
+
+// nonPageRefs: how many files OUTSIDE lib/puck/ mention this component name
+// (social composer, mail renderer, etc.) — a block reachable from there is
+// CHOSEN even at zero page instances.
+function computeNonPageRefs(registered) {
+  const result = new Map()
+  for (const name of registered) result.set(name, 0)
+  let out
+  try {
+    out = execFileSync(
+      'grep',
+      ['-rl', '-E', `\\b(${registered.map(escapeRe).join('|')})\\b`, path.join(WEB_DIR, 'src')],
+      { encoding: 'utf8', maxBuffer: 1024 * 1024 * 64 },
+    )
+  } catch (err) {
+    // grep exits 1 when nothing matches — that's a valid empty result, not an error.
+    out = err.stdout ?? ''
+  }
+  const tracked = trackedSourceFiles()
+  const files = out
+    .split('\n')
+    .filter(Boolean)
+    .filter((f) => tracked.has(f))
+    .filter((f) => !f.startsWith(PUCK_LIB_DIR + path.sep) && f !== CONFIG_PATH && f !== PROMISES_JSON)
+    .filter((f) => !f.includes('.test.') && !f.includes('/tests/'))
+  for (const file of files) {
+    let text
+    try {
+      text = readFileSync(file, 'utf8')
+    } catch {
+      continue
+    }
+    for (const name of registered) {
+      const re = new RegExp(`\\b${escapeRe(name)}\\b`)
+      if (re.test(text)) result.set(name, result.get(name) + 1)
+    }
+  }
+  return result
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+// The census is a claim about the REPO, so the scan must read what git tracks,
+// not what happens to be sitting on disk. A regenerate run during a neighbour's
+// half-finished work otherwise records references that do not exist in the
+// repo — measured 2026-08-19: an uncommitted src/components/speed/SpeedMetrics.tsx
+// from a concurrent session contributed Timeline and Stats refs to the committed
+// census. Locally-MODIFIED tracked files still count: the bar is tracked, not
+// clean, because a modified file is still a file the repo has.
+function trackedSourceFiles() {
+  let out
+  try {
+    out = execFileSync('git', ['ls-files', '-z', '--', 'src'], {
+      cwd: WEB_DIR,
+      encoding: 'utf8',
+      maxBuffer: 1024 * 1024 * 64,
+    })
+  } catch (err) {
+    throw new Error(`blocks-usage: git ls-files failed — cannot tell tracked from untracked: ${err.message}`)
+  }
+  const files = new Set(
+    out
+      .split('\0')
+      .filter(Boolean)
+      .map((rel) => path.join(WEB_DIR, rel)),
+  )
+  // A broken sensor must never degrade quietly: an empty or implausibly small
+  // tracked set would zero every nonPageRefs and read as "archive everything".
+  // 2474 files were tracked under one.ie/web/src when this floor was measured.
+  if (files.size < 500) {
+    throw new Error(`blocks-usage: git ls-files returned only ${files.size} files under one.ie/web/src — refusing to census a repo this scan cannot see`)
+  }
+  return files
+}
+
+function buildCensus() {
+  const registered = readRegisteredNames().sort()
+  // registered ∪ retired-but-reachable — see readAliasNames above
+  const measured = [...new Set([...registered, ...readAliasNames()])].sort()
+  const rows = readPagesRows()
+  const { pagesUsing, instances } = computeUsage(rows, measured)
+  const nonPageRefs = computeNonPageRefs(measured)
+  const blocks = {}
+  let chosen = 0
+  for (const name of measured) {
+    const pu = pagesUsing.get(name) ?? 0
+    const inst = instances.get(name) ?? 0
+    const npr = nonPageRefs.get(name) ?? 0
+    blocks[name] = { pagesUsing: pu, instances: inst, nonPageRefs: npr }
+    if (pu > 0 || npr > 0) chosen++
+  }
+  return {
+    measuredAt: new Date().toISOString().slice(0, 10),
+    registered: registered.length,
+    measured: measured.length,
+    chosen,
+    unchosen: measured.length - chosen,
+    blocks,
+  }
+}
+
+function diffBlocks(committed, fresh) {
+  const lines = []
+  const names = new Set([...Object.keys(committed.blocks ?? {}), ...Object.keys(fresh.blocks)])
+  for (const name of [...names].sort()) {
+    const a = committed.blocks?.[name]
+    const b = fresh.blocks[name]
+    if (!a) {
+      lines.push(`+ ${name} ${JSON.stringify(b)}`)
+      continue
+    }
+    if (!b) {
+      lines.push(`- ${name} ${JSON.stringify(a)}`)
+      continue
+    }
+    if (a.pagesUsing !== b.pagesUsing || a.instances !== b.instances || a.nonPageRefs !== b.nonPageRefs) {
+      lines.push(`~ ${name} committed=${JSON.stringify(a)} fresh=${JSON.stringify(b)}`)
+    }
+  }
+  if (committed.registered !== fresh.registered) lines.push(`~ registered committed=${committed.registered} fresh=${fresh.registered}`)
+  if (committed.chosen !== fresh.chosen) lines.push(`~ chosen committed=${committed.chosen} fresh=${fresh.chosen}`)
+  if (committed.unchosen !== fresh.unchosen) lines.push(`~ unchosen committed=${committed.unchosen} fresh=${fresh.unchosen}`)
+  return lines
+}
+
+function main() {
+  if (CHECK) {
+    if (!existsSync(OUT_PATH)) {
+      console.error(`blocks-usage --check: ${OUT_PATH} does not exist — run without --check first to seed it.`)
+      process.exit(1)
+    }
+    const committed = JSON.parse(readFileSync(OUT_PATH, 'utf8'))
+    const fresh = buildCensusOffline(committed)
+    const diff = diffBlocks(committed, fresh)
+    if (diff.length > 0) {
+      console.error('blocks-usage --check: drift detected')
+      for (const line of diff) console.error(line)
+      process.exit(1)
+    }
+    console.log('blocks-usage --check: ok (no drift)')
+    process.exit(0)
+  }
+
+  const census = buildCensus()
+  writeFileSync(OUT_PATH, JSON.stringify(census, null, 2) + '\n')
+  console.log(`wrote ${OUT_PATH} — registered=${census.registered} chosen=${census.chosen} unchosen=${census.unchosen}`)
+}
+
+// In --check mode, re-derive registered names + nonPageRefs from the committed
+// file's OWN key set. This lets --check run with zero D1/network access when
+// the caller doesn't need a live page-usage recompute (i.e. it trusts the
+// committed pagesUsing/instances numbers and only re-verifies name/ref shape).
+// If a live D1 recheck is wanted, delete block-usage.json and re-run without
+// --check first.
+function buildCensusOffline(committed) {
+  // --check runs with no D1: it re-derives only the source-scanned half
+  // (nonPageRefs) and trusts the committed D1 half. The name set is therefore
+  // whatever the committed file measured — registered UNION retired — so it
+  // must NOT be reported as `registered`, which counts actual registrations.
+  const measuredNames = Object.keys(committed.blocks ?? {}).sort()
+  const nonPageRefs = computeNonPageRefs(measuredNames)
+  const blocks = {}
+  let chosen = 0
+  for (const name of measuredNames) {
+    const pu = committed.blocks[name]?.pagesUsing ?? 0
+    const inst = committed.blocks[name]?.instances ?? 0
+    const npr = nonPageRefs.get(name) ?? 0
+    blocks[name] = { pagesUsing: pu, instances: inst, nonPageRefs: npr }
+    if (pu > 0 || npr > 0) chosen++
+  }
+  return {
+    measuredAt: committed.measuredAt,
+    registered: committed.registered,
+    measured: measuredNames.length,
+    chosen,
+    unchosen: measuredNames.length - chosen,
+    blocks,
+  }
+}
+
+main()

package/scripts/deploy-dev.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# deploy-dev.sh - ship one.ie/web to https://dev.one.ie (worker `one-dev`).
+#
+# THE TWO-TIER RULE:
+#   dev.one.ie  - agents finish loops here. MINIMUM gate: the fast lane only.
+#   one.ie      - humans promote here. FULL gate: ./deploy (FULL_VERIFY=1).
+# A fast pass is never reported as a full pass.
+set -euo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+WEB="$ROOT/one.ie/web"
+cd "$WEB"
+
+echo "[deploy-dev] target: https://dev.one.ie  worker: one-dev"
+
+# 2. the MINIMUM gate - fast lane, through the governor. Never the full suite.
+if [ "${DEV_SKIP_GATE:-0}" = "1" ]; then
+  echo "[deploy-dev] gate SKIPPED (DEV_SKIP_GATE=1) - you asked for it"
+else
+  echo "[deploy-dev] gate: FAST LANE (not a full pass)"
+  bash "$ROOT/.claude/scripts/gate-run.sh" devgate -- bun run verify:fast
+fi
+
+# 3. build + ship against the dev config
+bash "$ROOT/.claude/scripts/gate-run.sh" devbuild -- bun run build
+
+# derive the dev config FROM the astro build output, so it can never drift from
+# what production actually ships (and so `main` + the assets binding come along)
+python3 "$ROOT/.claude/scripts/gen-dev-config.py" || exit 1
+npx wrangler deploy --config dist/server/wrangler.dev.json
+
+# 4. prove it answers
+code=$(curl -s -o /dev/null -w '%{http_code}' https://dev.one.ie/ --max-time 20 || echo 000)
+echo "[deploy-dev] https://dev.one.ie -> HTTP $code"
+[ "$code" = "200" ] || { echo "[deploy-dev] FAILED - dev.one.ie did not answer 200"; exit 1; }
+echo "[deploy-dev] done. Promote to production with: ./deploy   (full gate, human decision)"

package/scripts/deploy-gate-check.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# deploy-gate-check.sh — red proofs for the deploy gate wrappers. Ships nothing,
+# deploys nothing, touches no service. Exits non-zero on failure.
+#
+# manifest: monorepo-only
+#
+# WHY. deploy.sh grew a memoised test gate, a cached build gate, and a rule that
+# an unpaid deferred-pin debt refuses a deploy. Each is a place a gate could
+# quietly stop biting, and a wiring check that only greps for a string proves
+# nothing about behaviour. So the deferred-pin block is EXTRACTED VERBATIM from
+# deploy.sh and executed against stubs -- a copy of it here would prove only that
+# the copy works.
+set -uo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+DEPLOY="$ROOT/.claude/scripts/deploy.sh"
+fails=0
+
+# --- deploy must NOT have re-wired tsc through the shared-lock cache --------
+# It was wired that way for one commit and reverted on measurement: the five
+# typechecks are 8s serial on a warm box and finish inside vitest's shadow, while
+# tsc-cached.sh takes the same gate_lock do-reconcile.sh takes -- so a concurrent
+# /do cycle could make the ship gate queue 900s and then go RED over nothing.
+if grep -qE 'gate_start(_governed)? "tsc-\$\(echo "\$svc" \| tr / -\)" "\$svc" bunx tsc --noEmit' "$DEPLOY"; then
+  echo "ok: typechecks run bare (no shared lock on the ship path)"
+else
+  echo "FAIL: the typecheck gate no longer runs bare — check the lock-contention note in deploy.sh"; fails=$((fails+1))
+fi
+
+# --- deploy must still call the cached build, not a bare `bun run build` -----
+if grep -q 'gate_start_heavy build one.ie/web bash "\$ROOT/.claude/scripts/astro-build-cached.sh"' "$DEPLOY"; then
+  echo "ok: the build gate routes through astro-build-cached.sh"
+else
+  echo "FAIL: the build gate no longer routes through astro-build-cached.sh"; fails=$((fails+1))
+fi
+# --- and the vitest gate must keep its pty, or it hangs on a log file --------
+# The assertion names test-full.sh, NOT test-cached.sh, and that is the whole
+# point of the edit that put it here. deploy.sh used to spell the vitest argv out
+# itself and call test-cached.sh directly; test-full.sh was then created as the
+# ONE definition of the full suite so deploy and /close could not present
+# different argv to the memo and miss each other's stamps. This grep kept naming
+# the old call, so it emitted "the vitest gate lost TEST_CACHE_PTY" over wiring
+# that was correct -- a FALSE RED on a ship gate, which is the failure mode that
+# gets a gate ignored. The pty is still set, twice: here, and per-lane at
+# test-lanes.sh:102/107.
+if grep -q 'TEST_CACHE_PTY=1 bash "\$ROOT/.claude/scripts/test-full.sh"' "$DEPLOY"; then
+  echo "ok: the vitest gate runs through test-full.sh with a pty"
+else
+  echo "FAIL: the vitest gate lost TEST_CACHE_PTY — it will hang on a non-TTY stdout"; fails=$((fails+1))
+fi
+
+# --- and the memo behind that gate must actually MISS when the tree moves ----
+# The line above is a wiring grep. This drives the real thing on one small
+# selection: a cold MISS, then a HIT on identical inputs, then a MISS again after
+# a source file the selection reads is edited. Without the third step a memo that
+# always hit would look perfect -- and would hand deploy a green suite over a
+# changed tree, which is the only way this optimisation can ship bad code.
+_SEL="tests/unit/agents/subscribe-tags-parity.test.ts"
+_SRC="one.ie/web/src/lib/in/spaces.ts"
+if [ ! -d "$ROOT/one.ie/web/node_modules" ] || [ ! -f "$ROOT/$_SRC" ]; then
+  # An unrunnable check is n/a. Never ok: a worktree without node_modules cannot
+  # start vitest, and a startup crash exits non-zero for reasons that have
+  # nothing to do with the property under test.
+  echo "n/a: no one.ie/web/node_modules here — the memo drive cannot run (NOT a pass)"
+else
+  _mc="$(mktemp -d)"; _memo() { TEST_CACHE_DIR="$_mc" bash "$ROOT/.claude/scripts/test-cached.sh" \
+        one.ie/web -- --reporter=dot "$_SEL" 2>&1; }
+  m1="$(_memo)"; r1=$?
+  m2="$(_memo)"; r2=$?
+  if [ "$r1" -ne 0 ] || [ "$r2" -ne 0 ]; then
+    echo "n/a: the probe selection did not pass, cannot measure the memo (NOT a pass)"
+  else
+    case "$m1" in *"cache HIT"*) echo "FAIL: a cold cache reported a HIT"; fails=$((fails+1));;
+      *) echo "ok: a cold memo MISSES and runs the tests";; esac
+    case "$m2" in *"cache HIT"*) echo "ok: identical inputs HIT the memo";;
+      *) echo "FAIL: identical inputs did not hit — the memo buys nothing"; fails=$((fails+1));; esac
+    # RED PROOF — move a source file the selection reads; the memo MUST miss.
+    cp "$ROOT/$_SRC" "$_mc/src.bak"
+    echo "// __deploy_gate_check_probe" >> "$ROOT/$_SRC"
+    m3="$(_memo)"
+    cp -f "$_mc/src.bak" "$ROOT/$_SRC"
+    case "$m3" in *"cache HIT"*) echo "FAIL: a CHANGED tree replayed a cached PASS"; fails=$((fails+1));;
+      *) echo "ok: a source edit invalidates the memo";; esac
+  fi
+  rm -rf "$_mc"
+fi
+# --- the deferred-pin ledger: driven, not grepped ---------------------------
+# Extract deploy.sh's debt block verbatim and run it with stubbed reporters. The
+# block is the last chance a deferred pin has to come due: verify-fast.sh settles
+# the ledger only in its own FULL_VERIFY branch, and deploy sets FULL_VERIFY=1 but
+# invokes the suite directly -- so before this block existed, a production deploy
+# shipped straight over pins that no run had ever executed.
+_debt_block="$(awk '/^DEBT_FILE=/{f=1} f{print} f&&/^fi$/{exit}' "$DEPLOY")"
+if [ -z "$_debt_block" ]; then
+  echo "FAIL: could not extract the debt block from deploy.sh — this checker is blind"; fails=$((fails+1))
+else
+  _drive_debt() { # <ledger-contents|""> <SKIP_TESTS> <TESTS_REPORT>
+    local led; led="$(mktemp)"
+    [ -n "$1" ] && printf '%s\n' "$1" > "$led" || : > "$led"
+    VERIFY_FAST_DEBT_FILE="$led" SKIP_TESTS="$2" TESTS_REPORT="$3" LOG=/dev/null \
+      bash -c '
+        say(){ printf "%s\n" "$*"; }; step(){ :; }; ok(){ printf "ok %s\n" "$*"; }
+        die(){ printf "DIE %s\n" "$*"; exit 1; }
+        '"$_debt_block"'
+        exit 0' >/dev/null 2>&1
+    local rc=$?; rm -f "$led"; return $rc
+  }
+  # RED PROOF — an outstanding debt with a SKIPPED suite must refuse the deploy.
+  if _drive_debt "pins deferred at cycle C3" 1 "skipped"; then
+    echo "FAIL: an unpaid pin debt did NOT refuse a --skip-tests deploy"; fails=$((fails+1))
+  else echo "ok: an unpaid pin debt refuses a test-skipping deploy"; fi
+  # RED PROOF — the same debt with no suite REPORT must refuse too (an unrun gate
+  # is not a passing gate, whatever the flags said).
+  if _drive_debt "pins deferred at cycle C3" 0 "skipped"; then
+    echo "FAIL: an unpaid debt passed with no suite result"; fails=$((fails+1))
+  else echo "ok: an unpaid debt with no suite result refuses"; fi
+  # GREEN half — a debt paid by a green full suite must let the deploy through,
+  # or the two proofs above are just a gate that always says no.
+  if _drive_debt "pins deferred at cycle C3" 0 "Tests 10780 passed"; then
+    echo "ok: a green full suite settles the debt and the deploy continues"
+  else echo "FAIL: a green full suite did not settle the debt"; fails=$((fails+1)); fi
+  # and an EMPTY ledger must never block anything
+  if _drive_debt "" 1 "skipped"; then echo "ok: no debt, no refusal"
+  else echo "FAIL: an empty ledger blocked the deploy"; fails=$((fails+1)); fi
+fi
+
+echo ""
+[ "$fails" -eq 0 ] && { echo "deploy-gate-check: PASS"; exit 0; }
+echo "deploy-gate-check: FAILED ($fails)"; exit 1