Fixes from Claude Code review:

1. Add merge validation for workflow_dispatch (Major)
   - Prevents analyzing unmerged PRs via manual trigger
   - Validates PR is merged before proceeding

2. Use unique HEREDOC delimiters (Major)
   - Prevents collision if PR body/comments contain "EOF"
   - Uses unique suffixes like __BODY_DELIM_7f3a9b2c__

3. Pin claude-code-action to SHA (Major)
   - Aligns with claude-code-review.yml for consistency
   - Tracks issue #892 for AJV validation bug

4. Add concurrency control (Minor)
   - Prevents race conditions on concurrent runs
   - Groups by PR number, doesn't cancel in-progress

5. Add shell error handling (Minor)
   - set -eo pipefail in all shell blocks
   - Fail fast on command errors

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat: Add closed-pr-review-auto-improver agent

Automated system that analyzes human reviewer feedback after PRs are merged
to identify generalizable improvements for the pr-review-* subagent system.

- Workflow triggers on merged PRs, extracts human/bot comments
- Agent applies 4-criteria generalizability test
- Creates draft PRs with improvements to pr-review-*.md files

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat: Add context-gathering phase for deeper comment analysis

- Include diffHunk in GraphQL query (shows code each comment is on)
- Add Phase 2 "Deep-Dive on Promising Comments" with explicit guidance:
  - Read the full file to understand broader context
  - Grep for schemas/types/patterns mentioned in comments
  - Understand the anti-pattern before judging generalizability
- Update Tool Policy to emphasize context gathering
- Renumber phases (now 6 phases total)

The agent now actively investigates each comment rather than
judging based on comment text alone.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: Apply write-agent best practices

Based on write-agent skill guidance:

1. Add near-miss example (questions/discussions ≠ reviewer feedback)
2. Strengthen Role & Mission - describe what "excellence looks like"
3. Failure modes now use contrastive examples (❌ vs ✅)
4. Phase 2 now checklist format with stop condition
5. Example shows completed checklist, not just steps

Key insight: "Stop here if you can't articulate a clear principle"
prevents vague improvements from polluting reviewers.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat: Add git time-travel for progressive context gathering

- Phase 2 now uses git rev-list + git show to see code at comment time
- Progressive gathering: diffHunk → full file → PR diff → other files
- GraphQL query now includes createdAt for all comment types
- Added git rev-list and git show to allowedTools

This ensures the agent sees what the human reviewer saw, not the
final merged state which may have fixes applied.

Co-Authored-By: Claude <noreply@anthropic.com>

* feat: Add explicit stop conditions for context gathering

Two exit paths at each level:
- EXIT A: Not generalizable (repo-specific, one-off bug, style preference)
- EXIT B: Pattern found (can articulate anti-pattern + universal principle)

Includes decision flow diagram and two contrasting examples showing
early exit (repo-specific DateUtils) vs pattern discovery (type/schema DRY).

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor: Strengthen agent per write-agent best practices

- Role & Mission: Add "what the best human analyst would do" section
- Failure modes: Add "Asserting when uncertain" with contrastive example
- Generalizability: Add confidence calibration guidance
- Add explicit conservative default: "when torn, choose lower confidence"

Per write-agent skill review: personality should describe best human
behavior, failure modes should include asserting when uncertain
(relevant for classification tasks).

Co-Authored-By: Claude <noreply@anthropic.com>

* pr-review: Add Schema-Type Derivation Discipline learnings

Pattern extracted from PR #1737 human reviewer feedback (amikofalvy):
- Types should derive from Zod schemas using z.infer<typeof schema>
- Use Pick/Omit/Partial instead of manually redefining type subsets
- Extract shared enum/union schemas instead of inline string literals

Changes:
- pr-review-types.md: New anti-pattern + analysis step 6 with detection patterns
- pr-review-consistency.md: Extended "Reuse" section to cover types

This demonstrates the closed-pr-review-auto-improver output — these are
the exact changes the agent proposed when run against PR #1737.

Co-Authored-By: Claude <noreply@anthropic.com>

* pr-review: Expand type derivation sources

Extended "Schema-Type Derivation Discipline" to cover full spectrum:
- Zod/validation schemas (z.infer)
- Database schemas (Prisma, Drizzle generated types)
- Internal packages (@inkeep/*, shared types)
- External packages/SDKs (OpenAI, Vercel AI SDK)
- Function signatures (Parameters<>, ReturnType<>)
- Existing domain types (Pick, Omit, Partial)

Added table format for clarity and comprehensive detection patterns.

Co-Authored-By: Claude <noreply@anthropic.com>

* pr-review: Add advanced type derivation patterns from codebase research

Expanded type derivation guidance based on actual patterns found in agents repo:
- Awaited<ReturnType<>> for async function returns
- keyof typeof for constants-derived types
- interface extends and intersection (&) for composition
- Discriminated unions with type guards
- satisfies operator for type-safe constants
- Re-exports for API surface boundaries
- Type duplication detection signals

Patterns sourced from agents-api codebase analysis including:
- env.ts, middleware/*, types/app.ts, domains/run/*

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* pr-review: Add Zod schema composition patterns

Added guidance for Zod schema extension/derivation patterns based on
codebase research (packages/agents-core/src/validation/schemas.ts):

- .extend() for adding/overriding fields
- .pick()/.omit() for field subsetting
- .partial() for Insert → Update schema derivation
- .extend().refine() for cross-field validation
- Anti-patterns: parallel schemas, duplicated fields

Examples from codebase:
- SubAgentInsertSchema.extend({ id: ResourceIdSchema })
- SubAgentUpdateSchema = SubAgentInsertSchema.partial()
- StopWhenSchema.pick({ transferCountIs: true })

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* pr-review: Rationalize scope between types and consistency agents

Clear separation of concerns:
- pr-review-types: Illegal states, invariants, unsafe narrowing
- pr-review-consistency: DRY, schema reuse, convention conformance

Moved to consistency:
- Zod schema composition patterns (.extend, .pick, .partial)
- Type derivation detection signals
- satisfies operator, re-exports conventions

Kept in types (type safety focus):
- Discriminated unions vs optional fields (prevents illegal states)
- Type guards vs unsafe `as` assertions
- Detection of union types without discriminants

Added cross-reference note in types agent pointing to consistency
for derivation/DRY concerns.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* closed-pr-review-auto-improver: Add exit states, skills integration, and Phase 5.5

- Add skills: pr-review-subagents-available, pr-review-subagents-guidelines, find-similar-patterns
- Add proper exit states at Phase 1, 2, and 4 (embedded in workflow, not separate section)
- Add Phase 5 step 2: "Find examples of the pattern" with judgment guidance
- Add Phase 5.5: Full file review & integration planning (scope fit, duplication check)
- Update output contract with detailed JSON structure and exit examples
- Add reviewer tagging to close the feedback loop

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* closed-pr-review-auto-improver: Add "keep agents standalone" guidance

Agents should be self-contained without cross-references to other agents.
This prevents coupling and ensures agents work correctly when read in isolation.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Recover lost skills: find-similar-patterns, pr-review-subagents-*

These skills were created in the previous session but never committed.
Recovered from conversation history.

- find-similar-patterns: Methodology for finding similar code patterns
- pr-review-subagents-available: Catalog of pr-review-* agents with scope boundaries
- pr-review-subagents-guidelines: Best practices for writing/improving reviewers

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Remove pr-review-* changes (moved to separate PR #1759)

The pr-review-consistency.md and pr-review-types.md improvements belong
in PR #1759, not this auto-improver feature branch.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: Move auto-improver to private plugin repo

Move agent and skills to inkeep/internal-cc-plugins for CI/CD-only loading:
- Removed: .claude/agents/closed-pr-review-auto-improver.md
- Removed: .agents/skills/{find-similar-patterns,pr-review-subagents-available,pr-review-subagents-guidelines}/

Updated workflow:
- Added step to clone inkeep/internal-cc-plugins
- Added --plugin-dir flag to load agent from plugin

Prerequisites before merging:
1. Create private repo: inkeep/internal-cc-plugins
2. Push plugin content to new repo
3. Add GH_PAT_PLUGINS secret to inkeep/agents

Co-Authored-By: Claude <noreply@anthropic.com>

* Switch from PAT to GitHub App for cross-repo auth

GitHub Apps provide better security and maintainability:
- 8-hour token lifetime (vs days/infinite for PATs)
- No user account dependency (survives personnel changes)
- Zero manual rotation (tokens generated fresh each run)
- Scales to N plugins without additional credentials

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Add workflow_dispatch trigger for testing historical PRs

- Add manual trigger with pr_number input
- Add Get PR Metadata step to fetch data via API (works for both triggers)
- Update all PR references to use the new metadata outputs
- Enables testing against historical PRs like #1737

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Address PR review feedback: robustness improvements

Fixes from Claude Code review:

1. Add merge validation for workflow_dispatch (Major)
   - Prevents analyzing unmerged PRs via manual trigger
   - Validates PR is merged before proceeding

2. Use unique HEREDOC delimiters (Major)
   - Prevents collision if PR body/comments contain "EOF"
   - Uses unique suffixes like __BODY_DELIM_7f3a9b2c__

3. Pin claude-code-action to SHA (Major)
   - Aligns with claude-code-review.yml for consistency
   - Tracks issue #892 for AJV validation bug

4. Add concurrency control (Minor)
   - Prevents race conditions on concurrent runs
   - Groups by PR number, doesn't cancel in-progress

5. Add shell error handling (Minor)
   - set -eo pipefail in all shell blocks
   - Fail fast on command errors

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Add debug artifact upload for troubleshooting

Uploads execution logs when workflow fails, matching pattern
from claude-code-review.yml. 7-day retention.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

…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>

…#898) (inkeep#3268)

* Introduce check:fast tier for in-vivo agent verification (G1)

Closes G1 from the merge-gates audit (inkeep#892): "No check:fast script tier
— Layer 1 (in-vivo) is undocumented for agents."

Adds `check:fast` as the canonical fast-verification command name across
root + 6 subtrees. Aliased to each subtree's existing `typecheck` (the
fastest reliable signal of real errors). Agents doing in-vivo iteration
inside a subtree can now run `pnpm check:fast` (or `bun run check:fast`
in OK) regardless of subtree — same command name, subtree-appropriate
implementation.

Scope:
- Root `check:fast` fans out to all 6 subtrees with typecheck coverage
  (matches existing `typecheck` root fan-out shape)
- Per-subtree `check:fast` script added; each aliases the subtree's
  existing typecheck command verbatim (no behavior change, just a
  named alias for discoverability)
- subtrees: public/agents, public/open-knowledge, private/agents-ui,
  private/chat-to-edit, private/copilot-app, private/copilot-chrome-extension

Why typecheck and not something broader:
- typecheck catches the most common in-vivo error (type mismatches,
  missing imports, broken refactors) with cache hits in <10s warm
- No tests: tests are slow and not in-vivo-fast
- No lint: lint is fast but typecheck already covers most real bugs
- No format:check: pre-commit's lint-staged covers that

This is naming, not new behavior. If we later want check:fast to mean
something different (e.g., typecheck + lint), the alias changes in one
place per subtree. The name is the durable contract; the implementation
is a script value.

Local verification: `pnpm --dir public/agents check:fast` runs `turbo
typecheck` correctly, 5.2s with 14/16 cached. (One pre-existing
typecheck error in agents-manage-ui — react-google-recaptcha-v3 types
missing — surfaced; that's on main, unrelated to this PR.)

Follow-up: update .github/QUALITY_GATES.md Layer 1 to reference
`check:fast` once inkeep#892 lands (QUALITY_GATES.md doesn't exist on this
branch yet — it's introduced by inkeep#892).

* Address PR inkeep#898 review: fold check:fast → typecheck alias (eliminates drift risk)

pullfrog[bot] flagged that the previous shape duplicated each subtree's
typecheck command verbatim under a `check:fast` key — 6 independent
string literals had to stay in lockstep with the matching `typecheck`
strings. A future PR changing a subtree's `typecheck` (e.g. adding a
`--filter` exclusion) could silently forget the `check:fast` twin and
the two would diverge.

Fix: each subtree's `check:fast` now invokes `pnpm typecheck` (or
`bun run typecheck` for OK) — a literal alias of the existing typecheck
script in the same package.json. The typecheck script stays canonical;
check:fast is its discoverable name. Single source of truth per subtree,
zero drift surface.

Per-subtree:
- public/agents: `check:fast: pnpm typecheck` (delegates to existing
  `typecheck: turbo typecheck --filter='!agents-cookbook-templates'`)
- public/open-knowledge: `check:fast: bun run typecheck` (delegates to
  existing `typecheck: turbo run typecheck`)
- private/agents-ui: `check:fast: pnpm typecheck`
- private/chat-to-edit: `check:fast: pnpm typecheck`
- private/copilot-app: `check:fast: pnpm typecheck`
- private/copilot-chrome-extension: `check:fast: pnpm typecheck`

Local verification (alias chain runs end-to-end):
- `pnpm --dir public/agents check:fast` → invokes typecheck → 16/16 turbo
  tasks success, 14/16 cached, 1m3s cold
- `pnpm --dir private/agents-ui check:fast` → recursive typecheck across
  packages/agents-ui, packages/react, packages/docusaurus — all green

(pullfrog's second finding about other AGENTS.md docs still referencing
`pnpm typecheck`: addressed in PR body reply — keeping deferred since the
alias means existing docs aren't wrong, just don't surface the new name.)

GitOrigin-RevId: 86ed0df4b6e7d9fa68bd67adb0df85661f61e055

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

…nkeep#1083) (inkeep#3290)

* [US-001] add check:fast script to public/agents/package.json

Add check:fast script to public/agents/package.json mirroring the
existing typecheck invocation (turbo typecheck --filter=!agents-cookbook-templates).

Every other subtree already defines check:fast as its typecheck alias
(agents-ui, chat-to-edit, copilot-app, copilot-chrome-extension via
pnpm typecheck, open-knowledge via bun run typecheck). public/agents
was the gap. Filling it lets the root fan-out (pnpm check:fast) and
the upcoming pre-push typecheck shift (US-003) treat every subtree
uniformly via the same script name.

Mirror-safe: script key only, no new files, no impact on
copybara/manifests/public-agents.json includes.

* [US-002] Prefer origin/main in resolveBaseRef, add --mode=delta escape hatch

Pre-push's scope was per-push delta: after a feature branch's first push,
@{upstream} pointed at the remote ref containing everything pushed, so
subsequent pushes only re-checked files in new commits. A regression in
commit A that wasn't caught at A's push was invisible to commit B's push
and surfaced 10 minutes later in CI.

Flip the default to cumulative-vs-origin/main on feature branches so every
push re-checks the full branch diff (matching what CI actually validates).
Pushes from main or master still prefer @{upstream} because diffing main
against origin/main would be diffing the branch against itself. Add
--mode=delta as an explicit opt-in for the old behavior (escape hatch for
force-pushed branches where origin/main may not have a clean merge base).

The pre-existing fallback chain (@{upstream} -> origin/main ->
unique-commit-parent -> null) is preserved verbatim. Only the preferred
ref on feature-branch cumulative pushes changes.

* [US-003] Wire check:fast typecheck into per-subtree pre-push runner

Run each affected subtree's check:fast (typecheck alias) between
format:check and the public/agents structural checks, so the inkeep#1 CI
failure class gets caught at push time rather than after a 10-minute
CI round-trip.

Subtrees that don't declare check:fast in package.json
(private/inkeep-cloud-mcp, private/support-copilot-agents) skip the
step with a warning. --no-typecheck bypasses the step entirely for
emergency pushes. Typecheck failures surface remediation pointing to
the per-subtree typecheck verb (pnpm --dir X typecheck or cd X &&
bun run typecheck) instead of the check:fast alias.

* [US-004] Add non-blocking conflict-with-main detection to pre-push

Adds a 5th pre-push step that warns when the current branch will
conflict with origin/main on merge. Non-blocking: pushing a WIP branch
known-to-conflict (to share with a collaborator) is legitimate.

Two helpers:
- run_warn_step: sibling to run_step with identical TTY rendering and
  log-offset tail, but never exits the hook. Shows pass on clean exit,
  warn-glyph on non-zero with the captured output tailed to terminal.
- detect_conflict_with_main: gates on git >= 2.38, fetches origin main
  (silent skip on network failure), runs merge-tree --write-tree
  --name-only, extracts the conflicting paths from the output.

Deviations from SPEC AC text (rationalized in code comments):
- Dropped --depth=1 from git fetch. Verified on git 2.50 that depth=1
  retroactively shallows the local origin/main, which then makes
  merge-tree fail with 'refusing to merge unrelated histories' on every
  subsequent push.
- Introduced run_warn_step as a sibling helper rather than reusing
  run_step. The latter exits on non-zero, which would block the push
  on conflict-detected, violating the non-blocking AC.

* [US-005] Surface AGENTS.md size pressure in pre-push output

Add a non-blocking inline warning to .husky/pre-push that prints the
current byte count for AGENTS.md and public/open-knowledge/AGENTS.md
when either is at or above 37,000 bytes. The threshold is 1,500 below
the 38,500-byte FOUNDATIONAL INVARIANT enforced by test:scripts, which
gives roughly 3-5 push cycles of warning before the cliff. Silent below
37,000, silent on missing files, never blocking.

Implemented as a plain shell helper rather than via run_warn_step so
the step line is suppressed below threshold (matching the AC: "no
output below threshold; keep pre-push focused"). The warning format
mirrors the spec template verbatim: a single line per file showing
size and the 38500/40000 reference points.

Smoke-tested boundary conditions (missing, 36999, 37000, 38280, 39630,
empty) plus live repo state (root 38471, OK 39677 -> both warn).

* [US-006] Add check:boundaries step to pre-push hook

Insert pnpm check:boundaries as the 3rd pre-push step, between
claude-hook-sync and test:scripts. Boundary violations (public/
importing from private/) now fail at pre-push instead of waiting
for CI's Private PR Validation 3-4 minutes later.

Sub-second cost on warm state. Uses the existing run_step helper
so blocking behavior, output discipline, and log-tail-on-fail come
for free.

* [US-007] Unit tests for parseArgs, SUBTREES, subtreeHasScript

Add scripts/check-pre-push-mode.test.mjs (16 tests) pinning the new
flag surface (--mode={delta,cumulative}, --no-typecheck) and the
typecheck wiring (SUBTREES.typecheckScript defaulted to check:fast,
subtreeHasScript skip-with-warning path).

Wrap main() in the standard ESM main-guard so the module is
importable from tests without re-running. Pattern matches
scripts/check-monorepo-traps.mjs.

resolveBaseRef itself is not unit-tested here. It uses module-level
REPO_ROOT for every git call, so a unit test would require either
parameterizing the cwd or spawning fixture worktrees. Rationale is
documented in the test file's header.

* [US-008] Document new pre-push behavior + ship audit artifacts

Update AGENTS.md "Pre-push verification" section to enumerate the
five blocking steps plus the two non-blocking environmental warns
(conflict-with-main, AGENTS.md size pressure). Add a Scope
paragraph covering the cumulative-vs-delta default and the
--mode=delta escape hatch. Add a Flags line for --no-typecheck,
--all, --base=<ref>, and --no-verify.

Tightened the section overall to absorb the new content within
the FOUNDATIONAL INVARIANT 38,500 byte cap. Final size 38,487
bytes (13 under).

Update .github/QUALITY_GATES.md Layer 3 row to reflect the new
step structure and reference typecheck shift, scope flags, and
escape hatches. Update the decision-tree bullet 3 to include
typecheck regression, boundary violations, and merge conflicts
as Layer 3 candidates, and to call out run_warn_step as the
helper for non-blocking environmental observations.

Ship the backing audit artifacts in the same PR (matches the
2026-05-13 merge-gates-audit precedent in PR inkeep#892):
- reports/pre-commit-prepush-ci-latency-and-autofix-audit/
- reports/CATALOGUE.md (regenerated)
- specs/2026-05-19-pre-push-shift-left/SPEC.md

* docs: refresh CI.md + CI_ARCHITECTURE.md pre-push hook rows

Both files described the pre-push hook as 'pnpm check:monorepo-traps
then pnpm format' — pre-dated the audit landed in PR inkeep#892 and never
caught up. This refresh aligns them with the current 5 blocking
steps plus 2 non-blocking warns, mentions the cumulative scope flip,
and points at QUALITY_GATES.md Layer 3 for the canonical reference.

Pure docs change. AGENTS.md cap unchanged (38,487 bytes).

* fix: align pnpm verify with pre-push hook + detached-HEAD comment

Address pullfrog review findings on PR inkeep#1083.

(1) pnpm verify was missing check:boundaries — AGENTS.md correctly
    claimed 'all five blocking steps' but the alias only ran four.
    Add check:boundaries between claude-hook-sync and test:scripts
    to match the husky hook's actual sequence.

(2) Add a maintenance comment in resolveBaseRef explaining that
    git rev-parse --abbrev-ref HEAD returns the literal string
    'HEAD' in detached-HEAD state, which falls through cleanly to
    the cumulative path. The existing fall-through is the intended
    behavior — future maintainers shouldn't add a currentBranch
    === 'HEAD' special case.

* review: address inkeep#1083 findings (4 small fixes + 1 new test)

Address claude[bot] PR review on PR inkeep#1083. All Minor/Consider/While-
You're-Here findings; nothing blocking.

1. QUALITY_GATES.md Layer 4 listed 'typecheck' as the first example,
   contradicting the Layer 3 typecheck shift this PR documents three
   lines above. Layer 4 now says 'full cross-subtree typecheck' to
   distinguish the layer-3-scoped invocation from the full-tree one.

2. QUALITY_GATES.md Layer 1 'no documented general-purpose check:fast
   yet at root' was factually wrong (root package.json has one). Update
   the row to describe what's there.

3. public/agents check:fast now delegates via 'pnpm typecheck' instead
   of duplicating the full turbo invocation. Matches the convention of
   every other subtree's check:fast and keeps a single source of truth
   for the filter; behavior is identical since pnpm typecheck IS the
   turbo invocation.

4. Warn on unrecognized --mode= values in check-pre-push.mjs. A typo
   like '--mode=cumuliative' would previously fall through silently to
   the cumulative default; now prints a one-line warning so the
   developer notices the typo.

5. Add a structural invariant test pinning pathPrefix === name + '/'
   and dir === name for every SUBTREES entry. A copy-paste typo here
   would silently disable change detection for the subtree.

6. Compress AGENTS.md 'Content-hash skip' paragraph and reference
   check-monorepo-traps.mjs for the full input list. Reclaims a small
   amount of headroom under the 38,500-byte FOUNDATIONAL INVARIANT cap
   (38,487 -> 38,460). Reviewer flagged ~13 bytes of headroom as
   uncomfortably tight; this is directional rather than a 200-500-byte
   compaction.

* review: pin runner field + --mode=<unknown> preserve-state behavior

Address claude[bot] re-review on PR inkeep#1083. Both 'Consider' findings,
test coverage extensions following patterns established earlier.

1. Add a runner-field invariant test pinning public/open-knowledge as
   the only 'bun' runner and rejecting 'bun' on any other entry. A
   copy-paste error swapping the runner field on the OK entry would
   either fail confusingly (pnpm can't resolve bun-only deps) or
   silently succeed without exercising the right toolchain.

2. Pin the --mode=<unknown> 'preserve prior state' behavior. The
   typo-warning branch added in 559894c61 intentionally keeps the
   current args.mode value when an unrecognized mode is encountered
   (so --mode=delta --mode=typo preserves delta). The behavior is
   correct but subtle and was unpinned; a future refactor that resets
   to default on unknown values would silently regress this edge case.

GitOrigin-RevId: 0d4e113f3224a2cdcb62311693ef54bd96877c14

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