chore(#417): quality-review pass — empty-generation belt, CI-matched readiness budget, index row grouping

- --check refuses to compare when the fresh generation produced no
  output (README.md missing): two-empty-dirs would otherwise diff clean,
  and a silent generation failure must never read as up to date.
- Postgres readiness wait aligned to ci.yml's smoke-test budget for the
  same image (30 x 2s, was 30 x 1s with no stated reason).
- Decision-index row for #417 grouped with the other Conventions rows.

Author: mforce

docs/decisions/README.md

@@ -31,10 +31,10 @@ follow the `→` link from the `AGENTS.md` bullet to get here.
 | [SPA E2E lives in `tools/simulation/ui/` (#277/#385)](277-spa-e2e.md) | AGENTS · Conventions |
 | [A write-contract change must update its non-CI callers (#394)](394-write-contract-callers.md) | AGENTS · Conventions |
 | [Production logs: compact JSON on stdout (#404)](404-production-logs.md) | AGENTS · Conventions |
+| [Generated PostgreSQL schema documentation (#417)](417-schema-docs.md) | AGENTS · Conventions |
 | [Writing a guard (a test that asserts an invariant)](407-writing-a-guard.md) | AGENTS · Writing a guard |
 | [CI security gates, lock-file healing, Dependabot, action pinning (#146)](146-ci-security-gates.md) | AGENTS · CI security gates |
 | [Releases and image publishing — internals (#351)](351-releases.md) | AGENTS · Releases · and `README.md` |
-| [Generated PostgreSQL schema documentation (#417)](417-schema-docs.md) | AGENTS · Conventions |
 
 The five short-enough Conventions bullets that kept their full rationale inline in
 `AGENTS.md` — break-glass recovery (#265), farm timezone (#264), the proxy-trust

tools/schema-docs/generate.sh

@@ -48,10 +48,11 @@ docker run -d --name "$PG" --network "$NET" \
   -p 127.0.0.1:0:5432 \
   "$POSTGRES_IMAGE" >/dev/null
 
+# Same 60s readiness budget as ci.yml's smoke test uses for this image.
 for i in $(seq 1 30); do
   if docker exec "$PG" pg_isready -h 127.0.0.1 -U cluckwork -d cluckwork >/dev/null 2>&1; then break; fi
   if [ "$i" = 30 ]; then echo "Postgres never became ready" >&2; exit 1; fi
-  sleep 1
+  sleep 2
 done
 
 PORT="$(docker inspect -f '{{ (index (index .NetworkSettings.Ports "5432/tcp") 0).HostPort }}' "$PG")"
@@ -97,6 +98,12 @@ if [ "$MODE" = "generate" ]; then
 else
   TMP_OUT="$(mktemp -d)"
   run_tbls "-v ${TMP_OUT}:/schema-check" "/schema-check"
+  # A generation that silently produced nothing must never read as "up to
+  # date" — README.md is the one file every tbls run emits.
+  if [ ! -f "$TMP_OUT/README.md" ]; then
+    echo "Schema-docs generation produced no output — refusing to compare." >&2
+    exit 1
+  fi
   if ! diff -r docs/schema "$TMP_OUT" >/dev/null 2>&1; then
     echo "docs/schema/ is STALE — it does not match what the migrations produce." >&2
     echo "Regenerate with: tools/schema-docs/generate.sh" >&2