docs(spec): 七项 description-surface truth sweep —— 一 PR 七条 Fixes,逐项清单评审 (#6243) - #6288
Merged
Merged
Conversation
…6137 #6065 #5676 #5886) First bundled-trivia sweep: seven same-class corrections to spec description surfaces that lied or drifted. No behaviour changes — every item is either truth-restoration or the execution of an existing ruling. - #6085 `shared/expression.zod.ts` dialect table: drop the retired `js` row (#3278 / ADR-0058 addendum — `ExpressionSchema` rejects it), add the real member `template`, and state that the table IS the enum. New pin `expression-dialect-docs.pin.test.ts` compares the two so neither can drift. - #6081 `stack.zod.ts` skills JSDoc: stop selling `triggerPhrases` (retired at #3896, now a `retiredKey()` tombstone) — point at `triggerConditions` plus `description`/`instructions`, which is #3896's own prescription. - #6161 strictness-ledger classification table: the `no gate` row still defined the class with two exemplars that have since had their parse wired and left it (#5020 / #5068). Record that the bucket's population is zero tree-wide, and that the verdict stays in the vocabulary regardless. - #6137 `ui/theme.zod.ts` / `ui/chart.zod.ts`: delete the two "nothing above this block may be a JSDoc block" warnings. #5059 made both hazards impossible — block selection now requires column 0, the header zone and no immediately following declaration, and a `//` line can no longer match. - #6065 (direction B) `api/endpoint.zod.ts` ×3 `.describe()`: `type`, `target` and `ApiMapping.transform` stop advertising what the publish gate rejects whole-key. The frozen vocabulary (#5040) is unchanged; the copy now says at authoring time what the gate says at rejection time. The verbatim mirror table in `packages/runtime/src/api-mapping.ts` is updated in the same pass. - #5676 `cloud/environment.zod.ts`: back-reference to the coarser 3-member `DiscoverySchema.environment` (the forward reference landed with #4828), plus `discovery-environment-subset.pin.test.ts` pinning the subset relation. No contract change — neither enum's membership moves. - #5886 `data/hook.test.ts`: re-spell the `input: { doc: … }` fixtures to the engine's real shape (`data`), the spec half of #5671. The old contract table was corrected at #5273; these fixtures still taught the disproved spelling. `content/docs/references/{shared/expression,api/endpoint}.mdx` regenerated — `check:generated` proved exactly those two stale and `--fix` regenerated only them. Fixes #6085 Fixes #6081 Fixes #6161 Fixes #6137 Fixes #6065 Fixes #5676 Fixes #5886 Co-authored-by: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011M7UwH25Unfi73UHim7ajY
…cription-truth-sweep
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
Contributor
📓 Docs Drift CheckThis PR changes 2 package(s): 118 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
github-actions
Bot
added
documentation
This was referenced Aug 7, 2026
Closed
Closed
qq9340100
added
skip-changeset
Claude
…cription-truth-sweep
PR #6224(#5553 / #6136)改了 build-docs 的模块描述行布局与裸路径链接改写, 并重写了全部参考页。本分支是后落地方,故按四步走:merge main → 重建 → check:generated 判定 → --fix 只重生成被证实陈旧的一项。 落点仍是本 sweep 的两张页(os-regen 合并驱动把它们记进 os-regen-pending): shared/expression.mdx 与 api/endpoint.mdx。新渲染器收掉了行间空行,方言表 因此首次渲染成一张真正的 markdown 表,而不是被空行拆散的六行。 内容核对:方言表 = cel / cron / template(无 js);endpoint 的 type / target / ApiMapping.transform 三行描述完整存活。 Co-authored-by: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011M7UwH25Unfi73UHim7ajY
Collaborator
Author
|
ACCEPT —— sweep 打包试点逐项清单评审(spec 车道 PM, 逐 job 结论亲读:24 checks 全 completed,22 success + 2 预期 skipped(Console Pin Gate;Check Changeset 按 skip-changeset),ESLint / TypeScript 均
一处维护者否决窗(dev 如实上报、不自定级,本席维持现状):#6065 的三段 describe 会随发布包 JSON Schema description 出货 —— 当前按 #6243 规格走 skip-changeset;若维护者认为该留 CHANGELOG 痕,改挂 @objectstack/spec patch changeset 即可,一行事。 已翻 ready + auto-merge。试点结论:跑顺 —— 按维护者 2026-08-07 指令,SKILL 的「发现分诊轮 sweep 打包」条款将起草(排在 #6301 出队后,同分支串行)。 Generated by Claude Code |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
首次 sweep 打包试点(#6243):七条同类 —— spec 的 description 面在说谎或漂移 —— 一 dev、一 PR、七条
Fixes齐关,评审按逐项清单。零行为变更;每一项要么是真相还原,要么是既有裁决的执行。⛔ 七项之外零改动(试点成败判据):
git diff --stat origin/main...HEAD= 13 个文件,逐一对应下表,无 rider。逐项清单
spec/src/shared/expression.zod.ts方言表(逐字进已发布参考页)js(配isolated-vm/quickjs引擎、用途写 "mapping, hook bodies"),缺真实成员templatejs行、补template行,并写明「本表即 12 行下的ExpressionDialect枚举」;procedural JS 走ScriptBody { language: 'js' },不是 L1 dialect(#3278 / ADR-0058 addendum,ExpressionSchema当场拒收)spec/src/stack.zod.tsskills JSDocretiredKey()拒收的键triggerConditions(context field/operator/value 的 AND)∩ agent allowlist;自然语言意图写进description/instructions。措辞复用 #3896 的退役处方(那是一次 SPLIT,不是改名)docs/audits/2026-07-unknown-key-strictness-ledger.md分类表no gate行ui/」—— 两个范例都已接通 parse 改判离开(#5020 / #5068)…counts.md全局与五个目录小计全是 0)。⛔ 不删no gate判定词:空类不是缺陷,是等下一个同形站点的词(#5249 为covered立的同一个理)spec/src/ui/theme.zod.ts:11-22、chart.zod.ts:13-18//警告:「本块之上不得出现 JSDoc 块」+「即使写在//行里,字面两星记号也会命中」/**在第 0 列、位于首个声明之前、且其后不紧跟声明,而//行被扫描直接跳过。已实读scripts/lib/file-description.ts逐条核实,非按 issue 转述spec/src/api/endpoint.zod.ts×3.describe()+runtime/src/api-mapping.ts逐字镜像表type/target/ApiMapping.transform的文案在向作者推销 publish 门整键拒绝的能力api-mapping.ts声明自己是这五条 describe 的 MINIMAL faithful reading,故同批更新其transform行spec/src/cloud/environment.zod.tsJSDoc + 新 pinstaging在这边一等、在 discovery 侧被拒,必须走resolveDiscoveryEnvironment)+ 新增子集 pinapi/discovery-environment-subset.pin.test.ts。⛔ 明确不改契约:两个枚举的成员一个没动spec/src/data/hook.test.tsinput: { doc: … }—— 旧表被 PR #5668(#5273)证伪并改为datadata(insert{ data, options }、update{ id, data, options }),连带两处context.input.doc断言。fixture 只喂开放形状的z.record,故这是纯 re-spell,零行为影响 —— 也正因如此它才能一直错着验证
check:generated判定恰好一项陈旧(content/docs/references/**),--fix只重生成它;合并 main 后复跑 10/10 up to date。⛔ 未手改任何生成物。references/shared/expression.mdx(方言表)+references/api/endpoint.mdx(三行 describe)。两页邻居条目逐一存活 —— 两文件合计仅 28 行变更,全部落在本 sweep 的行上。theme/chart/stack.zod.ts三项零文档 diff(前两者动的是//注释;后者的 JSDoc 不进参考页),这本身是 [finding]theme.zod.ts/chart.zod.ts里那两段「本块之上不得出现 doc block」的//警告,在 #5059 之后已过时(保守但无害) #6137 判断正确的旁证。check:liveness/check:empty-state/check:skill-examples/check:variant-docs/check:exported-any/check:dual-source-exports—— 6/6 PASS。@objectstack/spec334 文件 / 8484 测试全绿;@objectstack/runtime106 文件 / 1514 测试全绿;两包typecheck干净(spec 的check:test-typecheck债数 79 文件 / 691 错误未变,即两个新 pin 文件零新增债)。js行 → expression.zod.ts 的方言表仍把 js 列为活方言(还写着用于 "mapping"),且漏了 template —— 12 行之下的枚举正好相反 #6085 pin 变红,报expected [cel, cron, js, template] to deeply equal [cel, cron, template]与to not include 'js';EnvironmentTypeSchema的sandbox改名 → 「环境类别」这一个概念在 spec 里有两个枚举:DiscoverySchema.environment(3 成员)与 EnvironmentTypeSchema(7 成员) #5676 子集 pin 变红,报sandbox is advertised by DiscoverySchema.environment but is no longer an EnvironmentTypeSchema member。两处均按预告方向变红,随后原样还原。两个 pin 各自带反空断言(空左值会让
every()类断言假绿)。origin/main@2598216(含 action param 的options[]该不该讲字段级的逐选项词汇(color/visibleWhen)? —— 三处形状,三种拼法 #5016 /composeStacks的i18n仍是 last-wins —— #5005 裁决否掉的那个形状,只剩这一个键还在用 #5051 两条触及本 PR 同文件的提交,无冲突),重建 + 复跑全部门后如上。串行提示(给评审 / 合并者)
PR #6224(#5553 / #6136)改的是
scripts/lib/file-description.ts的渲染行布局,并重写了全部 ~170 张参考页 —— 包含本 PR 重生成的shared/expression.mdx与api/endpoint.mdx。 两者源文件不冲突,只在生成物上相撞;后落地的一方按 §10 走「merge main → 重建 →check:generated --fix→ 断言邻居条目存活」即可。#6094(flow.zod.ts墓碑)按 #6243 正文仍排除在外,等 #4415 后进下一轮 sweep;#4415 目前仍是 open issue、无在飞 PR,其 resync 条款本轮未触发。Changeset
按 #6243 与仓内惯例走
skip-changeset(纯 description / 散文面,零行为、零 API surface、零 authorable key 变化)。⛔ 一条如实上报、不自行定级:#6065 的三段 describe 会随发布包的 JSON Schema description 一起出货,严格说这是消费者可见的文案变更 —— 若维护者认为它该在 CHANGELOG 留痕,改走@objectstack/spec的 patch changeset 即可,该判断留给维护者而非本 PR 自定。范围外发现(已单开,⛔ 未夹带)
#6287 ——
preview/trial是EnvironmentTypeSchema的一等成员,但NODE_ENV_TO_DISCOVERY_ENVIRONMENT没有条目,靠?? 'development'兜底折叠。今天答案仍是对的(两者都非生产),但折叠方向没被声明,下一个新桶不会让任何门变红。查重已核:与 #5673(已 closed,讲未设置时的默认)、#5676(本 sweep,讲子集关系)均不重复 —— 子集 pin 钉的是「三个在七个里」,钉不到「七个各自折向哪里」,这是收编之后剩下的唯一一条隐式边。Fixes #6085
Fixes #6081
Fixes #6161
Fixes #6137
Fixes #6065
Fixes #5676
Fixes #5886
Generated by Claude Code