docs(ci): stop hard-coding hook self-test deps in a comment

[claude]

Fixes #14141

What

.github/workflows/lint.yml's Claude hook guard self-tests step discovers its
matrices by glob (find .claude/hooks -type f -name '*.selftest.sh' | sort), but
the comment above the step hard-coded a fixed dependency claim for the whole step.
That combination is a drift channel: a new matrix can need more than the original
two did without touching this comment, and one already does
(guard-governed-enqueue.selftest.sh needs node for real — see #14141 for the
full writeup). check:step-collectors cannot see this block (the comment already
admits as much a few lines up), so nothing catches the prose falling out of date.

This is option A from the triage (comment
#14141 (comment)):
rewrite the dependency sentence to describe only what the step itself needs, and
push the "what else" onto each matrix's own header — prose-for-prose, no new
machine channel. Options B/C (a preflight that parses matrix headers, deferred by
the triage) are out of scope here; .claude/hooks/** is untouched.

Before:

Needs jq and git and nothing else — no pnpm, no node, no build, no network
(jq is in the runner image and is already relied on bare by cut-rc.yml and
release.yml). ~2 s measured.

After:

This step itself needs only jq and git (both in the runner image; jq is
already relied on bare by cut-rc.yml and release.yml), plus whatever each
discovered matrix declares in its own header — discovery above is by glob, so a
matrix needing more (node, pnpm, a built tree, a generator) must say so there;
this comment is not the place to enumerate it.

The stale ~2 s measured figure is dropped along with it. No other line moves:
step name:, run: script, the find discovery, and the rest of the "Hermetic
by construction" paragraph (per-matrix throwaway git repos; re-run from a primary
checkout / detached HEAD / non-repo cwd) are untouched, and the
⚠️ check:step-collectors CANNOT see this block admission stays as-is.

Selftest census (why this matters right now)

All five matrices currently discovered under .claude/hooks/*.selftest.sh, and
whether each calls anything beyond jq/git/bash for real (not counting
node/pnpm strings that appear only inside simulated Bash-command fixtures fed
to the guard under test):

matrix	own header says	real extra deps
guard-governed-enqueue.selftest.sh	"Needs jq … and node"	node (both predicates run for real; one case runs a generator --check when deps are installed)
guard-main-checkout-bash.selftest.sh	"Needs jq and git and nothing else"	none
guard-main-checkout.selftest.sh	"Needs jq and git and nothing else"	none
guard-shared-stash.selftest.sh	"Needs jq … and nothing"	none
guard-tree-enum.selftest.sh	"Needs jq … and nothing else"	none

Only one matrix has drifted past jq+git so far, and it already documents its own
extra dependency in its own header — which is exactly the shape the rewritten
step comment now describes instead of enumerating. No second drift instance was
found, so route B (a preflight parsing matrix headers) stays deferred per the
triage.

Testing

• find .claude/hooks -type f -name '*.selftest.sh' | sort — the step's own
  discovery command, run locally: discovers the same 5 files listed above.
• The step's run: block executed locally, byte-for-byte (bash + jq + git + node
  are all present on this machine): all 5 matrices PASS, exit 0.
• Gate union derived via node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands .github/workflows/lint.yml on the current
  head (commit 7987b5b2e, origin/main merged in twice as it advanced) — 23
  families, 22 RAN-PASS, 1 NOT-MEASURED (check:type-check-debt, exit 3
  PREREQUISITE NOT MET — needs the full workspace dependency closure built
  first; this is a comment-only YAML change with no bearing on type-check debt).
  pnpm check:pm-dispatch-gates (1240 self-test cases) also RAN-PASS. Full list
  in the issue comment report.
• No changeset: this PR touches only a YAML comment under .github/**, no
  package or user-visible behaviour changes — skip-changeset label applied and
  confirmed by reading the PR's labels back.

Session: https://claude.ai/code/session_01WLJQhde67SeTccsmnBVarV

---

Generated by Claude Code

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 33623834019 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Test Core (1/6) — 失败步骤: Run this shard's tests

  @objectstack/cli:test:  FAIL   unit  test/vitest-tiers-partition.test.ts > the two tiers of packages/cli (#13504) > INTEGRATION_FILES equals the behavioural predicate over every file on disk
    ↳ 失败原因: @objectstack/cli:test: AssertionError: files that spawn the CLI or boot a kernel/driver but are NOT in INTEGRATION_FILES (add them): expected [ Array(1) ] to deeply equal []
  

↳ 失败原因 是判读的关键：超时（Test timed out in … / Hook timed out in …）多半是负载/时序，不是本 PR 的回归；
断言（AssertionError: …）才指向真实的行为改变。两者的 FAIL 行长得一模一样，只有这一行能区分。

⚠️ 断言这一侧有一类例外，判据是断言在测什么，不是它是不是 AssertionError。 断言的对象是产品行为（一个值、一个形状、一次拒收）⇒ 照上面读：真实的行为改变，去查，⛔ 不要重排掉；
断言的对象是这次实验自身的有效性前提（跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件）⇒ 它跟超时是同一类，同样对负载敏感，重排一次是合法的判别手段。
识别是机械的：断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为（真回归）；
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提：它守护的那条不变式当时是绿的，同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量，仍然是时间测量。（⛔ 这只改「怎么读一次红」，不改「哪些测试可以重排」——后者由别处管。）

跨 PR 相同签名（24h，按失败测试文件聚合）：

• test/vitest-tiers-partition.test.ts — 24h 内已弹出 3 个 PR（test(cli): split the suite into named unit and integration vitest tiers #14536、docs(ci): stop hard-coding hook self-test deps in a comment #14538、docs(spec,approvals): ApprovalEscalation.timeoutHours names its clock — calendar (wall-clock) hours #14542），但它们同属 1 条投机栈 ⇒ 1 次独立命中。汇总 issue：Queue-flake anchor: test/vitest-tiers-partition.test.ts #14554（已刷新）
• ⚠️ 24h 评论账本没读完（超过 5 页仍未读到窗口尽头），所以上面的「不同 PR 数」是下界，不是全量。

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 3 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」；已有汇总 issue ⇒ flaky/环境问题实锤，去那张 issue 上谈，修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)