Skip to content

docs(skills): teach that a notify with no link opens the run's trigger record - #30682

Merged
os-zhuang merged 1 commit into
mainfrom
claude/project-thread-9lz4tb
Nov 6, 2026
Merged

docs(skills): teach that a notify with no link opens the run's trigger record#30682
os-zhuang merged 1 commit into
mainfrom
claude/project-thread-9lz4tb

Conversation

@objectstack-fleet

@objectstack-fleet objectstack-fleet Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Requested by Elon · project thread

Fixes #30254

Clause-②: no
Metadata-protocol: none

维护者速读

  • 改了什么:自动化技能的 notify 示例、flows 文档的 notify 段落、一条新 eval,改教「不写链接时,通知点开就是触发这次运行的那条记录」。
  • 为什么改:PR feat(service-automation): a record-triggered flow's notification links to the record that started the run when it names no link #30252 已让运行时这样做,技能和文档还在教旧规则「不写成对的 sourceObject/sourceId 就没有链接」,AI 会白写一对多余的键。
  • 风险与回滚:只改教学文字和 eval,不改任何代码或 schema;回滚即整体 revert 本 PR。
  • 先看:skills/objectstack-automation/SKILL.md 的 notify 示例三行(L124–126),其次 content/docs/automation/flows.mdx 约 L351 的段落。
  • 两分钟验证:node scripts/check-skills-token-ratchet.mjs,应看到 objectstack-automation/SKILL.md 为 6447 tokens(上限 6449)。
  • 需要你做的:受管面(skills/**,Tier H),请审阅后批准或合并。

What changes

The runtime default that PR #30252 landed, read off origin/main b77c160a (packages/services/service-automation/src/builtin/notify-node.ts, defaultClickThroughOf and the sourceObject / sourceId / actionUrl config-schema descriptions): a notify node that writes none of sourceObject, sourceId and actionUrl links to the run's trigger record when the run has one (a record change other than a delete, a time-relative sweep's row, an action started on a record). An explicit pair or actionUrl wins; a half-written pair is dropped, never defaulted; a run with no trigger record links nowhere.

  • skills/objectstack-automation/SKILL.md: the notify example's link comments now state the default and its three exceptions (link: PAIR, else dropped; none of the 3 ⇒ the trigger record (not on delete), if any; actionUrl overrides the pair). The old // click-through: a PAIR, else dropped is gone.
  • content/docs/automation/flows.mdx: the notify sourceId paragraph states the default, its three cases, and the three exceptions, with the no-trigger-record examples the code comment names (a schedule tick, an inbound API post, a manual start with no record).
  • skills/objectstack-automation/evals/flows-triggers-approvals.json: eval 14, a record-triggered notify that should open its case. It expects no sourceObject: / actionUrl: written and the words trigger record (taught in SKILL.md).
  • .changeset/30254-notify-default-link-skill.md: '@objectstack/skills': patch.

Token readings (skills/**)

Reading Before (b77c160a) After (HEAD)
skills/objectstack-automation/SKILL.md lines 452 452
same file, ratchet tokens (stamp line excluded) 6449 (ceiling 6449, headroom 0) 6447 (headroom 2)
all skills/*/SKILL.md lines 4534 4534
all skills/*/SKILL.md bytes 226877 226867

The new notify comment costs 13 bytes net inside the example (it also drops the (a value slot) and text slot; asides, which Valid-but-silently-wrong item 1 teaches for sourceId and actionUrl). It is paid inside the same file by deleting a duplicated aside from the Flow Types api row, or a literal secret;: the Inbound webhook config table still teaches secretRef / secret. No ceiling moved.

Tests

Teaching text and an eval only; no code changed, so no unit suite and no ablation apply. The gate readings are under Verification.

Acceptance notes

  • Card item 3 is not in this PR (spec lane, out of this file surface). On origin/main b77c160a, packages/spec/src/automation/io-node-config.zod.ts still carries the old rule: the sourceObject (L750) and sourceId (L756) .describe() texts say only that a half pair is dropped, and the actionUrl text says only that it overrides the synthesized link. None of the three mentions the trigger-record default. The generated content/docs/references/automation/io-node-config.mdx (L106, L107, L109) repeats them. The seat carries this to domain:spec.
  • The SKILL.md ceiling is left at 6449 (headroom 2): lowering it is a scripts/ edit outside this file surface.

Verification

All readings at head d9415882, after turbo run build of @objectstack/spec, @objectstack/lint..., @objectstack/client-react... and @objectstack/formula (BUILD :: exit 0).

  • node scripts/pm/dispatch-gates.mjs --ran FILE --repo objectstack-ai/objectstack: 68 derived families accounted for, 67 run, 1 NOT MEASURED, 0 unrun.
  • NOT MEASURED: pnpm check:dual-build-cjs-loads, reason: exit 3, PREREQUISITE NOT MET (it needs a whole-tree build; CI runs it).
  • pnpm lint :: exit 0.
  • check-skills-token-ratchet: 57 authored bundle file(s) within their ceilings; skills/objectstack-automation/SKILL.md is 6447 tokens (ceiling 6449; headroom 2).
  • check:skill-examples: 283 prose examples type-check across 3 surface(s).
  • check:dts-closure is green over the 41 built packages only; CI sweeps the whole tree.
Every local family and its exit code 
node scripts/check-adr-0087-registration.mjs --base origin/main :: exit 0
node scripts/check-adr-0087-registration.mjs --self-test :: exit 0
node scripts/check-adr-links.mjs :: exit 0
node scripts/check-adr-links.mjs --self-test :: exit 0
node scripts/check-changeset-no-major.mjs --base origin/main :: exit 0
node scripts/check-closing-keyword-parity.mjs :: exit 0
node scripts/check-closing-keyword-parity.mjs --self-test :: exit 0
node scripts/check-comment-mask-corpus.mjs :: exit 0
node scripts/check-doc-route-spelling.mjs --advisory :: exit 0
node scripts/check-doc-route-spelling.mjs --self-test :: exit 0
node scripts/check-docs-section-name.mjs :: exit 0
node scripts/check-docs-section-name.mjs --self-test :: exit 0
node scripts/check-dts-emitted.mjs --self-test :: exit 0
node scripts/check-empty-changeset.mjs --base origin/main :: exit 0
node scripts/check-empty-changeset.mjs --self-test :: exit 0
node scripts/check-section-landing-index.mjs :: exit 0
node scripts/check-section-landing-index.mjs --self-test :: exit 0
node scripts/check-skills-token-ratchet.mjs :: exit 0
node scripts/check-skills-token-ratchet.mjs --self-test :: exit 0
node scripts/ci/assert-turbo-remote-cache.mjs --self-test :: exit 0
node scripts/ci/plan-test-core-shards.mjs --self-test :: exit 0
node scripts/ci/prune-turbo-cache.mjs --self-test :: exit 0
node scripts/pm/release-rehearsal-clone.mjs --self-test :: exit 0
node scripts/release-pending-publish.mjs --self-test :: exit 0
pnpm --filter @objectstack/lint run check:doc-formula-expressions :: exit 0
pnpm --filter @objectstack/lint run check:doc-security-posture :: exit 0
pnpm --filter @objectstack/spec run check:docs :: exit 0
pnpm --filter @objectstack/spec run check:empty-state :: exit 0
pnpm --filter @objectstack/spec run check:liveness :: exit 0
pnpm --filter @objectstack/spec run check:skill-docs :: exit 0
pnpm --filter @objectstack/spec run check:skill-examples :: exit 0
pnpm --filter @objectstack/spec run check:strictness-ledger :: exit 0
pnpm --filter @objectstack/spec run check:variant-docs :: exit 0
pnpm --filter @objectstack/spec run check:yaml-examples :: exit 0
pnpm check:agent-test-spelling :: exit 0
pnpm check:changeset-gate-self-tests :: exit 0
pnpm check:ci-filter-parity :: exit 0
pnpm check:closed-ceremony-text :: exit 0
pnpm check:corpus-claim-drift :: exit 0
pnpm check:cross-package-test-inputs :: exit 0
pnpm check:doc-anchors :: exit 0
pnpm check:doc-authoring :: exit 0
pnpm check:doc-frontmatter :: exit 0
pnpm check:docs-audit-scope :: exit 0
pnpm check:docs-redirects :: exit 0
pnpm check:docs-single-h1 :: exit 0
pnpm check:docs-spec-enumerations :: exit 0
pnpm check:docs-transcript-drift :: exit 0
pnpm check:driver-memory-census :: exit 0
pnpm check:dts-closure :: exit 0
pnpm check:dual-build-cjs-loads :: exit 3
pnpm check:gitlink-declared :: exit 0
pnpm check:lean-entry-closure :: exit 0
pnpm check:merge-driver :: exit 0
pnpm check:nul-bytes :: exit 0
pnpm check:pm-governed-merges :: exit 0
pnpm check:pm-skill-id-lint :: exit 0
pnpm check:published-files :: exit 0
pnpm check:published-readme-links :: exit 0
pnpm check:react-page-adapter-contract :: exit 0
pnpm check:refd-timer-probe :: exit 0
pnpm check:role-word :: exit 0
pnpm check:skill-compatibility :: exit 0
pnpm check:skill-frame-sync :: exit 0
pnpm check:skill-identifier-liveness :: exit 0
pnpm check:sourcemap-no-sources-content :: exit 0
pnpm check:vendor-version-stamps :: exit 0
pnpm check:watch-hint-literal :: exit 0
pnpm lint :: exit 0

Generated by Claude Code

@claude
docs(skills): teach that a notify with no link opens the run's trigge…
d941588 
…r record

The automation skill's notify example still said a click-through needs a
PAIR or is dropped. The runtime now links a node that writes none of
sourceObject, sourceId and actionUrl to the run's trigger record when it has
one (not a delete); an explicit pair or actionUrl wins, a half pair is
dropped, and a run with no trigger record links nowhere. The skill example,
the flows guide's notify paragraph and a new eval now say so. The SKILL.md
growth is paid by dropping a duplicated literal-secret aside from the Flow
Types table (the webhook config table still teaches it).

Co-authored-by: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016WV4cyou7XDWHnizyxR5MQ
@github-actions github-actions Bot added size/s documentation Improvements or additions to documentation tooling Fix lands in tooling, not a product package — enters pm:queue only with Unblocks: or a named surface labels Nov 5, 2026
@objectstack-fleet

objectstack-fleet Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor Author

domain:skills#1 · os-elon-musk · session_016WV4d1mkgEris4MHHLjtnk

Contract-review-claim: session_016WV4d1mkgEris4MHHLjtnk · head d941588 · 2026-11-05T22:21Z

@objectstack-fleet

objectstack-fleet Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor Author

domain:skills#1 · os-elon-musk · session_016WV4d1mkgEris4MHHLjtnk

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: d9415882a049c1b92868bd05f84c624f42a42210
Local-runs: none
Scope: skills/objectstack-automation/SKILL.md, skills/objectstack-automation/evals/flows-triggers-approvals.json (hits) + cited packages/services/service-automation/src/builtin/notify-node.ts, notify-node.test.ts, packages/triggers/trigger-api/src/api-trigger.ts, packages/spec/src/automation/io-node-config.zod.ts (read for the out-of-scope finding), content/docs/automation/flows.mdx, .changeset/30254-notify-default-link-skill.md (all on origin/main b77c160)

① Derived judgments

  • Accept set / public surface: none. Four files (changeset, flows.mdx, SKILL.md, one eval); no packages/**, schema, export or gate. Clause-②: no is right.
  • Metadata-protocol: none re-derived: the default landed in PR feat(service-automation): a record-triggered flow's notification links to the record that started the run when it names no link #30252 (semantic there); this PR changes no behaviour. No Skills-docs: line owed.
  • SKILL.md L124-126 states the runtime exactly: notify-node.ts:185 (no default when any of sourceObject/sourceId/actionUrl is set), :186 with :162 (delete excluded), :187 (trigger record), :1022-1024 (pair only when both halves resolve), :1004-1007 and :1157 (actionUrl wins). Pinned by notify-node.test.ts:20-81.
  • flows.mdx L352-358: the three trigger-record cases match notify-node.ts:174-176; the no-trigger-record examples hold, including the API case (api-trigger.ts:406-412 sets record with no object, so triggerRecordOf at notify-node.ts:155-159 answers nothing).

② Semver level

'@objectstack/skills': patch matches Metadata-protocol: none. Declaration lines are line-initial in the changeset and PR body; no skip-changeset. Check Changeset: success.

③ Boundary flags

  • PR author objectstack-fleet[bot]. open_questions: none.
  • Deviation "ceiling left at 6449, headroom 2": accepted; lowering it is outside the file surface.
  • out_of_scope_findings (card item 3) verified on origin/main: io-node-config.zod.ts:750 (sourceObject), :756 (sourceId) and :765-766 (actionUrl) do not state the trigger-record default that notify-node.ts:885/:889/:902 state. Still stale, owed to domain:spec: the seat files it before ACCEPT.
  • Token ratchet re-derived: SKILL.md 6449 → 6447 against ceiling 6449. Deleted text has another home (literal secret at head L356; sourceId value slot at L222-225; actionUrl text slot at L239-240). No rule dropped.
  • Check-runs at read time: 0 failure, 15 still in progress. All-green is the landing-time check.

④ Design judgment

  • skills/objectstack-automation/SKILL.md (L48, L124-126): holds against notify-node.ts on main and the card's scenario (a record-triggered notify with no link opens the trigger record); names the default, the half-pair drop, the actionUrl override, the delete exclusion and "if any". Sweep-row and action-on-record cases live in flows.mdx L352-355 (2 tokens of headroom).
  • evals/flows-triggers-approvals.json (eval 14, L246-262): same shape as evals 1-13, sequential id; must_not_contain sourceObject: / actionUrl: and must_contain trigger record assert the taught default; the expected output names the three exceptions.
  • content/docs/automation/flows.mdx (prose face): holds, see ①.
  • must-fix: none. should-fix: none.

Implemented-by: claude/project-thread-9lz4tb
Reviewed-by: session_016WV4d1mkgEris4MHHLjtnk

VERDICT: PASS

@objectstack-fleet objectstack-fleet Bot mentioned this pull request Nov 5, 2026
Closed
@objectstack-fleet

objectstack-fleet Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor Author

domain:skills#1 · os-elon-musk · session_016WV4d1mkgEris4MHHLjtnk

维护者速读

席位核对 — ACCEPT · head d941588

@objectstack-fleet objectstack-fleet Bot added the pm:awaiting-merge PR only: landing waits on the maintainer's own review and merge (SKILL.md 复核 ②); never on an issue label Nov 5, 2026
This was referenced Nov 5, 2026
Closed
Merged
Open
@os-zhuang
os-zhuang marked this pull request as ready for review November 6, 2026 00:58
@os-zhuang
os-zhuang added this pull request to the merge queue Nov 6, 2026
Merged via the queue into main with commit 83fc231 Nov 6, 2026
50 checks passed
@os-zhuang
os-zhuang deleted the claude/project-thread-9lz4tb branch November 6, 2026 01:19
@objectstack-fleet objectstack-fleet Bot mentioned this pull request Nov 6, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@hotlong hotlong Awaiting requested review from hotlong hotlong is a code owner
@os-zhuang os-zhuang Awaiting requested review from os-zhuang os-zhuang is a code owner

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation pm:awaiting-merge PR only: landing waits on the maintainer's own review and merge (SKILL.md 复核 ②); never on an issue size/s tooling Fix lands in tooling, not a product package — enters pm:queue only with Unblocks: or a named surface

Projects

None yet

Milestone

No milestone

2 participants

@os-zhuang @claude