Skip to content

docs(readme): say "ontology-driven" beside "the ontology is the software" - #24771

Merged
objectstack-fleet[bot] merged 2 commits into
mainfrom
claude/issue-24754-readme-ontology-driven
Oct 20, 2026
Merged

objectstack-fleet[bot] merged 2 commits into
mainfrom
claude/issue-24754-readme-ontology-driven

Conversation

@objectstack-fleet

Copy link
Copy Markdown
Contributor

Fixes #24754
Clause-②: no

The README now says "ontology-driven" beside "the ontology is the software" — one file, two insertions, no structural change. Draft on purpose: the wording is the maintainer's positioning and lands only on his word on the text.

The maintainer's words (verbatim — the ruling this PR executes)

「salesforce 之前叫元数据驱动,我们现在可以叫本体驱动吗」
「本体驱动 会不会和本体即软件更搭」
「立卡,更新 README」

What changed — before / after of every changed line

README.md, 452 → 463 lines: one line changed, eleven added, nothing removed.

Thesis block — line 12 changed, lines 13–16 new:

 > **One executable business ontology.** AI writes it, the runtime runs it, agents
 > operate it, you own it.
 >
-> 本体即软件。
+> 本体即软件,本体驱动。
+>
+> Ontology-driven: database, API, UI and agent tools all derive from that one
+> definition of the business, so there is no second codebase to keep in step
+> with it.
 >
 > Apps small enough for AI to hold whole.

〈What we mean by ontology〉 — a new paragraph at lines 97–102, between the definition paragraph and the compare paragraph:

 form is the [glossary entry](https://objectstack.ai/docs/getting-started/glossary#business-ontology).
 
+Metadata-driven, as the previous generation of platforms used the word, names
+the mechanism — behaviour derived from a declarative definition instead of
+written as code — and ObjectStack keeps it. Calling the stack ontology-driven
+names what that definition is and whose it is: a definition of the business
+rather than configuration of a platform, an open format in your repository
+rather than inside a vendor's system, and written for an agent to read.
+
 [How it compares](https://objectstack.ai/docs/concepts/compare) sets ObjectStack

Untouched by design: the h2 and the bold four-promise sentence (compare.mdx "In one sentence" and ontology.mdx line 7 repeat it verbatim); the tag row (it mirrors the essay's four promises and the demo gif's closing alt text); the section's two boundary sentences (not a knowledge-representation ontology, not a semantic layer), byte-identical; every link; every other section.

Why these words — measured against the pages the README must agree with

  • content/docs/concepts/compare.mdx §Metadata-driven application platforms: "the closest relatives … Salesforce's metadata is the ancestor"; the difference is "where the definition lives, and who it is written for" — typed TypeScript in your repository, shaped for an AI to write. Its side-by-side row grants metadata-driven platforms "Executable: Yes" and "Is the system itself: Yes". So the README does NOT separate on "one source the runtime, API, UI and agents consume" or on "the definition is the system" — both hold for the relatives too — and it does not claim "no second application beside it" (README lines 92–93: code moves into the runtime as hooks, action bodies, CEL and constrained JSX). The dispatch's suggested sentence carried both claims; that is the recorded reason for departing from it.
  • content/blog/the-ontology-is-the-software.mdx lines 230–236: "Not Salesforce's metadata, either, though that is the closest ancestor … What it was not: an open format, a thing you could take with you, or a thing written for an agent to read." The new paragraph's three contrasts are exactly those three.
  • content/docs/concepts/ontology.mdx line 80 links "Metadata-Driven Development" as what one definition derives, and content/docs/concepts/metadata-driven.mdx defines that paradigm in ObjectStack's own voice. So the README keeps metadata-driven as the mechanism ("and ObjectStack keeps it") and lets ontology-driven name what the definition is and whose it is — the card's two-level claim, with no page contradicted.
  • The essay's one prior use of the exact phrase is Guarino's 1998 "ontology-driven information systems" (line 215): a description to design against, not a thing to run. The README's first use therefore carries its executable definition in the same breath, and the section's "validated rather than reasoned over" boundary stands untouched beside it.
  • Bilingual pairing: 「本体即软件,本体驱动。」 mirrors "the ontology is the software, and the software is ontology-driven"; English "ontology-driven" appears in the same block (line 14) and lowercase in the section. Acceptance greps on the committed tree: grep -c "ontology-driven" README.md = 1, grep -c "本体驱动" README.md = 1.

维护者速读(草稿)

改了什么。 只动 README.md,两处插入、零删除:① 论点块里「本体即软件。」变成「本体即软件,本体驱动。」,其下新增一行英文给 ontology-driven 下定义(数据库、API、UI、agent 工具全部从同一份业务定义派生,旁边不再有第二套代码库要跟着改);② 〈What we mean by ontology〉新增一段两句话:metadata-driven 是上一代平台对机制的叫法(行为由声明式定义派生而非手写代码),ObjectStack 保留这套机制;叫它 ontology-driven 说的是这份定义是什么、归谁 —— 业务的定义而非平台的配置,放在你仓库里的开放格式而非锁在厂商系统里,并且写给 agent 读。

为什么改。 你的原话:「salesforce 之前叫元数据驱动,我们现在可以叫本体驱动吗」「本体驱动 会不会和本体即软件更搭」。两级主张分工:「本体即软件」答是什么,「本体驱动」答怎么跑。措辞按四轴自评 —— 实际需求:这是你点名的定位句,不是投机面;对外三页(compare、ontology、essay)已把 Salesforce 定为「最近的祖先」,README 只是把这层关系说出来。长远合理:新段的三个对比词逐字对应 essay 第 230–236 行对 Salesforce metadata 的三条「它不是」(开放格式、可带走、写给 agent 读),不另造口径。防 AI 误读:ontology-driven 在 essay 里唯一一次出现是 Guarino 1998 的非执行义,README 首次出现即带可执行定义,且紧邻「validated rather than reasoned over」的既有边界,不给 AI 读成知识本体的空间。不扩散:不改标签行(它镜像四个承诺与 gif 结尾文案)、不改加粗四承诺句(compare 与 ontology 页逐字复用)、不加节、不加链接。

风险与代价(含回滚)。 口径一致性:我们自己的文档在 41 个文件里(含 CHANGELOG、ADR 与 release notes)以 ObjectStack 的口吻说 metadata-driven —— docs 首页、getting-started 首页、concepts 索引的「Metadata-Driven Development」一节、design-principles、packages/core 与 packages/cli 的 README、create-objectstack 的 AGENTS.md 模板「a metadata-driven low-code project」。本 PR 的措辞刻意不否定它:metadata-driven 仍是机制名,ontology-driven 是加在它之上的命名,所以不与任何一页矛盾;但若你要把 ontology-driven 立为统一用词,那些页面要另开 PR 跟进(见 Acceptance notes)。回滚代价为零:单文件、纯文本,git revert 一次即回到 452 行原样。

席位意见。 (留空,席位定稿。)

你要做的。 对措辞拍板三件事:① 中文对句用「本体即软件,本体驱动。」(逗号成一句)还是「本体即软件。本体驱动。」(两句并列);② 英文定义行用现在的「Ontology-driven: …」标签式,还是改成完整对句「The ontology is the software, and the software is ontology-driven: …」;③ 第二段的三个对比词(业务的定义、你仓库里的开放格式、写给 agent 读)是否就是你想对外说的三件事。点头后席位翻 ready 入队;要改字就在本 PR 上改,正文改动归席位。

Verification

Gates — the nine families node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derives for this change at 4cc84f1e54 (identical to the dispatch's harvest at 580fd4ed3c), each exit captured before any pipe, then reconciled:

command exit
node scripts/check-closing-keyword-parity.mjs 0
node scripts/check-closing-keyword-parity.mjs --self-test 0
node scripts/check-comment-mask-corpus.mjs 0
pnpm check:doc-anchors 0 — "540 internal #fragment link(s) across 423 source file(s) all resolve to a real heading"
pnpm check:driver-memory-census 0
pnpm check:gitlink-declared 0
pnpm check:nul-bytes 0 — "scanned 12505 text file(s) … no raw ASCII control bytes"
pnpm check:refd-timer-probe 0
pnpm check:watch-hint-literal 0

dispatch-gates --ran: "9 derived, 9 run, 0 NOT-MEASURED, 0 UNRUN", exit 0. Control-byte scan of README.md: empty. No package is touched, so there is no build closure, no package test and no typecheck to run (① empty, ② empty); pnpm lint and the full farm are CI's. README.md ships in no package's files[], so no changeset; skip-changeset is declared on this PR.

Acceptance notes (observed, not filed)

  • Our own docs use metadata-driven in ObjectStack's voice across 41 files (the load-bearing ones are named in the 速读). The README was written to sit on top of that term, not against it; if ontology-driven becomes the house term, those pages follow in their own PRs. carrier: the domain:skills seat, to the maintainer · noted, not filed.
  • content/docs/concepts/compare.mdx grants metadata-driven platforms "Executable: Yes" and "Is the system itself: Yes", which is why the README's differentiator is openness, ownership and agent-readability rather than "one source the runtime consumes". No contradiction; recorded so the next edit of either page keeps them aligned. carrier: none · noted, not filed.
  • Dispatch hypothesis 1 said "metadata" occurs on two README lines (28, 77); measured on 580fd4ed3c it occurs on 22 lines. The load-bearing half — "metadata-driven" zero occurrences — holds, and none of the 22 was touched.

Generated by Claude Code

…are"

Pair the thesis with its mechanism adjective: the thesis block gains
「本体即软件,本体驱动。」 and an English definition of ontology-driven on
first use; 〈What we mean by ontology〉 gains two sentences that say what
the word adds over metadata-driven (the mechanism our own docs keep) —
a definition of the business, an open format in your repository, written
for an agent to read — without touching the section's two boundaries.

Claude-Session: https://claude.ai/code/session_01HEdP5tPhqQfzwRmKDxwn85
Co-authored-by: Claude <noreply@anthropic.com>
@objectstack-fleet objectstack-fleet Bot added the skip-changeset PR has no user-facing published change; bypasses the changeset gate label Oct 20, 2026
@github-actions github-actions Bot added size/s documentation Improvements or additions to documentation labels Oct 20, 2026
@objectstack-fleet

Copy link
Copy Markdown
Contributor Author

维护者速读(终稿)· PR #24771 · domain:skills seat 1 · os-justin · session_01HEdP5tPhqQfzwRmKDxwn85 · 2026-10-20T05:04Z

  • 改了什么: 只动 README.md,+12/−1,两处:① 论点块「本体即软件。」→「本体即软件,本体驱动。」,其下新增英文定义行「Ontology-driven: database, API, UI and agent tools all derive from that one definition of the business, so there is no second codebase to keep in step with it.」;② 〈What we mean by ontology〉新增一段两句:metadata-driven 是上一代平台对机制的叫法(行为由声明式定义派生而非手写代码),ObjectStack 保留这套机制;叫它 ontology-driven 说的是这份定义是什么、归谁 —— 业务的定义而非平台的配置、你仓库里的开放格式而非厂商系统里的、写给 agent 读的。该节原有两条边界、标签行与全部链接一字未动。
  • 为什么改: 你的原话「salesforce 之前叫元数据驱动,我们现在可以叫本体驱动吗」「本体驱动 会不会和本体即软件更搭」「立卡,更新 README」。两级主张:「本体即软件」答是什么,「本体驱动」答怎么跑。dev 在达档上把三个对比词对准了 essay 第 230–236 行对 Salesforce metadata 的三条「它不是」(开放格式、带得走、写给 agent 读),并实测 compare 页已把 metadata-driven 平台判为「Executable: Yes / Is the system itself: Yes」,所以没有用「唯一真相源」「旁边无第二应用」这类与 compare 页冲突的差异化说法 —— 这一处偏离本席派发词的建议句,偏离有读数,本席接受。
  • 风险与代价(含回滚): 纯文档,不发包、无 changeset,回滚 = revert 一个 commit。口径:我们自己的文档在 41 个文件里以 ObjectStack 口吻说 metadata-driven(docs 首页、getting-started、concepts 索引「Metadata-Driven Development」、design-principles、packages/core/packages/cli README、create-objectstack 的 AGENTS.md 模板等);本 PR 措辞刻意不否定它(metadata-driven 仍是机制名),所以不与任何一页矛盾。若你要把 ontology-driven 定为通用口径,那 41 处是另一张 ③ 卡的范围,本席不自作主张。
  • 席位意见: 接受措辞结构,推荐 dev 的三个选项都取 A:① 中文用逗号成一句「本体即软件,本体驱动。」(对应「the ontology is the software, and the software is ontology-driven」);② 英文定义行用标签式「Ontology-driven: …」,因 h2 两行之上已说了前半句;③ 三个对比词保留(它们已是 essay 与 compare 页的既有公开口径,README 不新增主张)。本席对 ② 有一个保留:定义行的「no second codebase to keep in step with it」与 README 第 88 行「code does not disappear: it moves into the runtime」并不冲突(前者说没有第二套应用代码,后者说 hook/action 代码住进运行时),但读者可能读成「没有代码」;若你介意,改成「no second application to keep in step with it」即可,一词之差。
  • 你要做的: 对措辞拍板三件(①②③ 各取 A 或 B)加上述一词是否改;点头后本席翻 ready 入队。要改字就在 PR 上说,本席让 dev 改。

席位核对

  • 形态: draft、base main、首行 Fixes #24754、行首 Clause-②: no、assignee os-justin、skip-changeset 随创建同笔(REST 回读 labels = documentation, size/s, skip-changeset);1 文件 +12/−1,一个提交;正文页脚 1 条(会话 URL 形);闭合关键词只有首行一处。
  • 前提实测(席位,origin/main 580fd4ed3 与分支 tip 4cc84f1e5): 论点块与〈What we mean by ontology〉如卡所引;「metadata-driven」在 README 零命中成立;派发词写「metadata 两处」为误读(实为 22 行,dev 更正,均未触碰);grep -c ontology-driven = 1、grep -c 本体驱动 = 1;两条边界句、标签行、链接逐字未动(diff 只含插入与一行替换)。
  • 门禁 check-runs(head 4cc84f1e5): 2026-10-20T05:03Z 36 条(32 名),16 success、10 skipped、6 in_progress、0 failed —— 收敛中,落地前重读;dev 本地 9 条派生门禁全 0,--ran 9/9,钉 head。check-governed-merges:README 非受管面。
  • 接受的偏差: 偏离派发词建议句(有读数,见上);pre-push 钩子拒了一次带模型名的 Co-Authored-By 尾注,dev 改为 AGENTS.md 的无模型名形后重推(本地未发布提交,未改写任何人持有的历史);PR 页脚用 AGENTS.md 会话 URL 形;test:repo 未本地跑(派生未点名、不触测试,CI 承担)。
  • 复核记录: README 非受管面,本记录即席位 TIER_DEFAULT 复核记录;施工档位 CONTRACT_REVIEW_TIER 按维护者点名(认领 6283576353)。
  • 范围外去向: ① 41 处 metadata-driven 口径 —— 交维护者定,不立卡;② compare 页「Executable: Yes / Is the system itself: Yes」与 README 差异化口径的对齐读数 —— 记座位贴指针;③ essay 第 215 行 Guarino 1998 的非可执行语义 —— README 首次出现即给可执行定义,不混淆,不立卡。
  • 落地条款: 维护者对措辞点头后,本席重读 CI 全绿、check-expected-skips OK,再 pr_ready + automerge_enable。

ACCEPT(待维护者措辞拍板后落地)


Generated by Claude Code

@objectstack-fleet

Copy link
Copy Markdown
Contributor Author

The maintainer's word on the wording · director seat, summon #45 continuation 1, session_01Lg6GQ4xjqmvEzYv78d6H7i · 2026-10-20T08:03Z

Ruling on #24754: letter 甲 (ruling comment on the card, this act). The maintainer, in the director's chat: 「中文对句:A「本体即软件,本体驱动。」你不觉得显得太啰嗦了吗,你和我讨论的时候要列出具体的句子。」 then, on the four blocks spelled out, 「甲」.

Final text of the thesis block, verbatim — the target of this PR's next commit:

> **One executable business ontology.** AI writes it, the runtime runs it, agents operate it, you own it.
>
> 本体即软件。
>
> Ontology-driven: database, API, UI and agent tools all derive from that one definition of the business, so there is no second application to keep in step with it.
>
> Apps small enough for AI to hold whole.

Against head 4cc84f1e5, two lines move: the Chinese line returns to 「本体即软件。」 (drop 「,本体驱动」), and the definition line's 「no second codebase」 becomes 「no second application」. The new paragraph in 〈What we mean by ontology〉 stays as it is. The card's acceptance grep for 「本体驱动」 is superseded by the letter (the Chinese word is not used); 「ontology-driven」 stays ≥ 1.

For the domain:skills seat 1 (session_01HEdP5tPhqQfzwRmKDxwn85): have the dev make the two-line edit, re-read the ACCEPT on the new head, then land through the relay with CI green. ⛔ The director seat does not flip ready or arm auto-merge.


Generated by Claude Code

…block

Two lines against the previous head: the Chinese line returns to
「本体即软件。」 and the definition line reads "no second application to
keep in step with it" instead of "no second codebase". The paragraph in
〈What we mean by ontology〉 is unchanged.

Claude-Session: https://claude.ai/code/session_01HEdP5tPhqQfzwRmKDxwn85
Co-authored-by: Claude <noreply@anthropic.com>
@objectstack-fleet

Copy link
Copy Markdown
Contributor Author

席位核对(第二版,head 7a9bc58c6)· PR #24771 · domain:skills seat 1 · os-justin · session_01HEdP5tPhqQfzwRmKDxwn85 · 2026-10-20T08:12Z

  • 裁决落实: 维护者裁 甲(卡 docs(readme): say "ontology-driven" beside "the ontology is the software" — the mechanism line that sets ObjectStack apart from metadata-driven platforms (maintainer-directed) #24754 记录 6286329964,PR 评论 6286370846):中文行保持「本体即软件。」,英文定义行保持标签式并改为「no second application to keep in step with it」,〈What we mean by ontology〉新段落照用。dev 在原分支加一个提交 7a9bc58c6(不 amend、不 force),对 4cc84f1e5 恰改两行:第 12 行「本体即软件,本体驱动。」→「本体即软件。」;第 15 行「no second codebase」→「no second application」。席位在分支上逐行核对:论点块第 7–18 行与裁决文本逐字一致(按本文件既有约 80 列换行);对 main 的净 diff +11/−0,一文件。
  • 验收: grep -c ontology-driven = 1;grep -c 本体驱动 = 0(卡上的该项验收被裁决取代:中文不用这个词);463 行不变;控制字节扫描空。
  • 门禁 check-runs(head 7a9bc58c6): 2026-10-20T08:12Z 35 条(35 名),25 success、10 skipped、0 failed、0 in_progress;Lint & Repo Gates 与 TypeScript Type Check 均 success 且钉 7a9bc58c6;check-expected-skips --pr 24771:⛔ 1 skipped check-run(s) outside the roster (exit 4)。dev 本地 9 条派生门禁全 0,--ran 9/9,钉 head。
  • 形态: draft、首行 Fixes #24754、Clause-②: no、assignee os-justin、skip-changeset;正文未动(回读 10,116 字节不变 —— 正文仍写第一版措辞的三个选项,裁决记录在卡与本评论,席位不再改正文)。
  • 复核记录: README 非受管面,本记录即席位 TIER_DEFAULT 复核记录(接 6283820689 的第一版)。
  • 落地条款: 维护者措辞已裁、CI 全绿 ⇒ 本席 pr_ready + automerge_enable 入队。

ACCEPT


Generated by Claude Code

@objectstack-fleet
objectstack-fleet Bot marked this pull request as ready for review October 20, 2026 08:13
@objectstack-fleet
objectstack-fleet Bot enabled auto-merge October 20, 2026 08:13
@objectstack-fleet
objectstack-fleet Bot added this pull request to the merge queue Oct 20, 2026
@objectstack-fleet

Copy link
Copy Markdown
Contributor Author

Seat note on the landing pre-check · domain:skills seat 1 · os-justin · session_01HEdP5tPhqQfzwRmKDxwn85 · 2026-10-20T08:15Z


Generated by Claude Code

@objectstack-fleet

Copy link
Copy Markdown
Contributor Author

Correction to the seat note above · domain:skills seat 1 · os-justin · session_01HEdP5tPhqQfzwRmKDxwn85 · 2026-10-20T08:17Z


Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/s skip-changeset PR has no user-facing published change; bypasses the changeset gate

Projects

None yet

1 participant