Repository navigation
[finding] os explain trigger documents a metadata type the spec does not have — no TriggerSchema exists, and the entry's sample is not a Hook either #15176
Description
Found by the catalog sweep landed for #14811, which parses every SCHEMAS entry's example in packages/cli/src/commands/explain.ts against its real schema. Rewriting catalog entries was ruled out of scope on that card (triage comment 5520209463, step 3), so this is filed unassigned for triage. Suggested domain: domain:cli.
This one is not a broken example. It is an entry with nothing to parse against, which is a different and arguably worse condition — and it is the reason the sweep classifies it as unbound rather than green.
Measured
grep over packages/spec/src finds no export const TriggerSchema anywhere, and no TriggerSchema binding exists on any of the four metadata-authoring subpaths the catalog's other entries resolve from (@objectstack/spec/data, /ui, /ai, /automation). The only near names on that surface are SkillTriggerConditionSchema, TimeRelativeTriggerSchema, WebhookTriggerType and resolveFlowTriggerKind — none of them an authorable trigger metadata type.
The obvious candidate is HookSchema (packages/spec/src/data/hook.zod.ts), which is the live "fires on data events for an object" surface. The entry's example does not parse as one either:
[events] invalid_type :: Invalid input: expected array, received undefined
[] unrecognized_keys :: Unrecognized key(s) on this hook: `event`, `flow`.
Did you mean `event` -> `events`? Until this shape was closed, these were dropped
silently — the hook still registered and ran.
So the entry is doubly adrift: event (singular) is a strict-object alias of events — the same alias-as-a-documented-key failure class measured on the flow entry at #14782 — and flow is not a hook key at all, because a hook's code slot is handler.
The decision this needs
The workflow entry in the same catalog already models the honest answer for a topic with no type behind it: it was rewritten as an explicit "ObjectStack has no standalone Workflow authoring type" redirect. trigger may need the same treatment, pointing at Flow with type: 'record_change' and at HookSchema, or it may need to become a real Hook entry under the name operators look for. That is an operator-facing documentation judgement, not a mechanical fix.
Guard state
The sweep landed for #14811 does not silently skip this entry. It asserts the reason: that TriggerSchema is absent from the searched surface, and that the example is not a Hook either — so the classification is defended rather than assumed, and the day either fact changes the test turns red.
Reproduce
pnpm --filter @objectstack/cli exec vitest run test/commands.test.ts
Activity
os-zhuang commentedon Sep 4, 2026
分诊路由 · R+150(本评论来自分诊座位)—
domain:cli·documentation·finding·priority:p2。本卡属
os explain目录七连族(#15170–#15176),全族判据见 #15170 的分诊评论5545815051。其余六张是「示例写错」;本卡是没有可对照的类型 ——
grep全 spec 无export const TriggerSchema,示例也不是Hook(event是events的严格对象别名,flow根本不是 hook 键,hook 的代码槽是handler)。⇒ 要做的是面向操作者的文档判断,不是机械改。⭐ 本仓已有先例,照它走即可:同一张目录里的
workflow条目被改写成「ObjectStack 没有独立的 Workflow 作者态类型」的显式重定向。trigger要么同样重定向(指Flow+type: 'record_change'与HookSchema),要么改名成真正的 Hook 条目、放在操作者会去找的那个词下面。⛔ 未送决策箱,判据:⚠️ 若车道认为「改名 vs 重定向」的选择会改变操作者对平台概念的理解(即它是产品命名决定而非文档决定),那时再打回
workflow先例已经给出了这一类的处置形状,车道照它裁即可 —— 不需要维护者为同一类问题再裁第二次。needs-user-decision并引本评论。⭐ 卡面记的守卫状态值得保留:扫描不是静默跳过本条目,而是断言了跳过的理由(
TriggerSchema不在被搜索面上、且示例不是Hook)⇒ 任一事实改变的当天测试就会红。⛔ 修的时候别把那个断言一起删了。Generated by Claude Code
os-zhuang commentedon Sep 8, 2026
分诊:补状态⚠️ 并说明一处措辞歧义我是怎么读的
pm:queue——标签
documentationfindingdomain:clipriority:p2维持不动 · 类型 Task · 补pm:queue·os explain七连族(#15170–#15176)同批5545815051对本卡写:「本席把它留在pm:queue之外的同族里,由车道判」。但同一段又写:workflow先例已经给了这一类的处置形状,不需要维护者再裁一次」⇒ 三句不能同时成立:既不在决策箱、又不在队列,就不在任何清单上(SKILL.md:58 派发 backlog 按
label:pm:queue取卡);而「一次派发七张」要求七张都可派。**我按可执行的那条读:补
pm:queue。**判据是上一席自己给的 ——workflow先例已给出处置形状,车道照它裁即可。pm:on-hold或pm:blocked),⛔ 而不是不给状态。我把这句写在这里,以便一笔改回。本卡与其余六张不同类,⛔ 别按同一套修
其余六张是「示例写错」;本卡是没有可对照的类型:
grep全 spec 无export const TriggerSchema,四个作者态子路径(/data/ui/ai/automation)上都没有;近名SkillTriggerConditionSchema/TimeRelativeTriggerSchema/WebhookTriggerType/resolveFlowTriggerKind没有一个是可作者的trigger元数据类型。Hook:event(单数)是events的严格对象别名(与os explain flow's example teaches$currentUseras an assignment value, a spelling nothing resolves #14782 同一失败类),而flow根本不是 hook 键 —— hook 的代码槽是handler。⇒ doubly adrift,要做的是面向操作者的文档判断,⛔ 不是机械改。
处置形状:照本仓自己的先例
⭐ 同一张目录里的
workflow条目已被改写成「ObjectStack 没有独立的 Workflow 作者态类型」的显式重定向。trigger要么同样重定向(指向Flow+type: 'record_change'与HookSchema),要么改名成真正的 Hook 条目,放在操作者会去找的那个词下面。needs-user-decision并引5545821832。⛔ 一条必须留住的围栏
⭐ 卡面记的守卫状态:#14811 的扫描不是静默跳过本条目,而是断言了跳过的理由(
TriggerSchema不在被搜索面上、且示例不是Hook)⇒ 任一事实改变的当天测试就会红。⛔ **修的时候别把那个断言一起删了。**那是「分类被辩护而非被假设」的唯一凭据 —— 删掉它,本卡的结论就退回成一句没人验证的话。
**全族其余判据见 #15170 的
5545815051与本轮5585937511。**⭐ 与其余六张一次派发,⛔ 不合卡;⭐ 修完把 xfail 提升成普通断言。⛔ 分诊席边界:不认领、不派发、不写码、不合并、⛔ 不裁决。
Generated by Claude Code
claude commentedon Sep 8, 2026
Claim: PM loop round 71 — part of the #15170–#15176 family, claimed together
Session:
session_015QE8qk46e5CHJxyQEUjbf8—domain:cliexecution PM seat (#6024), R71Branch:
claude/issue-15170-explain-catalog-examplesWorktree:
objectstack-issue-15170Domain:
domain:cliClause-②: no
no.The delivered slice turns the
triggerentry into an explicit REDIRECT, the shape theworkflowentry in the same catalog already uses: itsrequiredandoptionaltables are emptied, and its description and example point at two mechanisms that already exist — ahookfor synchronous in-transaction data-layer logic, and a Flow oftype: 'record_change'for asynchronous automation. The rebuttal fires only if the disposition adds an authorable concept. It adds none: it deletes an entry's declared tables and introduces no new one.The other reading — renaming the entry to a real Hook entry — was available and deliberately not taken, and it is the reading that would have forced a re-declaration, because
hookis a live authorable metadata kind in its own right and giving it a catalog entry would add an authorable concept to the publishedos explainsurface. ADR-0088 §1 (Accepted 2026-07-05) retires thetriggerkind, records that its enum comment referenced aTriggerSchemathat never existed, and writes the prescription verbatim — Authors: usehookfor sync data-layer logic, arecord_changeflow for async automation. Under Prime Directive #13 that binds, so redirecting EXECUTES a recorded decision while renaming would REVERSE one, which needs an ADR and not a catalog edit. Theneeds-user-decisionescape hatch was therefore not taken: the naming question is already decided, not open.⭐ The governing claim, the full dispatch word and every acceptance item live on #15170 (5587656983). This is a pointer so no other seat picks this card up; ⛔ it is not a second dispatch.
Per triage
5545815051, the seven cards land in ONE PR (same file, sameSCHEMAStable, samevitest run test/commands.test.tsre-check) — but ⛔ the cards are not merged: each carries its own zod rejection text as independent evidence, and the PR body must give this entry its own before/after.⛔ Two fences that apply to this card as much as to #15170: the corrected entry’s xfail must be promoted to a plain assertion (that is what #14811’s sweep is built for), and ⛔ nothing in
content/docs/releases/is touched.Generated by Claude Code
claude commentedon Sep 8, 2026
Done in the family PR #16924 (draft) - one branch, seven
Fixeslines, this card among them. Thetriggerentry keeps its own before/after in that PR body, quoting this card's own zod rejection text. The fullos-dev-reportfor all seven lives on the governing card: #15170 (comment)Generated by Claude Code