docs(observability): disambiguate audit.ts from recordAuditEvent, document gate-check-publish audit decision

src/queue/processors.ts

@@ -5238,6 +5238,14 @@ type PublicSurfaceOutputFailure = {
   error: string;
 };
 
+// Intentionally writes to check_summaries only, not audit_events (#2908): this fires on every successful gate-
+// check publish, which is a very high-frequency event (every review pass, potentially several times per PR as
+// it iterates) -- check_summaries is the purpose-built, already-queryable canonical record for "when was this
+// check published and what did it conclude" (repo/PR/headSha/checkRunId/conclusion/detailsUrl), so a parallel
+// audit_events row would roughly double that table's volume for no new queryable information. The DOWNSTREAM
+// actions this verdict triggers (merge/close/hold) are already fully audited via recordNativeGateDecision and
+// agent-action-executor's audit() closure. Only the FAILURE/degraded sub-paths of the caller below are audited
+// (auditGateCheckPermissionMissing, auditPrVisibilitySkip) -- that asymmetry is deliberate, not a gap.
 async function recordPublishedGateCheckSummary(
   env: Env,
   args: {

src/selfhost/audit.ts

@@ -2,6 +2,11 @@
 // operators can grep / pipe to their log aggregator (Loki, CloudWatch, Datadog, etc.) without any extra
 // setup. Written to process.stdout so it is captured by Docker's default json-file log driver and is
 // accessible via `docker compose logs gittensory`.
+//
+// NOT the durable audit_events DB table (#2908): this module is a stdout-only logger for exactly the 4 queue-
+// lifecycle events below, called only from sqlite-queue.ts/pg-queue.ts. For the actual queryable audit trail of
+// contributor-affecting decisions (review published, PR merged/closed, notification sent/failed, guardrail
+// hold, ...), see recordAuditEvent in ../db/repositories.ts.
 
 import { otelTraceLogFields } from "./otel";