Repository navigation
Commit 89803c5
docs(skills): the platform skill teaches the package customizations read's contributions (#30071)
<!-- claude-projects-attribution: {"github_login":"huangyiirene"} -->
_Requested by **Irene** · [project
thread](https://claude.ai/code/project/chan_01TJXtQ1tVD26ecLDZxFS67x?thread=cmsg_01TJXtQ1tVD26ecLDZxFS67xEzujNK3mUgKv682JDmvunN)_
Fixes #29411
Clause-②: no
Metadata-protocol: none
The Fable mandate was waived by the maintainer; this PR was developed on
Opus.
## 维护者速读
- 改了什么:objectstack-platform 技能的「定制已安装包」一节,在 `GET
/packages/<id>/customizations` 段后新增一段,教读取结果的 `contributions`
成员:每个其他包加到基础包上的条目一条,带 `packageId`;`field` / `flow` 条目给出所在的基础包
`object`,`nav` 条目给出基础包的 `app`、目标 `group`(有则给)和条目
id(`name`);`counts.contributions` 数的是条目而非包。另加一个 `'@objectstack/skills':
patch` changeset。
- 为什么改:spec 的 `GetPackageCustomizationsResponseSchema` 早已声明
`contributions`(#28722 已在 main 上产出 `nav` 条目),技能只说该读取列出
overrides、extensions 和 switched-off,AI 读不到第四个列表。
- 风险与回滚:纯技能文本 + changeset。token 天花板就地付账:删了同文件三处复述(每处的规则在文件内另有归宿),6004 →
6000 / 6011,上限行未动,无 re-wrap。回滚即 revert。
- 先看:`skills/objectstack-platform/SKILL.md` 新段(L132)与三处删除;对照
`packages/spec/src/api/package-lifecycle.zod.ts` 的 `contributions` 与
`counts.contributions`。
- 两分钟验证:`node scripts/check-skills-token-ratchet.mjs`,预期 platform
SKILL.md 6000/6011。
- 需要你做的:Tier H 受管面(`skills/**`),需要 `GOVERNED_APPROVERS` 的批准;PR 保持 draft。
## What changes
`skills/objectstack-platform/SKILL.md`, "Customizing an installed
package (ADR-0146)". A new paragraph after the one that introduces `GET
/packages/hotcrm/customizations` (that paragraph is byte-identical):
```
That read's `contributions` lists what other packages add to the base, one entry per item with its `packageId`: a `field` or `flow` names the base's `object` it is on, a `nav` item the base's `app`, its `group` if any, and its id as `name`; `counts.contributions` counts items, not packages.
```
Each fact is read off `main` at `c23501b2`:
- `GetPackageCustomizationsResponseSchema.contributions`
(`packages/spec/src/api/package-lifecycle.zod.ts`): a discriminated
union on `kind`; the `field` / `flow` arm carries `object`, `name`,
`packageId`; the `nav` arm carries `app`, optional `group`, `name` (the
nav item's id), `packageId`. `packageId` is never the base nor its pair.
- `counts.contributions`: "`contributions.length`: items, not packages."
- **`nav` is served on main.** `readBaseContributions` in
`packages/runtime/src/domains/packages.ts` pushes `{ kind: 'nav', app,
group?, name: id, packageId }` from
`registry.getAppNavContributions(app)` for each app the base owns
(#28722 closed; `packages-customizations.test.ts` pins it). So the
paragraph teaches it plainly, with no "not yet served" mark.
- Not taught, on purpose: "a disabled package's items are not listed".
The runtime applies `isPackageDisabled` only to the `nav` loop (a
disabled package's flow is simply not registered; fields are not
filtered), so a general sentence would overstate it, and the card did
not ask for it.
`.changeset/29411-platform-skill-package-contributions.md`:
`'@objectstack/skills': patch`, with `Clause-②: no` and
`Metadata-protocol: none`. `@objectstack/skills` ships this catalog, so
the change publishes and takes a changeset, never `skip-changeset`.
### Token ratchet, paid in place (no ceiling row moved, no re-wrap)
| file | tokens before / after / ceiling | bytes before / after | lines
before / after |
|:--|:--|:--|:--|
| `skills/objectstack-platform/SKILL.md` | 6004 / 6000 / 6011 (headroom
7 → 11) | 24036 / 24019 | 429 / 426 |
The new paragraph is paid for by three deletions in the same file, each
a restatement whose rule keeps a home there. The lines around each cut
are byte-identical; nothing was rewrapped.
1. **"Exact shape: `ObjectStackDefinitionSchema` in
`node_modules/@objectstack/spec/src/stack.zod.ts`; each collection's
item schema sits in its domain folder (…)."** (3 lines and the blank
line, 201 bytes). Home: the References section ("Always `Read` the
source for exact field shapes") and `references/_index.md`, which lists
`stack.zod.ts` and every domain schema file.
`check:skill-top-level-keys` reads the enumeration paragraph above it by
its own anchor, not this line.
2. **"Raise it there; do not compensate for it here."** (the tail of the
"fix is upstream" bullet). Home: the "A platform defect means waiting
for the platform fix" bullet two items below ("No defensive coding, no
shape tolerance …", "Record the block against the platform issue").
3. **"Pick `demoStaff` whenever the demo needs an account to exist."**
(the last sentence of Demo accounts). Home: the section's opening, which
says a seed cannot create an account and to "Declare the people in
`demoStaff`", and the sentence before it, which says `devLogins` creates
nothing.
## Why
The skill told an author that the customizations read lists overrides,
extensions and switched-off items, and stopped there. The schema has
served a fourth list, `contributions`, plus its count, since #28722; an
AI reading only the skill would not know other packages' fields, flows
and nav items come back on the same read, or would read
`counts.contributions` as a package count.
## Verification
Head `21e8aa1a` (one commit on `c23501b2`).
<details><summary>Local gates on 21e8aa1: 45 derived, 45 run with exit
0, 0 NOT MEASURED (`dispatch-gates --ran`)</summary>
- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derived 45 commands for the two changed
files. All 45 ran after `pnpm install --frozen-lockfile` and a full
`pnpm build` (exit 0), each with a 900 s timeout and its exit code
captured before any pipe.
- All 45 exited 0, among them `check-skills-token-ratchet.mjs` (and
`--self-test`), `check-changeset-no-major.mjs`,
`check-empty-changeset.mjs`, `check:changeset-gate-self-tests`,
`check-comment-mask-corpus.mjs`, `check:skill-docs`,
`check:skill-top-level-keys`, `check:skill-identifier-liveness`,
`check:skill-frame-sync`, `check:skill-compatibility`,
`check:role-word`, `check:dts-closure`, `check:dual-build-cjs-loads` and
`check:lean-entry-closure`.
- `--ran` printed: `45 derived famil(ies) accounted for — 45 run, 0
NOT-MEASURED`.
- `node scripts/check-commit-card-trailers.mjs --range
origin/main..HEAD`: exit 0 (one commit, no card relation, model-free
trailer pair).
- Writes: one `git push` (the branch, 21e8aa1); one relay `pr_create`;
no GitHub MCP write.
</details>
- Evals: no case in
`skills/objectstack-platform/evals/config-plugins-ops.json` covers the
customizations read, so none is run or added for the new paragraph. Two
cases (L116, L134) cover the Demo accounts section that cut 3 touches;
their expected outputs rest on the sentences that stay (`demoStaff`
creates the accounts, `devLogins` creates nothing), so they read the
same.
## Human Minimum
- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
(No schema touched.)
- [x] 2. Every name I added uses the casing for its kind.
- [x] 3. No formatter ran; `pnpm lint` is CI's repo-wide run.
- [x] 4. One issue, one branch off an up-to-date `main`, one pull
request.
- [x] 5. A change that publishes carries a changeset, and both
declaration lines are filled in here and in the changeset.
- [x] 6. `packages/spec` not touched.
- [x] 7. No hand edits to `content/docs/references/`,
`packages/*/CHANGELOG.md` or `content/docs/releases/`.
- [x] 8. Title, body and comments are in English (the 维护者速读 block is the
repo's own Chinese reading aid).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01J8VVAjMvCpqNhHkd2m3T5A
Co-authored-by: Claude <noreply@anthropic.com>1 parent 8fa370c commit 89803c5
2 files changed
Lines changed: 14 additions & 7 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 | |
|---|---|---|---|
| |||
68 | 68 | | |
69 | 69 | | |
70 | 70 | | |
71 | | - | |
72 | | - | |
73 | | - | |
74 | | - | |
75 | 71 | | |
76 | 72 | | |
77 | 73 | | |
| |||
133 | 129 | | |
134 | 130 | | |
135 | 131 | | |
| 132 | + | |
| 133 | + | |
136 | 134 | | |
137 | 135 | | |
138 | 136 | | |
| |||
144 | 142 | | |
145 | 143 | | |
146 | 144 | | |
147 | | - | |
| 145 | + | |
148 | 146 | | |
149 | 147 | | |
150 | 148 | | |
| |||
403 | 401 | | |
404 | 402 | | |
405 | 403 | | |
406 | | - | |
407 | | - | |
| 404 | + | |
408 | 405 | | |
409 | 406 | | |
410 | 407 | | |
| |||
0 commit comments