Repository navigation
Commit 7c1eeb1
docs(skills): the objectstack-data skill leads a hook author to the save notice (#30947)
<!-- claude-projects-attribution: {"github_login":"os-tesla"} -->
_Requested by **Tesla** · [project
thread](https://claude.ai/code/project/chan_01AXsQkLFKRdQCqQ3RTr6Jao?thread=cmsg_01AXsQkLFKRdQCqQ3RTr6JaoFJX6bqYge66A6RmcwQVyv1)_
Fixes #28819
Clause-②: no
Metadata-protocol: none
## 维护者速读
- 改了什么:`objectstack-data` 技能的规则索引里,`rules/lifecycle.md`
条目补上「保存提示」(`ctx.notice`)一句;`references/data-hooks.md` 的沙箱 `ctx.*` 表与
`HookContext` 清单各加一行 `notice`,都指向 `rules/lifecycle.md` § Save
Notice。新增全部用同文件内删除重复叙述来付账,两行 token 棘轮按落地读数下调(6123→6078、10066→10011)。
- 为什么改:保存提示的教学已在 `rules/lifecycle.md`,但索引把该页写成只讲数据保留,钩子参考里又没有
`notice`,写保存钩子的作者从本技能进来找不到它。
- 风险与回滚:只改技能文本与棘轮上限,不改运行时;若有误,revert 本 PR 即可。
- 先看:`skills/objectstack-data/references/data-hooks.md`(新增的 `ctx.notice`
行、`notice?` 成员,以及被删的三段)、`skills/objectstack-data/SKILL.md` 第 45 行与
`lifecycle` 属性行、`scripts/check-skills-token-ratchet.mjs` 两行下调。
- 两分钟验证:`node scripts/check-skills-token-ratchet.mjs | grep
objectstack-data/`,预期 `SKILL.md is 6078 tokens (ceiling 6078; headroom
0)` 与 `data-hooks.md is 10011 tokens (ceiling 10011; headroom 0)`。
- 需要你做的:`skills/**` 为 Tier H,席位契约复审通过后由你批准合并。
## What changes
**`skills/objectstack-data/SKILL.md` — the rule index (L45).** The
`rules/lifecycle.md` entry gains one clause: "plus the **save notice** a
hook hands the saver (`ctx.notice`)". The "distinct from lifecycle
*hooks* below" parenthesis stays, since the page is still the retention
page, and now also where the save notice is taught.
- Paid by: the `lifecycle` row of the optional-properties table dropped
"— a `telemetry`/`transient`/`event`/`audit` class must declare a
bounding policy or parsing fails", which the index entry one screen
above already states ("❗ append-only objects must declare one") and
`rules/lifecycle.md` § Validation Rules carries with the refused shapes.
The row keeps the bolded requirement and its link.
- The Verify section is untouched (queued card #30893 owns it).
**`skills/objectstack-data/references/data-hooks.md` — two rows.**
- Sandbox `ctx.*` table: a `ctx.notice` row — `(message) => void`, tell
the saver what this save set in motion, answered as the create/update
`notice` and shown on the save toast, no capability, insert/update only,
last call wins, linking `rules/lifecycle.md` § Save Notice. Every word
is read off `main`: `HookContextSchema.notice`
(`packages/spec/src/data/hook.zod.ts`, "no capability token", "last call
before the write answers wins", "present on every insert/update
dispatch", "absent on find and delete"), the body runner's hand-over
(`packages/runtime/src/sandbox/body-runner.ts`, `notice:
engineCtx.notice`) and the VM bridge
(`packages/runtime/src/sandbox/quickjs-runner.ts`, "No capability
gate").
- `HookContext` listing: `notice?: (message: string) => void; // Save
notice — rules/lifecycle.md § Save Notice`, beside `api?`, matching the
spec's optional member and `HookNoticeSetter`.
- Paid by three same-file deletions of restated prose:
1. In the `body` section intro, "and the one that was previously
undocumented (you had to reverse-engineer `@objectstack/runtime` to use
it)" — history of the page, not a rule; the sentence keeps "the one a
metadata-only runtime actually executes".
2. The blockquote "The former `ctx.session.tenantId` alias was removed
in v16 … (The generic driver-layer `execCtx.tenantId` /
`DriverOptions.tenantId` isolation knob is a separate axis and is
unaffected.)" — its first half is the `HookContext` listing's own
comment on `organizationId` ("The former `tenantId` alias was removed in
v16"), its second half is the "Two isolation axes" blockquote directly
below it.
3. The paragraph "`ctx.user` is the ergonomic shortcut for an
authenticated caller; it is `undefined` for system / unauthenticated
writes, so read `ctx.session?.organizationId` when a hook must work
regardless of whether a user resolved." — the `ctx.user` table row and
the listing's comment both say "`undefined` for system / unauthenticated
writes", and the code line right above it (`ctx.user?.organizationId ??
ctx.session?.organizationId`) is the fallback it describes.
**`scripts/check-skills-token-ratchet.mjs`** — both rows re-locked DOWN
at the landed counts (`6123 → 6078`, `10066 → 10011`), each with a
comment naming what paid for what. No ceiling rises.
**Changeset:** `.changeset/28819-save-notice-discoverable.md`,
`'@objectstack/skills': patch`, with both declaration lines.
### Skill bundle readings (`skills/**` touched)
| | before (`origin/main` 4d56914) | after (`79305e90`, same bytes as
`6edbf15a`) |
|:---|---:|---:|
| `skills/objectstack-data/SKILL.md` | 465 lines · 6087 tokens | 465
lines · 6078 tokens |
| `skills/objectstack-data/references/data-hooks.md` | 973 lines · 10056
tokens | 965 lines · 10011 tokens |
| all 11 `SKILL.md` in `skills/` | 4525 lines · 56670 tokens | 4525
lines · 56661 tokens |
Tokens are the gate's own convention, `ceil(utf8 bytes / 4)`, with the
20-byte `version:` stamp line unpriced on a `SKILL.md`.
## Tests
Prose only, so no package test and no ablation (the ablation rule
excludes docs). The teaching was checked against `main`'s code, not
memory:
- `node scripts/check-skills-token-ratchet.mjs --self-test` — `97 cases
pass`, exit 0.
- `node scripts/check-skills-token-ratchet.mjs` — both edited rows
report `headroom 0`, exit 0.
- `skills/objectstack-data/evals/` has no runner in this tree
(`skills/README.md` L74: the fixtures are scored by maintainers); the
two JSON fixtures are not touched and the ratchet still measures them
(1753 / 1749 tokens, not ratcheted).
## Acceptance notes
- The `ctx.notice` row sits between `ctx.crypto` and `ctx.title`, so the
table stays in its "gated members, then ungated helpers" order.
- Not a defect: `HookContext.notice` is declared optional on the schema
(a context built without a live engine parses), so the listing spells it
`notice?:`, like `api?:`.
- Out of scope, noted only: the optional-properties table and the rule
index both still describe `lifecycle` twice (row + index entry); that
duplication predates this PR and pays for it here, nothing more was cut.
## Verification
<details><summary>Derived gates: 64 derived, 63 run green, 1 NOT
MEASURED (head 6edbf15)</summary>
`node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derived 64 commands at `6edbf15a`. Each ran
with stdin from `/dev/null`, its exit code written to disk before any
pipe (ran-list: project files
`skills-seat-2/r2026-11-06/out/28819-gates-ran-6edbf15a.list`).
- 63 exit 0, among them `check-skills-token-ratchet` (+ `--self-test`,
97 cases), `check:skill-identifier-liveness`, `check:skill-frame-sync`,
`check:skill-compatibility`, `check:pm-skill-id-lint`,
`check:doc-authoring`, `check:role-word`, `check:nul-bytes`,
`check:changeset-gate-self-tests`, `check-empty-changeset --base
origin/main`, `check-adr-0087-registration --base origin/main`,
`check-changeset-no-major --base origin/main`,
`check:pm-governed-merges`, `check:pm-dispatch-gates`,
`@objectstack/spec check:skill-docs` and `check:skill-refs`,
`@objectstack/lint check:doc-formula-expressions`.
- `pnpm check:lean-entry-closure`: exit 3 (no `packages/objectql/dist`)
on the first pass; after `pnpm --filter '@objectstack/objectql...'
build` under the verify lock it exits 0 ("Admitted set held exactly (15
packages)"). The ran-list carries the 0.
- `pnpm check:dual-build-cjs-loads`: exit 3, PREREQUISITE NOT MET — it
loads every published package's dist (89 absent). **NOT MEASURED**
locally; the diff touches no package it loads, and CI's `Lint & Repo
Gates` runs it.
Reconciliation: `dispatch-gates --repo objectstack-ai/objectstack --ran`
printed `64 derived famil(ies) accounted for — 63 run, 1 NOT-MEASURED (1
DERIVED from a recorded exit 3)`.
Head `79305e90` is `6edbf15a` merged with `origin/main` 33043bd (one
i18n commit, no file in common). On the merged head the base-sensitive
families re-ran green: `check-skills-token-ratchet`,
`check-empty-changeset --base origin/main`, `check-adr-0087-registration
--base origin/main`, `check-changeset-no-major --base origin/main`,
`check:skill-identifier-liveness`, all exit 0; the four changed files
and their bytes are identical to `6edbf15a`.
Prerequisite builds, both under `scripts/pm/os-verify-lock.sh`: `pnpm
--filter '@objectstack/lint...' build` (VERDICT command-exit 0, 108 s)
and `pnpm --filter '@objectstack/objectql...' build` (VERDICT
command-exit 0, 150 s).
</details>
Tier H by path (`skills/**`). It stays a draft: the seat runs the
at-tier contract review, then the maintainer approves and merges.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01L9qibx4SVi1CLmwbLz82b7)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 1aeeafd commit 7c1eeb1
4 files changed
Lines changed: 30 additions & 17 deletions
File tree
- .changeset
- scripts
- skills/objectstack-data
- references
| 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 | |
|---|---|---|---|
| |||
510 | 510 | | |
511 | 511 | | |
512 | 512 | | |
513 | | - | |
| 513 | + | |
| 514 | + | |
| 515 | + | |
| 516 | + | |
514 | 517 | | |
515 | 518 | | |
516 | 519 | | |
| |||
678 | 681 | | |
679 | 682 | | |
680 | 683 | | |
681 | | - | |
| 684 | + | |
| 685 | + | |
| 686 | + | |
| 687 | + | |
| 688 | + | |
| 689 | + | |
| 690 | + | |
| 691 | + | |
682 | 692 | | |
683 | 693 | | |
684 | 694 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
42 | 42 | | |
43 | 43 | | |
44 | 44 | | |
45 | | - | |
| 45 | + | |
46 | 46 | | |
47 | 47 | | |
48 | 48 | | |
| |||
90 | 90 | | |
91 | 91 | | |
92 | 92 | | |
93 | | - | |
| 93 | + | |
94 | 94 | | |
95 | 95 | | |
96 | 96 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
310 | 310 | | |
311 | 311 | | |
312 | 312 | | |
313 | | - | |
314 | | - | |
315 | | - | |
| 313 | + | |
316 | 314 | | |
317 | 315 | | |
318 | 316 | | |
| |||
360 | 358 | | |
361 | 359 | | |
362 | 360 | | |
363 | | - | |
| 361 | + | |
364 | 362 | | |
365 | 363 | | |
366 | 364 | | |
367 | 365 | | |
368 | 366 | | |
| 367 | + | |
369 | 368 | | |
370 | 369 | | |
371 | 370 | | |
| |||
599 | 598 | | |
600 | 599 | | |
601 | 600 | | |
| 601 | + | |
602 | 602 | | |
603 | 603 | | |
604 | 604 | | |
| |||
622 | 622 | | |
623 | 623 | | |
624 | 624 | | |
625 | | - | |
626 | | - | |
627 | | - | |
628 | | - | |
629 | | - | |
630 | | - | |
631 | | - | |
632 | | - | |
633 | 625 | | |
634 | 626 | | |
635 | 627 | | |
| |||
638 | 630 | | |
639 | 631 | | |
640 | 632 | | |
641 | | - | |
| 633 | + | |
| 634 | + | |
642 | 635 | | |
643 | 636 | | |
644 | 637 | | |
| |||
0 commit comments