From 00e426fde9536c85535692c324ff68a4229a33ed Mon Sep 17 00:00:00 2001
From: Kishore Kumar <nkishore@megam.io>
Date: Thu, 14 May 2026 10:45:33 +0530
Subject: [PATCH] =?UTF-8?q?docs(agents):=20trim=20PUB=20GATE=20=E2=80=94?=
 =?UTF-8?q?=20delegate=20consumer-grep=20to=20zlint=20unused-decls?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The PUB GATE was enforcing two things that overlapped: (1) mechanical
"every pub has a consumer" verification, which zlint's unused-decls:error
already fails the build on, and (2) the design call — shape verdict
(file-as-struct vs conventional) + no-inheritance (don't clone a sibling's
justification).

Overlap (1) is now delegated explicitly. The gate body keeps the design
call, which is unique to the agent: zlint can't decide whether a new pub fn
belongs on a struct or as a free fn, and it can't detect "I cloned the
sibling's reasoning verbatim instead of doing my own grep + verdict".

Per-edit proof block compresses from "consumers + shape + no-inheritance"
to "shape verdict + no-inheritance" — roughly half the ceremony per pub.

Changes:
- AGENTS.md row 10 — gate description trimmed; consumer-grep moved to zlint.
- docs/gates/pub-surface.md — pre-edit step 3 (consumer-grep loop) and step 4
  (manual orphan sweep) replaced with "shape verdict per new surface, no
  inheritance"; required output drops the per-symbol consumer= field;
  self-audit notes the load-bearing make lint run.
- AGENTS_INVARIANCE.md Q4.4 + Q4.4a — rephrased to match new contract;
  Q4.4b (per-edit proof-line) and Q4.4c (threshold-as-floor) unchanged.
- docs/ZIG_RULES.md ZLint Policy — unused-decls:error marked load-bearing
  with the cross-reference back to PUB GATE so future ruleset trims don't
  silently bypass the gate.

Size: 25548 / 25600 bytes (52 under). All 17 audit checks PASS.

Reviewed surface: §10a code commit in M68 trigger-DX worktree uses the
new trimmed proof format.
---
 AGENTS.md                 |  2 +-
 AGENTS_INVARIANCE.md      |  4 ++--
 docs/ZIG_RULES.md         |  1 +
 docs/gates/pub-surface.md | 18 +++++++-----------
 4 files changed, 11 insertions(+), 14 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 2b43c9e..379d463 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -105,7 +105,7 @@ Guards fire pre-hoc regardless of lifecycle stage. Override: `<GATE>: SKIPPED pe
 | 7 | Milestone-ID Gate | `docs/gates/milestone-id.md` | Saving source / config outside `docs/`. Regex `M[0-9]+_[0-9]+`, `§X.Y`, `T7`, `dim N.M` · `MILESTONE ID ALLOWED per user override (reason: ...)` in preceding comment. |
 | 8 | Architecture Consult & Update Gate | `docs/gates/architecture.md` | Naming a stream/channel/Redis namespace/queue/RPC/Postgres schema; describing a flow; mid-task architecture question — grep relevant `docs/architecture/` · **no override** — doc wins until reconciled. |
 | 9 | ZIG GATE | `docs/gates/zig.md` | `*.zig` outside `vendor/`/`third_party/`/`.zig-cache/` (tests in scope) · `ZIG GATE: SKIPPED per user override (reason: ...)`. |
-| 10 | Pub Surface & Struct-Shape Gate | `docs/gates/pub-surface.md` | New `*.zig` under `src/`; threshold-cross (first pub type / first method-on-pub-free-fn-dominant / last pub free fn removed); **any new `^pub` line in new-bytes** (threshold list is a floor, not a ceiling) · `PUB GATE: SKIPPED per user override (reason: ...)`. **`FILE SHAPE DECISION` skip needs user's explicit ask this turn — auto-mode does NOT cover.** **No inheritance:** each new pub surface requires its own consumer-grep + shape verdict; cloning a sibling's "Public for the integration test in …" comment does NOT discharge. **Per-edit proof-line mandatory** (full block OR one-line `PUB GATE: skipped — <reason>`); silent gate-clean edits are violations. |
+| 10 | Pub Surface & Struct-Shape Gate | `docs/gates/pub-surface.md` | New `*.zig` under `src/`; threshold-cross (first pub type / first method-on-pub-free-fn-dominant / last pub free fn removed); **any new `^pub` line in new-bytes** (threshold list is a floor, not a ceiling) · `PUB GATE: SKIPPED per user override (reason: ...)`. **`FILE SHAPE DECISION` skip needs user's explicit ask this turn — auto-mode does NOT cover.** Consumer-grep delegated to `zlint`'s `unused-decls: error`; body enforces **shape verdict** + **no inheritance** (own verdict per surface; do not inherit sibling justifications). **Per-edit proof-line mandatory** (full block OR one-line `PUB GATE: skipped — <reason>`); silent gate-clean edits are violations. |
 | 11 | UI Component Substitution Gate | `docs/gates/ui-substitution.md` | `*.tsx`/`*.jsx` under `ui/packages/app/`. Raw HTML (`<section>`/`<button>`/`<input>`/`<article>`/`<dialog>`/`<dl>`/`<table>`/`<nav>`/`<header>`/`<form>`) → design-system primitive (`asChild` for HTML semantics) · `UI GATE: SKIPPED per user override (reason: ...)`. |
 | 12 | DESIGN TOKEN GATE | `docs/gates/design-token.md` | `*.tsx`/`*.jsx` under `ui/packages/app/` or `ui/packages/website/`. Blocks `*-[...]` arbitraries (`text-[Npx]`, `leading-[...]`, `tracking-[...]`, `max-w-[Npx|Nch]`, `text-[clamp(...)]`, raw palette) when token utility exists in `theme.css` · `// DESIGN TOKEN: SKIPPED per user override (reason: ...)` immediately preceding the line; auto-mode does NOT cover; reason must cite a concrete external constraint. |
 | 13 | UFS GATE | `docs/gates/ufs.md` | Source under `src/`, `ui/packages/*/`, `zombiectl/` matching `*.zig`/`*.ts`/`*.tsx`/`*.js`/`*.jsx`. Repeat string literals → named const; semantic numeric literals → named const; cross-runtime constants share identifier verbatim across Zig/TS/JS. Pin-test exception requires `// pin test: literal is the contract` · `UFS GATE: SKIPPED per user override (reason: ...)`; auto-mode does NOT cover. |
diff --git a/AGENTS_INVARIANCE.md b/AGENTS_INVARIANCE.md
index 5e54fab..10d8cbe 100644
--- a/AGENTS_INVARIANCE.md
+++ b/AGENTS_INVARIANCE.md
@@ -64,8 +64,8 @@ The questionnaire is organised by scenario. Each scenario corresponds to a momen
 | 4.1c (UI) | Does the project-side `scripts/audit-design-tokens.sh --diff` audit run as part of `make lint` (`_website_lint` + `_app_lint`) and block on any arbitrary that has a token equivalent? | YES |
 | 4.2 (Zig) | For every `*.zig` Edit/Write outside `vendor/`/`third_party/`/`.zig-cache/`, does ZIG GATE fire? | YES |
 | 4.3 (Zig) | Must FILE SHAPE DECISION print before the first Write to a new `*.zig` under `src/` — and is that override **not** covered by auto-mode? | YES |
-| 4.4 (Zig) | Does PUB GATE require external-consumer grep proof for every new `pub` symbol? | YES |
-| 4.4a (Zig) | Does AGENTS.md prohibit inheriting a sibling's `pub fn` decision — i.e. does every new pub surface require its own consumer-grep + shape verdict, and does cloning a sibling's "Public for the integration test in …" comment NOT discharge the gate? | YES |
+| 4.4 (Zig) | Does PUB GATE delegate mechanical consumer-grep to `zlint`'s `unused-decls: error` rule (run by `make lint`), leaving the gate body to enforce shape verdict + no-inheritance + per-edit proof? | YES |
+| 4.4a (Zig) | Does AGENTS.md prohibit inheriting a sibling's `pub fn` decision — i.e. does every new pub surface require its own shape verdict, and does cloning a sibling's "Public for the integration test in …" comment NOT discharge the gate? | YES |
 | 4.4b (Zig) | Does AGENTS.md require a per-edit proof-line (full block OR one-line `PUB GATE: skipped — <reason>`) before every `*.zig` Edit/Write, so silent gate-clean edits are still violations (the proof of consideration is part of the discipline)? | YES |
 | 4.4c (Zig) | Does the PUB GATE trigger set explicitly include "any new `^pub` line in new-bytes" (the pre-edit grep at body §1), so the threshold list (first pub type / first method on pub-free-fn-dominant / last pub free fn removed) is a floor, not a ceiling? | YES |
 | 4.5 (Zig) | Is cross-compile to `x86_64-linux` AND `aarch64-linux` mandatory before commit? | YES |
diff --git a/docs/ZIG_RULES.md b/docs/ZIG_RULES.md
index 543f8c7..ae9bc4b 100644
--- a/docs/ZIG_RULES.md
+++ b/docs/ZIG_RULES.md
@@ -66,6 +66,7 @@ For every commit that touches `*.zig`, the agent runs the workflow below — no
 
 - This repo uses `zlint` as part of `make lint`.
 - Pinned version: `v0.7.9`.
+- **`unused-decls: error` is load-bearing.** PUB GATE (`docs/gates/pub-surface.md`) delegates mechanical consumer-grep to this rule — a `pub` without an in-tree consumer fails `make lint`. Disabling or downgrading it silently bypasses half the gate; if you must, amend PUB GATE in the same diff so the design call is captured elsewhere.
 - `suppressed-errors` stays off because this repo intentionally uses narrow `pg` cleanup patterns that a generic rule cannot classify correctly.
 - `unsafe-undefined` is a good future tightening target once current low-level uses are cleaned up or annotated.
 - A disabled ZLint is not useful; prefer a scoped ruleset that passes today and tightens over time.
diff --git a/docs/gates/pub-surface.md b/docs/gates/pub-surface.md
index 042602f..aa7c824 100644
--- a/docs/gates/pub-surface.md
+++ b/docs/gates/pub-surface.md
@@ -19,11 +19,13 @@ For all other `*.zig` edits, the full block is skipped with a one-liner: `PUB GA
 
 Two `docs/ZIG_RULES.md` rules:
 
-1. **`pub` only when an external file imports the symbol** — default private; strip stale `pub`s when touching a file.
+1. **`pub` only when an external file imports the symbol** — default private; strip stale `pub`s when touching a file. *Mechanical enforcement is delegated to `zlint`'s `unused-decls: error` rule*, which fails `make lint` for any `pub` without an in-tree consumer. The gate body no longer requires a per-symbol consumer-grep in the proof block.
 2. **File-as-struct shape is the default for new behavior-bound-to-state files.** A file *is* a struct in Zig — modeling that shape exposes ownership and testability cheaply. Conventional layout (multi-type modules, parsers/DSLs, constants modules, pub-free-fn-dominant modules, tagged-union dispatch tables, "operations over a passive value") **must be justified at PLAN**, not chosen by inertia.
 
 **Tie-break:** behavior-bound-to-state → file-as-struct; operations-over-value → conventional. **Escape clause:** "I can articulate in one sentence why this is operations-over-value." If you can't, file-as-struct wins.
 
+**No inheritance:** each new pub surface needs its own *shape verdict* — cloning a sibling's "Public for the integration test in …" justification does NOT discharge. Mechanical consumer-grep is `zlint`'s job; the design call is yours, and it does not transfer between symbols.
+
 ## File-as-struct layout
 
 ```zig
@@ -70,21 +72,15 @@ Skipping this block is a PLAN violation, not just an EXECUTE one.
    - new variant on a pub error union: `ErrorUnion{… NewVariant,`
    - new variant on a pub enum: `= enum { … NewVariant,`
 2. Count primary types in the file (struct/union/enum the file is "about"); choose layout: file-as-struct (count = 1, all pub fns take `self`) or conventional (otherwise).
-3. List every new `pub` symbol the edit introduces (top-level + variant additions); for each, grep external consumer:
-
-   ```
-   grep -rn "<symbol>" src/ tests/ --include="*.zig"
-   ```
+3. List every new `pub` symbol the edit introduces and confirm its shape verdict matches the file's chosen layout. Each new symbol gets its own verdict — do not inherit from a sibling.
 
-   → file:line, or `NONE`. Strip `pub` from any with `NONE`.
-4. Progressive cleanup on touch: `grep -n "^pub " <file>` and audit existing `pub`s in the same diff.
+Mechanical consumer-grep is no longer part of this checklist: `zlint`'s `unused-decls: error` rule (enabled in `zlint.json`, run by `make lint`) fails the build on any `pub` without an in-tree consumer. The gate body owns the design call (shape verdict + no inheritance); zlint owns "did you forget to strip a dead pub?"
 
 ## Required output (when fires)
 
 ```
 PUB GATE: <file> | types=<0|1|>1> | layout=<file-as-struct|conventional> (<why>)
-  New: <sym> consumer=<file:line>|NONE→strip; <sym> consumer=...
-  Audited: <K> kept · <M> stripped
+  New: <sym>, <sym>, …
 ```
 
 If no new `pub` symbols and the file is not new, the gate is a no-op — skip the printable block.
@@ -97,7 +93,7 @@ git diff -U0 HEAD -- '*.zig' \
   | head
 ```
 
-Non-empty = new pub surface this turn; verify a PUB GATE block was printed before each corresponding Edit/Write.
+Non-empty = new pub surface this turn; verify a PUB GATE block (with shape verdict) was printed before each corresponding Edit/Write. The end-of-turn `make lint` run is also load-bearing: if `zlint` reports `unused-decls`, you skipped stripping a dead `pub` and the gate did not fail loud enough.
 
 For new-file FILE SHAPE coverage: