Merge remote-tracking branch 'origin/main' into claude/issue-16464-shard-timings-refresh-workflow

Author: claude

.claude/agents/os-dev.md

@@ -126,8 +126,8 @@ model: opus
 - ① 先 build 依赖闭包:`pnpm --filter '<pkg>^...' build` 是新 worktree 的第一条命令。
 - 跳过它产出的失败,读起来与你的改动弄坏了 import 一模一样。
 - ② 受影响包自己的 `pnpm test` / `pnpm typecheck`,用 `--filter` 圈定。
-- 受影响包 = CI 会测的包,清单读 `TURBO_SCM_BASE="$BASE" pnpm exec turbo ls --affected`。
-- ⛔ 不按改了哪些包猜:普通 import 被改模块的包也在清单里,欠它们的测试。
+- 受影响包 = 本包;import 方只在公开面变化时欠测试:spec 契约、发布的 `exports`、线上形状。
+- 公开面字节不变 ⇒ 只欠本包测试与派生门禁,⛔ 不给每个 import 方补测试。
 - `packages/cli` 只欠 `unit` 层(见 Definition of done 的测试条)。
 - ③ 派发词点名的门禁族,加上你看得出被牵连的。
 - 新 fake engine ⇒ `check:engine-double-contract`;新错误码 ⇒ `check:error-code-casing`。
@@ -207,11 +207,10 @@ model: opus
 - 它必须答 exit 0;否则阴性作废,`git fetch --deepen` / `--unshallow` 到控制腿转 0 再重读。
 - ⛔ 控制腿别挑浅窗内的近亲:控制 commit 至少与被测那个同深;两条腿的退出码都进报告。
 - `--is-shallow-repository` 是便宜的触发器不是判据,判据是控制腿。
-- 反向验证(回退修复,看诊断变化)先 commit 修复:恢复只是 `git checkout <your-branch> -- <path>`。
-- 对着未提交的编辑,`git checkout origin/main -- <path>` 不留任何恢复点。
+- 反向验证与消融是一次性证明:前后运行引在 PR 正文与报告里;⛔ 不留永久测试文件。
+- 两者都先 commit 修复再回退或变异:恢复腿指向 `HEAD`,`HEAD` 必须先装着你的实现。
+- 未提交时 `git checkout origin/main -- <path>` 不留恢复点,`git checkout HEAD -- <path>` 删的正是实现。
 - 恢复机制与字节一致性证明规则见 AGENTS.md;从已 commit 的状态重跑,红/绿数字才可信。
-- 消融同一条,先 commit 再变异:恢复腿指向 `HEAD`,`HEAD` 必须先装着你的实现。
-- 对未提交的实现,一次完美的 `git checkout HEAD -- <path>` 删的正是实现本身,事后检查全绿。
 - 通则:失效形态是 exit 0 且什么都没做的清理步骤,只能靠观察状态验证,永不靠读退出码。
 - 恢复腿与变异腿完全对称,四条硬线如下。
 - ① 恢复写 `git checkout HEAD -- <path>`,⛔ 永不裸 `git checkout -- <path>`:裸恢复从索引取。
@@ -225,6 +224,7 @@ model: opus
 - 拒收类用例断言信封,不断言 throw 本身;最小断言集是错误的 `code` 与 `status`(ADR-0112 信封)。
 - 单独的 `expect(...).toThrow()` 不是拒收测试:抛裸 `Error` 的未修复 driver 照样绿。
 - 从不抛错的传输层转红时,它指向缺陷之外。
+- 提示、裁决与错误文案 ⛔ 不 pin,除非消费者解析其原文;断言种类、退出码或具名主体。
 - 措辞本身即契约的地方,在 `code`+`status` 之上再断言 message 首句,永不取而代之。
 - 键与值的可达性判据:守某个键是真实编写面 → 断言 fixture 上无 `unrecognized_keys`。
 - 守某个值的判定 → 要求完整 `safeParse` 绿;拒键与拒值是两个不同的事实。

.claude/skills/pm-dispatch/references/platform-readings.md

@@ -71,6 +71,10 @@
 - 同一 PR 第二次被踢 ⇒ 停止重投,按签名四分支重判。
 - 吞吐两则:合并队列落地 ≈ 每 PR 15–30 分钟且串行,⛔ 不据还没落提前判异常。
 - 单容器重验证(build 加 test)并发甜点 ≈3,排批按它定上限。
+- 入队事件与队列 ref 迟 1–3 分钟才出现 ⇒ 轮询预算按 3 分钟,⛔ 不按 1 分钟判没挂上。
+- ready 翻转触发检查重跑 ⇒ 入队落在翻转之后约一分钟,那段空窗不是挂载失败。
+- `behind` 的 PR 照常入队:落后于 main 不是入队否决,⛔ 不为它先跑 update-branch。
+- `check_suite.completed` 会命名过期 head,check-run 也只属最后一次 push ⇒ 用前先重读当前 head。
 
 ## API 配额
 
@@ -212,6 +216,8 @@
 - `list_issue_types` 对本集成 403 而 `issue_write type:` 正常,是读权限缺口。
 - ⇒ 直接写已知好值(`Bug`/`Feature`/`Task`),写侧报错才是真信号;列表 403 不等于类型不可用。
 - 非法值是响错还是静默丢弃未实测,写非已知值前先小样验证。
+- ⛔ 控制词不取卡片逐字标题:逐字标题回 0,同题自然语言回 14 条含该卡,零仍不是读数。
+- MCP `get_comments` 结果超 ~100 KB 溢出成文件:返回体是路径不是评论,读前先判形。
 
 ## 读数陷阱
 
@@ -330,6 +336,21 @@
 - 计数答至今发生过没有,不答机制在不在:零计数只作弱先验。
 - 判 required 集为空要读 ruleset 的 required 集本身,或看队列合并是否真在等检查。
 - ⛔ 别处写下的计数值一律先复测再用。
+- MCP `issue_write create` 落库丢掉正文尾部的署名页脚块,正文其余部分完好。
+- 同一路径吃掉标题里的尖括号跨度 ⇒ 标题占位写裸词(NAME / :id),⛔ 不写尖括号形。
+- 建卡改走 REST `POST /issues` 页脚存活;回读后 `PATCH /issues/{n}` 重送正文逐字节存下。
+- CI job 的失败 step 不必与 job 名一致 ⇒ ⛔ 不由 job 名推原因,先读 step 名再下结论。
+- Actions 日志保留把老 job 截到 post-job cleanup ⇒ 归档只剩清理输出时原因不可断言。
+- 无 `packageManager` 的目录里 corepack 运行时解析 registry `latest` ⇒ 同 SHA 前绿后红是 tag 移了。
+- 自测写出的 fixture `package.json` 必带根清单的 `packageManager`,否则 CI 里解析到 latest。
+- `COREPACK_DEFAULT_TO_LATEST=0` 单用修不了已记 12.x 的 store ⇒ 环境变量不是补救。
+- corepack 下载 pnpm 可在检查体开跑前崩 undici(`assert(!this.paused)`)⇒ 是基础设施红。
+- 落地探针除命名代码形外,还必须在落地前的 tip 上读出不同值,否则它分不开两棵树。
+- `check-governed-merges` 浅克隆上拒答而非少报,并报未审计仓数;补救 `git fetch --shallow-since=`。
+- 前台 `sleep` 被 harness 拒 ⇒ 等待写成带 until 条件的前台阻塞等待,⛔ 不写 sleep 轮询循环。
+- 分支删除被拒有第二形态:代理回 403,与既有 send-pack 断连同处置 ⇒ 不可删,⛔ 不重试。
+- `merge-tree` 套不套 `.gitattributes` 驱动随本克隆注册与否变,驱动 exit 0 只说驱动收下了。
+- ⇒ 驱动管辖的路径上冲突证明跑两遍,第二遍带 `-c merge.os-regen.driver=false` 关掉驱动。
 
 ## 闭合关键词解析(PR 正文写侧)
 
@@ -342,6 +363,7 @@
 - PR body 与 squash commit message 是两个独立解析源:commit 干净不等于 body 干净,只查 commit 会漏。
 - 误关的卡以 `completed` 状态对一切只看 open 的过滤与巡检隐身,无机械守卫覆盖这条路径。
 - 消费侧检查 = 合并后读 `closed_by_pull_requests`,在复核清单里。
+- 被 `Fixes` PR 自动关闭的卡保留 `pm:*` 标签;`Refs` PR 不关卡 ⇒ 状态转移归席位不归平台。
 
 ## 断粮检测与跨墙恢复(5 小时用量墙)
 
@@ -360,3 +382,7 @@
 - 更新端带 `model`,但只有每次起新会话的 Routine 吃得到。
 - 自绑的保持所绑会话的档位直到绑定解除 ⇒ ⛔ 不据更新端能改档推自绑的档位可改。
 - UI 建的 Routine agent 改不动:更新端只受理自己建的。
+- 用量墙杀死席位与全部在飞子代理而 worktree 存活;`SendMessage` 幂等重启文本可整批复活。
+- 定时器只在轮次之间投递:可迟到数分钟,也可在轮内被吃掉而无通知 ⇒ 醒来先重读状态。
+- 撞墙期间到点的定时器在重置后按序补投 ⇒ ⛔ 不为它们重建 Routine。
+- 墙杀后别席可能在共享分支留下抢救 WIP 提交:未过门禁的分支尖不是复核输入。

.github/workflows/ci.yml

@@ -371,15 +371,17 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      # PRs: only test packages affected by the diff against the PR base.
-      # spec sits at the root of the dependency graph, so spec-touching PRs
-      # still run (close to) everything — but the many PRs that don't touch
-      # spec skip the bulk of the 75-package matrix. Push to main and
-      # merge-queue builds partition the FULL package list instead: the queue
-      # result IS the next main, so it gets main's validation, not the PR's
-      # affected-only subset. (Spec's suite runs here plain / uninstrumented;
-      # the coverage-instrumented pass lives in the nightly coverage-nightly
-      # workflow.)
+      # PRs and merge-queue builds: only test packages affected by the diff —
+      # against the PR base on pull_request, against the group's own
+      # `base_sha` on merge_group (#16453). spec sits at the root of the
+      # dependency graph, so spec-touching diffs still run (close to)
+      # everything — but the many that don't touch spec skip the bulk of the
+      # 75-package matrix, and at ~120 queue merges a day that is the bulk of
+      # the queue's test compute. Push to main partitions the FULL package
+      # list: it gates nobody, and its full run is the ground truth the
+      # shard-timings refresh reads. (Spec's suite runs here plain /
+      # uninstrumented; the coverage-instrumented pass lives in the nightly
+      # coverage-nightly workflow.)
       #
       # !@objectstack/dogfood: the ~7½-minute dogfood suite is the dedicated
       # Dogfood job's whole purpose, and both jobs run under the same `core`
@@ -436,127 +438,26 @@ jobs:
       #     `turbo ls`'s internal choice of dot-ness — undocumented, and
       #     `turbo ls` is experimental (see above). Resolving to a commit here
       #     leaves turbo no choice to make.
+      # The selection itself lives in scripts/ci/select-shard-packages.sh:
+      # environment in, `$RUNNER_TEMP/turbo-ls.json` out. This step only
+      # exports the event's fields, so the same script -- every branch of
+      # it -- runs locally and under its self-test (#16453). Per event:
+      #   pull_request  affected set against merge-base(origin/<base>, HEAD)
+      #   merge_group   affected set against the group's `base_sha`, unioned
+      #                 with the same cross-package scans. An EMPTY set is a
+      #                 legitimate docs-only group: it reaches the "No packages
+      #                 on this shard" exit below, every shard still attests,
+      #                 and Test Core is an honest green. It is NOT the #10057
+      #                 case, which is pull_request-only (the script says why).
+      #   push          unchanged: the FULL list.
       - name: Compute this shard's package set
         env:
-          BASE_REF: ${{ github.event.pull_request.base.ref }}
-          PINNED_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          OS_SHARD_EVENT_NAME: ${{ github.event_name }}
+          OS_SHARD_PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
+          OS_SHARD_PR_PINNED_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          OS_SHARD_MERGE_GROUP_BASE_SHA: ${{ github.event.merge_group.base_sha }}
         run: |
-          SCM_BASE=''
-          if [ "${{ github.event_name }}" = "pull_request" ]; then
-            if [ -z "$BASE_REF" ]; then
-              echo "::warning::This pull_request event carries no base branch, so the affected-set diff base cannot be computed."
-            else
-              # `fetch-depth: 0` above already makes this resolve — the fetch is
-              # the guard for the day that changes, not the normal path.
-              #
-              # `git cat-file -e` rather than the more idiomatic strict
-              # `git rev-parse --verify` spelling. That is history rather than
-              # style, and it is written down because it used to be a live
-              # hazard: the pre-#6589 check-shard-attestation.mjs classified a
-              # job as an aggregate GATE when the script's basename and its
-              # `--verify` flag merely CO-OCCURRED as substrings anywhere in
-              # the job's joined `run:` text. This job always carries the
-              # basename (its `--emit` step at the bottom), so spelling
-              # `--verify` anywhere in this step — comments included, since
-              # they were part of `run:` — silently reclassified the shard job
-              # as a gate.
-              #
-              # #6589 closed that by construction. Classification is now by
-              # INVOCATION: within one command the flag must follow the
-              # script's own name as an argument, the test is applied per STEP
-              # and never over the job's joined text, and the lexer drops shell
-              # comments — all three pinned by that script's `--self-test`,
-              # which is why this comment can now name the flag at all. Either
-              # spelling is safe here; `git cat-file -e` stays because
-              # churning it would buy nothing.
-              if ! git cat-file -e "refs/remotes/origin/$BASE_REF^{commit}" 2>/dev/null; then
-                git fetch --no-tags --quiet origin "+refs/heads/$BASE_REF:refs/remotes/origin/$BASE_REF" \
-                  || echo "::warning::Could not fetch origin/$BASE_REF; the merge-base resolution below will decide."
-              fi
-              # `if !` rather than a bare assignment on purpose: these steps run
-              # under `bash -e`, where a failing command substitution kills the
-              # step with no message at all.
-              if ! SCM_BASE=$(git merge-base "refs/remotes/origin/$BASE_REF" HEAD); then
-                SCM_BASE=''
-              fi
-            fi
-          fi
-          if [ -n "$SCM_BASE" ]; then
-            # The drift is printed, not just corrected: nothing in this log ever
-            # said which commit the affected diff started from, which is why the
-            # decay was invisible.
-            DRIFT=$(git rev-list --count "$PINNED_BASE_SHA..$SCM_BASE" 2>/dev/null || echo '?')
-            echo "Affected-set diff base: $SCM_BASE  (merge-base of origin/$BASE_REF and HEAD)"
-            echo "Frozen payload base.sha: $PINNED_BASE_SHA  -- $BASE_REF has moved $DRIFT commit(s) since it was frozen, and that drift is exactly what this step used to charge to this PR."
-            TURBO_SCM_BASE="$SCM_BASE" pnpm exec turbo ls --affected --output=json > "$RUNNER_TEMP/turbo-ls.json"
-            # `turbo ls --affected` answers "which packages does the dependency
-            # GRAPH reach from this diff" — and some suites read files the graph
-            # does not connect them to. spec's api-methods-batch-conformance scan
-            # walks every `*.object.ts` in the monorepo while spec declares no
-            # dependency on the packages it judges (nor should it: the scan reads
-            # source text precisely to avoid inverting the spec -> * direction).
-            # A platform-objects-only diff therefore left it unrun, and #7769
-            # landed a violation on `main` that only PRs touching `spec` ever saw.
-            # Measured on turbo 2.10.7: 51 packages affected by that diff, spec
-            # not among them.
-            #
-            # So packages that declare a cross-package input radius are unioned
-            # back in when the diff touches it. The declarations, and the static
-            # detector that refuses to let a new cross-package scan go
-            # undeclared, live in the script (`pnpm check:cross-package-test-inputs`).
-            #
-            # Failure here falls back to the FULL package list, never to the
-            # affected-only set: same posture as the merge-base fallback below
-            # (#6195), and the same reason — the full list is a strict superset,
-            # so doubt costs minutes rather than coverage. This is the FILTER
-            # CONTRACT's half 1 applied one layer down.
-            if ! git diff --name-only "$SCM_BASE" HEAD > "$RUNNER_TEMP/changed-files.txt" \
-              || ! node scripts/check-cross-package-test-inputs.mjs \
-                   --union-into "$RUNNER_TEMP/turbo-ls.json" \
-                   --changed "$RUNNER_TEMP/changed-files.txt"; then
-              echo "::warning::Could not union cross-package scans into the affected set; falling back to the full package list for this shard."
-              pnpm exec turbo ls --output=json > "$RUNNER_TEMP/turbo-ls.json"
-            # A fourth signal the failure branches do not cover: a producer that
-            # exits 0 with a wrong, plausible, EMPTY answer. Only that `git
-            # diff`'s exit STATUS was checked, never its emptiness, so a
-            # merge-base resolving to something wrong-but-valid gave an empty
-            # changed-file list -> zero affected packages -> a green shard that
-            # tested nothing, with every log line reading like a normal quiet PR
-            # (#10057). The shard attestation (#6082) does not cover it: it
-            # attests "shard N ran and every step passed", which is exactly what
-            # a shard that tested nothing does.
-            #
-            # Empty is decidable as BROKEN here, and only here: a pull_request
-            # always differs from its merge-base. At the partitioner zero is
-            # frequently the CORRECT answer (a docs-only PR genuinely affects no
-            # package, and with 6 shards a small change legitimately leaves
-            # shards empty), so a blanket "red on empty" belongs there least of
-            # all -- this is the one place selection-failed and nothing-selected
-            # can be told apart.
-            #
-            # Scoping this to pull_request needs no `github.event_name` test:
-            # SCM_BASE is assigned only inside the `pull_request` guard above, so
-            # this whole `[ -n "$SCM_BASE" ]` branch is unreachable on push and
-            # merge_group. Those keep taking the full-list path in the `else`
-            # below, by design.
-            elif [ ! -s "$RUNNER_TEMP/changed-files.txt" ]; then
-              echo "::warning::The diff against merge-base $SCM_BASE listed no changed files, which a pull_request cannot legitimately produce; falling back to the full package list for this shard rather than selecting nothing (#10057)."
-              pnpm exec turbo ls --output=json > "$RUNNER_TEMP/turbo-ls.json"
-            fi
-          else
-            # Falling back to the FULL package list, never to the frozen
-            # base.sha. This is not the #4690 silent-skip anti-pattern: that is
-            # about a gate PASSING on input it could not read, and the full list
-            # is a strict superset of the affected one — this shard still runs
-            # everything it would have run and more. Cost is minutes; the
-            # alternative is a red Test Core on a PR with nothing wrong with it.
-            # Push and merge-queue builds take this branch by design (the queue
-            # result IS the next main, so it gets main's validation).
-            if [ "${{ github.event_name }}" = "pull_request" ]; then
-              echo "::warning::Could not resolve merge-base(origin/$BASE_REF, HEAD); falling back to the full package list for this shard rather than diffing from the frozen base.sha (#6195)."
-            fi
-            pnpm exec turbo ls --output=json > "$RUNNER_TEMP/turbo-ls.json"
-          fi
+          bash scripts/ci/select-shard-packages.sh
           node scripts/partition-test-shards.mjs "$RUNNER_TEMP/turbo-ls.json" \
             --shard ${{ matrix.shard }}/6 --exclude @objectstack/dogfood \
             > "$RUNNER_TEMP/shard-packages.txt"