chore: run primary CI before push

2026-07-23 13:09:52 +08:00
parent 3e3ea47296
commit 00d5b69882
18 changed files with 132 additions and 37 deletions
@@ -2,7 +2,7 @@

 Status: implemented

-The hook/CI symmetry in this record is superseded by [Fast local Git hooks](2026-07-22-fast-local-git-hooks.md); CI remains the exhaustive enforcement path.
+[Local primary CI before push](2026-07-23-local-primary-ci-before-push.md) restores hook/CI symmetry for the primary Node inventory. [Fast local Git hooks](2026-07-22-fast-local-git-hooks.md) continues to own the pre-commit design.

 ## Problem

@@ -2,7 +2,7 @@

 Status: implemented

-The local-hook portion of this record is superseded by [Fast local Git hooks](2026-07-22-fast-local-git-hooks.md). The bounded gate scheduler and package-level `publint` parallelism remain in force for CI, `doc-sync`, and explicit local commands.
+[Local primary CI before push](2026-07-23-local-primary-ci-before-push.md) now owns the local-hook contract: pre-push selects the same primary inventory as CI. The bounded gate scheduler and package-level `publint` parallelism remain in force for CI, `doc-sync`, and explicit local commands.

 ## Problem

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-22-fast-local-git-hooks.md: a07af1cd424c86f7fa80ea946cd5012362cc66eb
-2026-07-22-fast-local-git-hooks.zh.md: 78d4ea8980476609a9140737a75152eba123b308
+2026-07-22-fast-local-git-hooks.md: 4a504c6c4f5816f00be6d86ddfbcb93baf0d7768
+2026-07-22-fast-local-git-hooks.zh.md: 792e035bc5761fc044cf231aff3bb59f31a47659
@@ -4,6 +4,8 @@ Status: implemented

 English | [中文](2026-07-22-fast-local-git-hooks.zh.md)

+> **Superseded for pre-push:** [Local primary CI before push](2026-07-23-local-primary-ci-before-push.md) replaces the typecheck-only publication checkpoint with the exact primary CI inventory. The fast pre-commit decision remains in force; the pre-push design below records the policy this repository no longer uses.
+
 ## Problem

 An agent already runs the tests and checks that exercise its change, while commit, push, and CI can each repeat increasingly broad subsets of the same work. A full pre-push suite therefore delays every publication, amplifies unrelated local flakes, and gives no new signal when CI immediately runs the exhaustive matrix again.
@@ -4,6 +4,8 @@ Status: implemented

 [English](2026-07-22-fast-local-git-hooks.md) | 中文

+> **pre-push 部分已被取代：**[推送前本地运行主 CI](2026-07-23-local-primary-ci-before-push.md)以精确的主 CI 清单取代仅运行类型检查的发布检查点。快速 pre-commit 的决策继续有效；下文的 pre-push 设计记录了本仓库不再采用的策略。
+
 ## 问题

 agent（智能体）已经会运行能够覆盖自身改动的测试和检查，而提交、推送与 CI 可能分别重复其中范围越来越广的子集。因此，全量 pre-push 套件会拖慢每次推送，放大与当前改动无关的本地偶发失败，而且 CI 紧接着再次运行完整矩阵时不会提供新信号。
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-23-local-primary-ci-before-push.md: 9d7f4d5a5aae428a003b1cbbb8911e7ad7c50831
+2026-07-23-local-primary-ci-before-push.zh.md: 3b58a828bd12d0149d8c4101d8665ee15b9fffc2
@@ -0,0 +1,38 @@
+# Agent Note: Local primary CI before push
+
+Status: implemented
+
+English | [中文](2026-07-23-local-primary-ci-before-push.zh.md)
+
+## Problem
+
+Hosted CI can become unavailable before repository code executes because of account, billing, quota, or runner failures. A typecheck-only publication hook then permits a remote branch update without coverage, snapshot, documentation, build, package, or built-entrypoint evidence precisely when the hosted workflow cannot supply that signal.
+
+Focused checks remain the right feedback loop during implementation, but their selection depends on the author correctly predicting every affected contract. Publication needs one complete, mechanically owned local baseline that does not depend on the hosted control plane starting a job.
+
+## Decision
+
+[lefthook.yml](../../../../lefthook.yml) keeps pre-commit focused on staged lint, whitespace, and vendored-source metadata. Pre-push invokes `pnpm run check:pre-push` and blocks publication on any failure.
+
+The `check:pre-push` package script selects the `pre-push` mode in [scripts/run-gates.ts](../../../../scripts/run-gates.ts). Both `pre-push` and `ci-primary` return the same `ciPrimaryGates()` inventory, so the hook and the primary Node CI job cannot drift through separately maintained command lists. Build consumers retain their explicit scheduler dependencies, and `DSH_GATE_CONCURRENCY` remains the resource-control seam for constrained hosts.
+
+Authors still run focused checks while iterating. They do not run the full aggregate immediately before a normal push because the hook owns that one exhaustive local execution. A hook failure is fixed or reported as a blocker; bypass requires explicit approval.
+
+This contract is equivalent to the keyless primary Node CI aggregate on the current host. It does not claim the supported-version or operating-system matrix, Python SDK, real-provider, native, or sandbox workflow signals that require their own environments.
+
+## Supersedes
+
+This decision supersedes the pre-push half of [Fast local Git hooks](2026-07-22-fast-local-git-hooks.md). Its staged pre-commit design remains in force. It also restores the local publication role described by [Parallel pre-push gates](2026-07-06-parallel-pre-push-gates.md) without reviving a second gate inventory.
+
+## Alternatives considered
+
+- **Rely on restoring hosted CI availability** — repairs the immediate administrative failure but leaves publication without a baseline during the next control-plane or runner outage.
+- **Wire pre-push to `check:all`** — reuses a broad local command, but that inventory intentionally differs from the primary CI contract and would make “CI equivalent” inaccurate.
+- **Copy the CI commands into `lefthook.yml`** — makes the hook visibly comprehensive but creates a second inventory that can drift whenever CI changes.
+- **Keep typecheck-only pre-push and require a manual command during outages** — preserves low latency but relies on every author noticing the outage and remembering an exceptional procedure before each update.
+
+## Consequences
+
+Every normal push pays the primary CI aggregate's wall time and may be blocked by a repository-wide local failure unrelated to the outgoing diff. In return, every published revision has observed coverage, snapshots, documentation, build, package, and built-entrypoint evidence from one shared inventory even when hosted jobs never start.
+
+The result is local evidence, not a substitute for unavailable remote environments. Pull requests and handoffs report hosted billing, provider, platform, and pending states separately instead of presenting a successful macOS pre-push run as a green GitHub matrix.
@@ -0,0 +1,38 @@
+# Agent Note: 推送前本地运行主 CI
+
+Status: implemented
+
+[English](2026-07-23-local-primary-ci-before-push.md) | 中文
+
+## 问题
+
+托管 CI 可能会因账户、计费、配额或运行器故障，在仓库代码开始执行之前就不可用。此时，仅运行类型检查的发布钩子会允许更新远端分支，却缺少覆盖率、快照、文档、构建、包（package）和构建后入口点的证据；恰恰这时，托管工作流无法提供这些信号。
+
+实现期间，聚焦检查仍是正确的反馈循环，但检查选择取决于作者是否正确预判每项受影响的契约。发布需要一套由机制统一维护的完整本地基线，且不依赖托管控制平面能否启动作业。
+
+## 决策
+
+[lefthook.yml](../../../../lefthook.yml) 让 pre-commit 集中处理暂存文件 lint、空白错误和 vendor 源码元数据。Pre-push 调用 `pnpm run check:pre-push`，任何检查失败都会阻止发布。
+
+`check:pre-push` 包脚本从 [scripts/run-gates.ts](../../../../scripts/run-gates.ts) 中选择 `pre-push` 模式。`pre-push` 和 `ci-primary` 都返回同一份 `ciPrimaryGates()` 清单，因此钩子与主 Node CI 作业不会因分别维护命令列表而产生漂移。构建产物消费方仍保留对调度器的显式依赖关系，`DSH_GATE_CONCURRENCY` 仍是资源受限主机的资源控制 seam。
+
+作者在迭代时仍运行聚焦检查。正常推送前不立即运行全量聚合，因为钩子负责这一次全面的本地执行。钩子失败必须修复或报告为阻塞项；绕过钩子需要明确批准。
+
+本契约等同于当前主机上的 keyless 主 Node CI 聚合。它不代表已经取得受支持版本矩阵或操作系统矩阵、Python SDK、真实模型提供方、原生构建或沙箱工作流的信号；这些信号需要各自的环境才能取得。
+
+## 取代关系
+
+本决策取代[快速本地 Git 钩子](2026-07-22-fast-local-git-hooks.md)中有关 pre-push 的部分。其中面向暂存文件的 pre-commit 设计继续有效。它还恢复了[并行 pre-push 门禁](2026-07-06-parallel-pre-push-gates.md)中描述的本地发布职责，但没有重新引入第二份门禁清单。
+
+## 考虑过的替代方案
+
+- **依靠恢复托管 CI 可用性**——可以修复当前的管理性故障，但下一次控制平面或运行器中断时，发布流程仍没有基线。
+- **将 pre-push 接入 `check:all`**——能够复用一条广泛的本地命令，但其清单有意不同于主 CI 契约，会使「等同于 CI」的表述不准确。
+- **将 CI 命令复制到 `lefthook.yml`**——能够直观展示钩子的全面性，但会创建第二份清单，并在每次 CI 变更时产生漂移。
+- **保留仅运行类型检查的 pre-push，并要求中断期间手动运行命令**——能够维持低延迟，但依赖每位作者发现中断，并在每次更新前记得执行特殊流程。
+
+## 结果
+
+每次正常推送都要承担主 CI 聚合的实际耗时，也可能被与待推送 diff 无关的全仓本地失败阻塞。相应地，即使托管作业从未启动，每个已发布版本仍有一套由共享清单实际运行得出的覆盖率、快照、文档、构建、包和构建后入口点证据。
+
+该结果只是本地证据，不能代替不可用的远端环境。PR（Pull Request）和交接会分别报告托管服务计费、提供方、平台与待处理状态，而不会把一次成功的 macOS pre-push 运行表述成 GitHub 矩阵已通过。