…p#892) (inkeep#3267)

* Audit merge gates lifecycle + fix public/agents husky hardening

From Nick's gating-for-merge checkpoint audit request. Five quality-gate
layers (in-vivo → pre-commit → pre-push → PR required → merge queue) are
all functional but had no canonical doc describing what runs where, and
several gaps/bugs surfaced during the audit. This PR addresses what
belongs in agents-private; cross-repo skill fixes are tracked separately.

Changes:

reports/2026-05-13-merge-gates-audit.md (new)
- Full layer-by-layer audit with file:line citations
- 4 bug-shaped findings + 4 spec-shaped gaps documented
- Recommendations split by repo ownership and decision boundaries

.github/QUALITY_GATES.md (new)
- Canonical lifecycle layering: 5-layer table, time budgets, configs
- Decision tree: "where does my new check belong?"
- Sub-agent cwd discipline section (the structural reason the
  tests-at-local-root bug exists)
- Cross-layer redundancy explanation (it's intentional)
- Common failure modes table
- Cross-refs to AGENTS.md, CI.md, CI_ARCHITECTURE.md, CI_RUNBOOK.md,
  REQUIRED_CHECKS_ROADMAP.md

AGENTS.md
- New router row pointing at .github/QUALITY_GATES.md (~199 bytes added;
  still under 40k cap)

public/agents/.husky/pre-commit
- Fix B2: change `pnpm lint-staged` to `pnpm exec lint-staged`. Mirrors
  the hardening agents-private's root .husky/pre-commit got after a real
  pnpm10 misresolution bug walked node_modules upward to user-home,
  failing every commit with MODULE_NOT_FOUND. public/agents/'s copy was
  still vulnerable when cloned standalone. Added comment block matching
  root explaining why.

NOT in this PR (tracked separately):

- B1+B3: tests-at-local-root in eng-qa/eng-debug/eng-review-local/eng-fix-bug
  skills. These live in inkeep/team-skills (external repo); editing the
  .agents/.cursor/.codex mirrors here would be overwritten by the
  cross-harness-skills-sync.yml workflow. Tracked as spawned task —
  parallel PR to inkeep/team-skills. Will sync back here automatically.

- B4: auto-merge-when-green for human PRs. 1-way door, needs Nick's
  explicit sign-off. SPEC + audit document the proposal.

- G1: check:fast tier introduction. Needs architectural scoping (which
  subset of pnpm check is "fast" vs "full"? per-subtree or root?).
  Acknowledged in QUALITY_GATES.md as Layer 1's current state.

Local verification:
- pnpm check:monorepo-traps: green
- bash -n public/agents/.husky/pre-commit: syntax OK
- cd public/agents && pnpm exec lint-staged --version: 16.2.7 (resolves)
- bash scripts/check-agents-md-size.sh: passes (38697 bytes, under 40k
  cap; warning at 35k is pre-existing)

* Move QUALITY_GATES.md cross-link out of AGENTS.md to stay under size invariant

Private PR Validation failed on `FOUNDATIONAL INVARIANT: AGENTS.md within
FAIL_AT - 1500 = 38500 bytes`. My router-row addition pushed AGENTS.md
from 38498 → 38697 (over by 197 bytes). The 1500-byte buffer below the
hard cap is deliberate per scripts/check-agents-md-size.test.mjs:8-12 —
it fires growth pressure BEFORE the runtime cap.

Resolution: revert the AGENTS.md router-row addition entirely (back to
38498 bytes); surface QUALITY_GATES.md via cross-links from
CI.md (companion-docs block) and CI_ARCHITECTURE.md (header paragraph)
instead. Both files already live alongside the new doc in `.github/`,
so the relative path is short. Discoverability preserved: anyone
hitting the existing AGENTS.md "Editing a GitHub Actions workflow"
or "Debugging a red CI run" router rows will find the link via CI.md.

* Address PR inkeep#892 bot review nits (link integrity + comment accuracy + line cites)

6 actionable items from pullfrog[bot] + claude[bot] review threads on
PR inkeep#892, all small but real:

.github/QUALITY_GATES.md
- Fix broken relative link: ../../.husky/pre-commit#L11 escapes repo
  root (404 on GitHub blob renderer). Change to ../.husky/pre-commit#L11
  to match every other relative link in the file.
- H1 sentence-case → Title Case for consistency with peer .github/
  docs (CI_ARCHITECTURE.md, CI_RUNBOOK.md, REQUIRED_CHECKS_ROADMAP.md
  all use title case).

public/agents/.husky/pre-commit
- Add the pre-existence guard for ./node_modules/.bin/lint-staged that
  agents-private's root .husky/pre-commit has (lines 25-31). The comment
  in this file claimed it "Mirrors the hardening" but only had layer 1
  (`pnpm exec`); the root has TWO layers (guard + pnpm exec). Now both
  are mirrored: a fresh clone without `pnpm install` gets an actionable
  install message instead of a less-helpful pnpm-resolution failure.
  Updated comment to describe both layers explicitly.

reports/2026-05-13-merge-gates-audit.md
- Line cite fixes: public/agents/CLAUDE.md:23 → :20 (the cite landed on
  the "Single-command iteration" line; pnpm check is at L20).
- Line cite fix: vercel-merge-group-gate.yml:30 → :31-32 (line 30 is
  the end of the runbook-pointer comment block; the `on:` key is at
  L31 and `merge_group:` at L32).
- Clarify the PR inkeep#784 reference: bot reviewer couldn't verify the
  install-skip env var on main (correctly — inkeep#784 isn't merged). Now
  reads: "still open at the time of this audit", names the actual env
  var (INKEEP_TRAP_SKIP_INSTALL_VERIFY), and explicitly states "until
  inkeep#784 merges, the env var won't appear on main."

Discarded (per bot reasoning, included for the record):
- reports/...:58 line ranges for scripts/check-pre-push.mjs point at
  config arrays (SUBTREES, PUBLIC_AGENTS_STRUCTURAL_CHECKS,
  WORKFLOW_TREE_PREFIXES) rather than the active runner code. Each
  cited range still covers the data the prose describes, and the bot
  itself labeled it "non-blocking". Leaving as-is.

GitOrigin-RevId: a8ca617b1bd7f9b96b940c9def2160dc52b6f1d5

Co-authored-by: Varun Varahabhotla <vnv-varun@users.noreply.github.com>