Repository navigation
Commit bda38ab
docs(skills): type-check more objectstack-formula examples with os:check (#31746)
<!-- claude-projects-attribution: {"github_login":"zhuangjianguo"} -->
_Requested by **Steedos** · [project
thread](https://claude.ai/code/project/chan_018ETKaNwMZCNRYD7D8Q9Ubb?thread=cmsg_018ETKaNwMZCNRYD7D8Q9Ubb9N2bXVZjKY6oCBfL3iTddq)_
Refs #31112 (slice 4 of a per-skill split: item 4, objectstack-formula;
the card stays open)
Clause-②: no
Metadata-protocol: none
## 维护者速读
- 改了什么:objectstack-formula 技能包的 SKILL.md 又有 5 段 TypeScript 示例接入了示例编译检查(9
段中由 1 段变为 6 段),涉及文本公式、除数保护、动态种子值和两段 `previous` 状态转换条件;没有发现写错的示例。
- 为什么改:AI 编写公式、条件和种子值时最先照抄这些示例;接入检查后,规范一旦改名或收紧,示例会在 CI 里立刻变红,而不是悄悄教错。
- 风险与回滚:只改发布技能包的文档文字,不动任何运行时代码;token 上限未抬高(5956 → 5973 /
5997),新增字节靠同文件删减三处重复说明支付(每处删减的规则都在同文件另有出处)。回滚即 revert 本 PR。
- 先看:`skills/objectstack-formula/SKILL.md` 的「Mandatory patterns for AI
emission」一节(5 处新标记与新增的 import 行)。
- 两分钟验证:`pnpm --filter @objectstack/spec check:skill-examples`,预期最后一行为
337 段示例全部通过类型检查。
- 需要你做的:作为受管面审批人审阅并批准本 PR(skills/** 属 Tier H)。
## What changes
`skills/objectstack-formula` had 1 of its 9 fenced `ts` blocks under
`check:skill-examples` (measured on `main` 4013e30; every block sits in
`SKILL.md`; `references/_index.md` is generator-owned and holds none;
`evals/` excluded). It now has 6. Each new mark is the os:check marker
on the line above the fence plus one import line; the seed block also
gains `const seed = ` and `;` on its existing line.
| File | marked before → after / blocks | tokens before → after /
ceiling | lines before → after |
|:--|:--|:--|:--|
| `SKILL.md` | 1 → 6 / 9 | 5956 → 5973 / 5997 | 487 → 494 |
Skills bundle reading: the sum of every published `SKILL.md` moves by +7
lines (this file only).
- §1 coalesced text formula and §2 guarded divisor: `import { F } from
'@objectstack/spec';`.
- §4 dynamic seed values: `import { cel } from '@objectstack/spec';` and
`const seed = { … };` (a bare `{ a: x, b: y }` statement is a block with
labels and does not parse).
- §5 `previous`/`record` transition and the bulk-write transition
predicate: `import { P } from '@objectstack/spec';`.
- Unmarked: the three ❌ blocks (string concatenation on nullable
operands, Salesforce-flavor strings, `new Date()` seeds). They are wrong
on purpose, and the file now says so once, under the section heading.
## Why
#31112 item 4 (ruling B of #22059): published examples are guarded by
the opt-in type check. This slice brings objectstack-formula's
self-contained examples under it.
### Example fixes
None. Every marked block compiled as written once its import was added.
### Trims that paid the marks (each cut and where its rule survives)
- Intro: "This skill is the canonical reference for AI authors emitting
formula / condition / predicate / dynamic-seed metadata." cut; the
frontmatter `description` says what the skill covers and who loads it.
- §5: "ISCHANGED-style logic does not exist as a function; use explicit
`previous` comparison." cut; survives in the Mechanical translation
table row `ISCHANGED(x)` → `previous.x != record.x` and in §5's own
"Comparing against `previous` is the only way to say 'just became'".
- §3: "For field-level conditional rules, emit the canonical field
properties: `visibleWhen`, `readonlyWhen`, and `requiredWhen`." folded
into "Never emit `conditionalRequired` (use `requiredWhen`) — …"; the
three keys survive in the Surfaces table's `Field` row and the
frontmatter `description`.
## Tests
<details><summary>check:skill-examples, before and after, and the
reverse check</summary>
- Before (`main` 4013e30): `✅ 332 prose examples type-check across 3
surface(s)`.
- After (commit b484a20; head b372dba adds only a merge of `main`
touching no `skills/**` or `packages/spec` path): `pnpm --filter
@objectstack/spec check:skill-examples` exited 0 with `✅ 337 prose
examples type-check across 3 surface(s) — every marked block parsed, so
tsc ran the SEMANTIC pass on all of them`.
- Reverse check, after the commit: planted a wrong import (`import { F,
Field }`, `SKILL.md:240`) and an unknown member on the seed's `cel`
envelope (`.bogusKey`, `SKILL.md:296`). The checker exited 1 with TS2305
and TS2339 at exactly those lines. Restored with `git checkout HEAD --`;
`git status --porcelain` was empty after.
</details>
<details><summary>Derived gate sweep (commit b484a20)</summary>
`node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derived 46 commands. 45 exited 0. `pnpm
check:dual-build-cjs-loads` exited 3 (PREREQUISITE NOT MET: needs every
package's dist; CI runs it). `dispatch-gates --ran` exited 0: 46
derived, 45 run, 1 NOT-MEASURED, 0 unrun. Re-run on the merged head
b372dba: `check-skills-token-ratchet`, `check-changeset-no-major --base
origin/main`, `check:skill-links`, `check-empty-changeset --base
origin/main`, all exit 0.
</details>
## Acceptance notes
- `check:skill-examples` is not in the derived gate list for a
`skills/**` diff, so it was run by hand.
- No ceiling was raised or lowered; the ratchet printed no lowering
instruction (headroom 24 left).
- This build ran on the default tier: `dispatch-gates --tier` mandates
Fable for `skills/**`, and the claim records the no-Fable-build exit;
the contract review is the seat's, on the lane's isolated reviewer.
## Verification
`pnpm --filter @objectstack/spec check:skill-examples` (needs
`@objectstack/spec` and `@objectstack/client-react` built) prints 337
examples green; `node scripts/check-skills-token-ratchet.mjs` exits 0.
## Human Minimum
A governed approver reviews and approves (Tier H).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01QsR2jR79xaiCrky8EZ18Up
Co-authored-by: Claude <noreply@anthropic.com>1 parent 6dfc7fa commit bda38ab
2 files changed
Lines changed: 26 additions & 9 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
22 | 22 | | |
23 | 23 | | |
24 | 24 | | |
25 | | - | |
26 | | - | |
| 25 | + | |
27 | 26 | | |
28 | 27 | | |
29 | 28 | | |
| |||
230 | 229 | | |
231 | 230 | | |
232 | 231 | | |
| 232 | + | |
| 233 | + | |
233 | 234 | | |
234 | 235 | | |
235 | 236 | | |
236 | 237 | | |
| 238 | + | |
237 | 239 | | |
| 240 | + | |
238 | 241 | | |
239 | 242 | | |
240 | 243 | | |
| |||
250 | 253 | | |
251 | 254 | | |
252 | 255 | | |
| 256 | + | |
253 | 257 | | |
| 258 | + | |
254 | 259 | | |
255 | 260 | | |
256 | 261 | | |
| |||
269 | 274 | | |
270 | 275 | | |
271 | 276 | | |
272 | | - | |
273 | | - | |
274 | | - | |
| 277 | + | |
| 278 | + | |
275 | 279 | | |
276 | 280 | | |
277 | 281 | | |
| |||
286 | 290 | | |
287 | 291 | | |
288 | 292 | | |
| 293 | + | |
289 | 294 | | |
290 | | - | |
| 295 | + | |
| 296 | + | |
291 | 297 | | |
292 | 298 | | |
293 | 299 | | |
| |||
306 | 312 | | |
307 | 313 | | |
308 | 314 | | |
| 315 | + | |
309 | 316 | | |
| 317 | + | |
310 | 318 | | |
311 | 319 | | |
312 | 320 | | |
313 | | - | |
314 | | - | |
315 | | - | |
316 | 321 | | |
317 | 322 | | |
318 | 323 | | |
| |||
342 | 347 | | |
343 | 348 | | |
344 | 349 | | |
| 350 | + | |
345 | 351 | | |
| 352 | + | |
346 | 353 | | |
347 | 354 | | |
348 | 355 | | |
| |||
0 commit comments