fix(hook-base-ref): I-phase — pre-push base-ref via git stdin (F1-F4, ADAPT pre-commit precedent)

[artyhoo]

Summary

I-phase implementing the hook-base-ref-detection R-phase (PR #287 research patch). The pre-push hook guessed a static origin/staging base, which silently no-op'd on any consumer repo without a staging branch (install.sh ships the bash fallback, which had the same default) and mis-scoped prod-promotion pushes to main. The fix reads the base git already hands the hook on stdin (<local_ref> <local_sha> <remote_ref> <remote_sha>) — eliminating the guess entirely.

Verdict: ADAPT pre-commit's stdin-parsing primitive (SSOT #85). Read base for dev; env-override for CI.

What changed (F1–F4)

Finding	Fix	Where
core	parsePushRefs() + Z40 + commitsNotOnRemotes() (pure, unit-tested)	packages/core/hooks/utils/git.ts:44,64,89
core	resolveBase() — precedence env > stdin remote_sha (Z40 → commits-not-on-remotes) > origin/staging default	packages/core/hooks/pre-push.ts:95
F1	stranded origin/main...HEAD (3-dot) §6 guard → routed through resolver, reconciled to 2-dot	packages/core/hooks/pre-push.ts:386-405
F2	TS silent-skip → visible warning in every base-scoped section (§6/§7/§1.7/§8)	packages/core/hooks/pre-push.ts:123 (warnSkip)
F3	verified: .husky/pre-push uses exec, git forwards pre-push stdin natively; no husky npm dep	—
F4	SSOT #85 (pre-commit precedent, ADAPT, T16 match analysis + falsifier)	docs/meta-factory/prior-art-evaluations.md:153
consumer	pre-push.fallback.sh (the channel install.sh ships) gets the same resolver	packages/core/hooks/pre-push.fallback.sh:28

Reserved fork resolved to Option A (stdin). The R-phase left "incremental vs full-PR dev-side scope" to the maintainer. Resolved to A: Option B reintroduces the trunk-guess the finding's root cause (#own-stack-blind-spot) condemns; stdin is a strict improvement given the per-commit trailer invariant + CI's full-PR backstop. B is documented as the SSOT #85 falsifier — a reversal callable later, not a live toss-up.

Verification

• git unit 68/68 (6 new commitsNotOnRemotes, 9 new parsePushRefs/Z40)
• prepush-upstream-ref.test.sh 8/8 (5 new stdin scenarios), prepush-fallback-base-ref.test.sh 5/5 (new) — RED-first paired-negatives (4/5/7/8 + FB1/FB2 confirmed failing pre-fix)
• principles 153/153, typecheck clean, actionlint + zizmor clean, render drift clean, audit-ai-docs 191/191
• pushed through the live pre-push hook — the new resolver's Z40 path ran on this branch's own first push and passed
• adversarial cold-review run; 1 MAJOR + 1 MINOR + 1 NIT, all applied

§1.7 Forward-check applied

The change complies with every active discipline layer:

• no-paid-llm-in-ci.md: resolver is pure git, zero API — packages/core/hooks/pre-push.ts:95 (resolveBase uses only upstreamExists/commitsNotOnRemotes) and packages/core/hooks/pre-push.fallback.sh:28 (resolve_commits, pure git rev-parse/rev-list).
• build-first-reuse-default.md: ADAPT (not BUILD) of a mature precedent — SSOT row docs/meta-factory/prior-art-evaluations.md:153 (docs(audit): refresh AUDIT-CHECKLIST/AUDIT-PROMPT post-C-1 + packages/ layout #85, verdict ADAPT, pre-commit), with explicit T16 problem-class match (~60%) + falsifier.
• dual-implementation-discipline.md §5: both channels resolve the base identically — packages/core/hooks/pre-push.fallback.sh:24 mirrors packages/core/hooks/pre-push.ts:95 precedence (env > stdin > default), proven by parallel paired-negative suites.
• doc-authority-hierarchy.md: SSOT append-only respected — docs/meta-factory/prior-art-evaluations.md:153 (docs(audit): refresh AUDIT-CHECKLIST/AUDIT-PROMPT post-C-1 + packages/ layout #85 appended after docs(skills): sync shipped prose to C-1 resolution (close DN-1) #84, ID-ordered).

§1.7 Backward-check applied

Complete sweep of every base-resolving surface the R-phase enumerated — all four reconciled, none silently superseded:

• packages/core/hooks/pre-push.ts:95 — upstreamRef() (old static default) → resolveBase().
• packages/core/hooks/pre-push.fallback.sh:28 — old UPSTREAM_REF=…:-origin/staging → resolve_commits().
• packages/core/hooks/pre-push.ts:386-405 — F1 stranded origin/main...HEAD 3-dot guard → resolver-routed 2-dot.
• .github/workflows/audit-self.yml:312,316 — CI PREPUSH_UPSTREAM_REF: origin/${{ github.base_ref }} preserved unchanged.

Explicit non-supersession / out-of-scope notes:

• R-phase PR research(hook-base-ref-detection): R-phase — pre-push base-ref via git stdin (ADAPT pre-commit precedent) #287 is NOT superseded — this PR is the implementation of its verdict (the research patch remains the authoritative design record).
• Pre-existing failing test pre-push.test.ts > invokes the remaining audit-self self-tests by literal path — NOT touched. It asserts stale .test.sh literals left by the Wave 10.4 .ts migration; fails identically on pristine origin/staging; not in the CI gate (test:principles = principles/ only). Separate stale-assertion fix per CLAUDE.md PR strategy → Observation 1.
• install.sh ship-list NOT touched — the fix lands in both pre-push.fallback.sh (shipped) and pre-push.ts, so the consumer fallback now resolves the base from stdin and no longer silently no-ops. Shipping pre-push.ts to consumers for the substance arms is a separate enhancement → Observation 2.
• CI loud-fail preserved, not regressed — audit-self.yml:307 still fails loudly when the PR base is unresolvable; the new dev-side warnSkip fires only when neither stdin nor env resolves (CI always supplies env, so it never reaches that path).

Observations (surfaced, not acted on — PR-scope discipline)

1. Pre-existing pre-push.test.ts stale .test.sh assertion (above) — separate fix.
2. install.sh ships only the fallback, not pre-push.ts — bug is closed (fallback now works), but full TS substance arms for consumers = separate enhancement umbrella.

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

Что починили: pre-push-хук раньше угадывал, с какой веткой сравнивать пуш — жёстко origin/staging. На любом чужом репозитории без ветки staging проверка молча ничего не делала (а консьюмерам устанавливается именно bash-fallback с тем же дефолтом). Теперь хук читает базу, которую git сам передаёт ему на stdin при каждом пуше — работает на любом репозитории с любым именем транка, гадать больше не нужно. Новая ветка (Z40) → проверяются «коммиты, которых ещё нет ни на одном remote».

Чем CI остался прежним: CI как и раньше передаёт PREPUSH_UPSTREAM_REF=origin/<base_ref> и громко падает, если база не резолвится (audit-self.yml:307) — полный PR-scope. Изменился только dev-side: вместо тихого пропуска теперь либо stdin-база, либо видимое предупреждение. Приоритет: env (CI) > stdin (dev) > старый дефолт. Backstop в CI не тронут.

---

Base: staging. Closes the hook-base-ref-detection I-phase.