research(hook-base-ref-detection): R-phase — pre-push base-ref via git stdin (ADAPT pre-commit precedent)

[artyhoo]

Summary

R-phase research-patch on pre-push hook base-ref detection. Worker started on worktree-setup.sh:73 (CC WorktreeCreate hook origin/HEAD staleness, 4 observed hits) but pivoted on discovering a larger asymmetry in the pre-push enforcement substrate. Pivot accepted as valid discovery; original ask remains open as separate queued umbrella (worktree-create-dual-channel per memory project_worktree_create_dual_channel_decision).

Main finding: install.sh:483 ships pre-push.fallback.sh (not pre-push.ts) to consumers; fallback defaults to origin/staging. Consumers with main/master trunk → git rev-parse --verify fails → exit 0. The §1.7 + §7 enforcement substrate the project sells is silently dead by default for any consumer without a staging branch.

Verdict (ADAPT, falsifiable): Read git pre-push stdin as base-ref on dev/consumer side (pre-commit framework precedent — DeepWiki 2026-05-29). Keep PREPUSH_UPSTREAM_REF as CI override per existing PREPUSH_ONLY seam (audit-self.yml:291-313 already correct).

Maintainer verdict 2026-05-29 on the scope fork (incremental-vs-full-PR): incremental-push-on-dev / full-PR-range-on-CI. Matches existing CI backstop architecture (PR #121 PREPUSH_ONLY seam runs over real PR range). Per-commit trailer invariant means incremental scope still checks every commit if dev stops silent-skipping → stdin alone is strict improvement.

Falsifier: wrong if husky/git pre-push doesn't actually forward stdin natively in this setup — F3 verification scheduled for I-phase.

Files

• docs/meta-factory/research-patches/2026-05-29-hook-base-ref-detection.md (NEW)

I-phase work items (NOT in this PR — T5)

• F1 — pre-push.ts:297 §6 guard hardcoded origin/main...HEAD + 3-dot vs 2-dot inconsistency reconciliation (git.ts:45,53).
• F2 — TS silent-skip on unresolvable base → loud-fail align with pre-push.fallback.sh:11 warning.
• F3 — verify .husky/pre-push native stdin forwarding (no husky npm dep present, low risk, confirm before relying).
• F4 — SSOT entry: «pre-push base-ref via git stdin (pre-commit precedent), ADAPT».

I-phase = separate session with separate kickoff per R/I separation discipline.

§1.7 Forward-check applied

Sweep across active .claude/rules/ for disciplines bearing on this research-patch:

• .claude/rules/build-first-reuse-default.md §3 — BFR 6-layer survey done: WebSearch ×3 (origin/HEAD detection, base-ref signals, lefthook), DeepWiki (pre-commit/pre-commit), SSOT consult (no existing base-ref entry). Verdict ADAPT for pre-commit stdin primitive at patch §Recommended-design.
• .claude/rules/phase-research-coverage.md §1 — 6-item search-coverage met: SSOT consult, WebSearch ≥3, DeepWiki, T16 problem-class explicit at patch §Prior-art.
• .claude/rules/phase-research-coverage.md §1.7 — this section.
• .claude/rules/phase-research-coverage.md §1.12 — recommendation discipline: verdict carries cited evidence + file:line backed claims (pre-push.ts:50-52, pre-push.fallback.sh:11, install.sh:483, audit-self.yml:291-313, pre-push.ts:297).
• .claude/rules/ai-laziness-traps.md §2 T5 — R-phase output is research-patch only, no code changes (file:line: patch §I-phase findings header «do NOT fix in this R-phase — T5»).
• .claude/rules/ai-laziness-traps.md §2 T11 — own-stack-blind-spot named explicitly at patch §Root-cause; prior-art consulted before proposing fix.
• .claude/rules/ai-laziness-traps.md §2 T16 — problem-class match analyzed at patch §Prior-art with explicit «partial match» finding (stdin-primitive transfers; scope semantics differ — maintainer fork documented).
• .claude/rules/dual-implementation-discipline.md §3 — CI vs dev/consumer asymmetry is the core finding (CI already correct at audit-self.yml:291-313; dev/consumer dead at pre-push.fallback.sh:11). Verdict preserves CI override path.
• .claude/rules/no-paid-llm-in-ci.md §1 — proposed mechanism is git-stdin parsing in dev hook, no LLM in CI.

§1.7 Backward-check applied

Sweep for artefacts that this patch must NOT silently supersede:

• docs/meta-factory/prior-art-evaluations.md — no existing base-ref entry; this patch proposes F4 new entry in I-phase, does NOT alter existing rows. SSOT consult evidence: grep verified no «pre-push» or «base-ref» entry across the register at author-time.
• .claude/rules/phase-research-coverage.md — patch operates within its discipline (cites §1 + §1.7 + §1.12), does NOT modify the rule itself.
• PR feat(ci): real-commit §1.7 + Prior-art trailer backstop (CI last-resort gate) #121 (memory project_warn_only_flip_and_ci_backstop) — CI PREPUSH_ONLY seam at real PR range PRESERVED. Verdict explicitly keeps PREPUSH_UPSTREAM_REF env override per audit-self.yml:311 (sets PREPUSH_UPSTREAM_REF=origin/<github.base_ref> via GitHub Actions env). Not superseded.
• PR feat(dispatch-worktree-automation): I-phase Sub-wave A — WorktreeCreate hook + paired-negative test (Candidate D2) #279 + PR docs(dispatch-worktree-automation): I-phase Sub-wave B — skill prose migration to claude -w + §7.6 bug #39886 backstop + template §4a removal (PR #271 §8 items 1+2+4+5) #282 (dispatch-worktree-automation I-phase) — different hook event (WorktreeCreate vs pre-push), different bug class. NOT touched, NOT superseded. Original worktree-setup.sh:73 issue queued as separate umbrella per memory project_worktree_create_dual_channel_decision.
• audit-self.yml:291-313 PREPUSH_ONLY seam — explicit cite as «correct» in patch §Problem; preserved.
• .husky/pre-push orchestration — patch does NOT propose changes to husky setup; F3 verifies stdin forwarding before I-phase relies on it.

🟢 Простыми словами

Хук pre-push проверяет трейлеры §1.7 в коммитах перед git push. Чтобы знать какие коммиты проверять, ему нужна «база» — точка от которой считать новые. Сегодня хук угадывает базу как «origin/staging», но у внешних пользователей такой ветки обычно нет → git ругается → хук тихо exit 0 → проверки не запускаются. Дисциплина, ради которой проект существует, по умолчанию мёртвая у всех внешних потребителей.

Открытие: git САМ передаёт хуку базу через stdin (стандартный pre-push протокол: <local_ref> <local_sha> <remote_ref> <remote_sha>). Не угадывать — читать. Так делает фреймворк pre-commit/pre-commit (зрелый upstream, верифицирован через DeepWiki). На dev/consumer-стороне читаем stdin, на CI-стороне оставляем переменную PREPUSH_UPSTREAM_REF которая уже работает правильно через GitHub Actions github.base_ref. Это R-phase патч — фикс будет в отдельном I-phase.

Scope-drift acknowledgment: исходный запрос был про другой хук (worktree-setup.sh:73 — для claude -w), Worker нашёл этот более важный баг при research. Принято как valid discovery; оригинальный фикс остаётся в queued umbrella worktree-create-dual-channel.