fix(skills,docs): align skills/docs with published spec; guard flat view containers#3096
Merged
Conversation
…iew containers Fixes the five skill/doc-vs-spec drifts found by the 2026-07-17 third-party evaluation of the 15.1.0 release (AI following the official skills produced metadata that failed or silently broke): 1. objectstack-data skill taught `defineDataset()` for seeds — the actual export is `defineSeed()` (`dataset` is reserved for the ADR-0021 analytics layer). Renamed the whole section incl. imports, type table, zod path. 2. Same skill taught a `type: 'unique'` validation — removed from the spec in #1475. Now teaches `indexes: [{ fields, unique: true }]`; also purged the fictional `async`/`custom` types from rules/validation.md, fixed `format.pattern`→`regex` (no `uuid` builtin), `conditional` to its real `when`/`then`/`otherwise` shape, converted all predicates to record-rooted CEL (`P` tag), and documented that `cross_field` is failure-condition (inverted) like `script`, per the runtime rule-validator. 3. objectstack-ui skill kanban example used a top-level `groupBy` — the real shape is nested `kanban: { groupByField, summarizeField, columns }` with top-level `columns` still required. Gantt examples had the same flat disease with wrong key names (`startField`/`dependencyField` → `gantt.startDateField`/`dependenciesField`); `timeSegments` moved inside the `gantt:` block; column `summary` is a plain enum, not an object. Added a `defineView` container primer to the skill. 4. docs ui/views taught flat view objects that `os validate` passed but the Console silently never rendered (ViewSchema strips unknown keys → empty container). Page rewritten around the `defineView({ list, listViews, formViews })` container + stack registration; property tables corrected (`columns` required; `name`/`label` optional; `span` over legacy `colSpan`; `visibleWhen` is record-rooted CEL). 5. README quickstart curl path `/api/v1/todo_task` → `/api/v1/data/todo_task`. Root-cause guard for #4: `defineView()` now throws on a container with zero views, and `os validate` gains a `view-container-shape` check (`validateViewContainers` in @objectstack/lint, run PRE-parse like the ADR-0053 check) reporting flat/empty `views: []` entries with a fix hint. The runtime view type-schema mapping is deliberately untouched (ViewItem + container + #2555 personalization shapes need their own change). Regenerated skills/README.md + content/docs/ai/skills-reference.mdx via gen:skill-docs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 3 package(s): 105 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
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
1 participant
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.
背景
2026-07-17 第三方评估(15.1.0 发布包实测)发现 5 处 skills/docs 与发布 spec 的漂移。这些直接伤害 AI-native 卖点:AI 按官方 skill 写元数据会连续挂。本 PR 全部修复,并把最重的一条(平铺 view 静默不渲染)的根因堵上。
修复清单(评估 5 项)
defineDataset→defineSeed(skills/objectstack-data 整节 + platform skill 的os data seed描述):实际导出是defineSeed(objectDef, {externalId, mode, env, records})(seed.zod.ts);dataset名字保留给 ADR-0021 分析语义层。skill 正文新增两者辨析提示。type: 'unique'校验类型已不存在(Validation rules: 6 of 9 spec rule types are declared but not enforced at runtime #1475 删除):SKILL.md 类型列表改为完整 6 个 discriminator(script/state_machine/format/cross_field/json_schema/conditional),显式教indexes: [{ fields, unique: true }];rules/relationships.md 的 junction 组合唯一示例同步改 indexes。groupBy→ 嵌套kanban: { groupByField, summarizeField, columns },顶层columns仍必填;对照KanbanConfigSchema与examples/app-showcase/src/ui/views/task.view.ts。defineView容器写法:原页面教的平铺 view 对象({ name, label, type, columns }顶层)os validate通过但 Console 静默不渲染。新页面以defineView({ list, listViews, formViews })+defineStack({ views: [...] })注册为主线,并加 Callout 警示平铺写法;属性表订正(columns实际必填、name/label实际 optional、span优先于 legacycolSpan、visibleWhen为 record 根的 CEL)。/api/v1/todo_task→/api/v1/data/todo_task(rest 包路由实证;脚手架模板本已正确)。顺带修复的同类漂移(修复中实证发现)
startField/endField/dependencyField(键名也是错的)→ 嵌套gantt: { startDateField, endDateField, titleField, progressField, dependenciesField, parentField };timeSegments示例移入gantt:块(objectui 运行时从ganttConfig.timeSegments读取)。summary形态(UI skill):summary: { function: 'min' }→ 平枚举summary: 'min'(ColumnSummarySchema)。async/custom类型(外呼/自定义校验 → lifecycle hook);format的键是regex非pattern、内建无uuid;conditional实为when/then/otherwise(无validations[]数组);所有谓词改 record 根 CEL(P标签),并按运行时rule-validator.ts明确cross_field与script同为反转语义(谓词=失败条件)——原文档的 cross_field 示例全部写反。defineView容器 primer(此前整个 skill 从未出现容器概念)。根因加固(第 4 条的"为什么 validate 放行")
根因:
ViewSchema四槽全 optional + Zod strip 未知键 → 平铺 view 被剥成合法空容器{},schema 门通过、loader 零展开、Console 零视图。defineView()现在对零视图容器抛错(带 wrap-it 提示)。@objectstack/lint新增validateViewContainers(ruleview-container-shape),os validate接线(与 ADR-0053 检查同样跑在 normalizeStackInput 之后、schema parse 之前,否则平铺键已被剥掉);平铺/空容器条目报错并给修复提示,独立 ViewItem(viewKind)条目放行。viewtype-schema 映射:运行时要同时容纳容器/ViewItem/Runtime view overlay drops viewKind/object — one grid sort permanently removes the view from the switcher #2555 个性化三形态,直接收紧会把 Console 个性化保存打挂 → 独立跟进 view metadata type-schema is a no-op for runtime shapes: ViewItem/personalization bodies strip to {} under ViewSchema #3095。验证
@objectstack/spec全量 254 files / 6890 tests 通过(含新增 defineView 空容器/平铺抛错用例);@objectstack/lint216 tests 通过(新规则 7 用例);@objectstack/clitsc 构建通过。os validate以view-container-shape拦截、exit 1;还原后 app-todo / app-crm / app-showcase(4 容器 21 对象)全部干净通过,无误报。gen:skill-docs重跑,check:skill-docs同步 ✓;docs 站点pnpm docs:build通过,/docs/ui/views已在浏览器实测渲染(容器主线、Callout、TOC 正常)。Follow-ups
viewtype-schema 对 ViewItem/个性化形态空转(strip-to-{}全放行)的收紧。🤖 Generated with Claude Code