clearai-dsh 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,178 @@
 
 All notable changes to this project are recorded here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.5.0] — 2026-10-08
+
+这一版是 0.5 升级的阶段一与阶段二:预期与未解释项、评估者查数据可信、不可逆命令拦在执行前、三档等级、经验与本体分类,宿主下界提到 DSH 0.2。
+
+**开发集上的初步结果**(盲评,不当作有效性证据,见 [docs/optimization/sim-runs/](docs/optimization/sim-runs/)):反应器题漂移纠正 ClearAI 3/4、裸模型 1/4;同一现场 3 题序列里第 3 题全部用上了前两题的经验,第 3 题均分 1.5 对 1.17,差距来自漂移这一项;配方与探索深度两边持平。正式验证和探索深度([设计草稿](docs/optimization/0.5-plan/exploration-depth.zh-CN.md))留到之后的版本。
+
+### Added
+
+- **预期与未解释项(反常)**:步骤可以带预期 `expect`(预计看到什么、从哪条关系或经验来),动手前也能用 `RevisePlan(action="expect")` 补写。结果和预期或本体对不上的地方,交付时写进 `AdvancePlan.anomalies`,或随时用新工具 `Anomaly` 登记;它们挂在卡上,只有三个去处:被解释、写明理由排除、交给人。不阻塞结案。`STATE_VERSION` 17(投影多了 `anomalies`)。
+- **评估者查还有什么没解释**:任务书列出未解释项,纪律要求查原始数据里没登记的异常(参考读数、重复点漂移、装置之间的差)和排除理由站不站得住;裁决多一个 `anomalies` 字段,折成「评估者发现」的未解释项退回给模型。
+- **不可逆动作拦在命令上**:`Frame` 的 `irreversible` 声明动作和命令特征,匹配的 bash 命令执行前当场问人;不放行或没人能答就拒。
+- **经验(跨任务的「下次怎么做」)**:`Conclude(outcome="achieved")` 多一个可选的 `lessons`(每条一句,分坑 / 先核 / 会骗人的捷径 / 先验四类,带涉及的装置或量、凭据、不适用的条件)。结案评估者对照记录逐条判(裁决多一个 `lessons` 字段),支持的由系统写进 `clear/knowledge/lessons/<id>.json`(做的人写不了),其余在回执里列出。别的会话经工作区同步读到它们;卡上在立题、定计划、写预期前摆出最多 6 条,和眼下目标、下一步提到同一装置或量的排前面。人把文件里的 `status` 改成 `retracted` 就撤回。`STATE_VERSION` 18(投影多了 `lessons`,派生多了 `lessonRows`)。
+- **本体只留能产出预期的东西**:概念分类别 / 度量 / 现象(`kind`),度量必须写 `unit`;关系分影响 / 定义 / 测量 / 表现为(`kind`),影响关系可写大致形状 `shape`(单调升、单调降、有峰、阈值、耦合),测量关系写读数怎么核(`check`);实体可带带日期的 `history`。卡上「用到的关系」把形状和核法递出来;词面命中也看下一步要做什么和它的预期。都是可选格,旧文件照旧有效,指纹不变。
+- 0.5 的设计与升级计划:[meta 设计](docs/optimization/0.5-plan/meta-design.zh-CN.md)、[升级计划](docs/optimization/0.5-plan/upgrade-plan.zh-CN.md)。
+
+### Changed
+
+- 本体与认识论状态在决策点递到模型眼前:运行态卡给出判断用到的概念释义和相关事实的原话与边界;目标还没立或已结案时,直接列出以前留下的事实。
+- 本体的提示改为只写推理要用的东西:度量写成概念、释义写口径;因果关系写进关系;实体只在结论要指认它时才建。
+- 独立评估者可以复跑(`auditRerun`,预设打开):评估者在工作区副本里跑产物自带的脚本核数字,原工作区只读;评估期间收下的产物被改动过,这份裁决不认。
+- **等级只给三档**:L2 自己检验、L3 独立评估、L4 人放行。L0–L2 的细分从没改变过谁来判,合并;旧账里的 L0、L1 读作自己检验,新写的收成 L2。
+
+- **宿主下界提到 DSH `0.2.0-rc.2`(`engines.dsh` 为 `>=0.2.0-rc.2`),更早的宿主不再支持。** ClearAI 用到的事件、服务方法、客户端插座和 `dsh plugin` 命令行在 0.2.x 上都没有破坏性变化,运行时代码不用改;改的是只在旧的 root 目录名册上才有意义的工具和文档。
+- **`install.sh`(开发形态)改走产品那条路**:构建出包,再 `dsh plugin add` 装进 profile。旧做法把预设拷进 `~/.dsh/.agent-presets`,名册不读它,装得上却选不到 ClearAI。
+- **`verify-deploy` 只验装出来的那个包**,预期的工具数与段数从部署的目录现算;`verify-clean-install` / `verify-lifecycle` 只认声明行;`e2e-run` 只在宿主还带着 `@deepseek-ai/dsh-invariants` 时才插那一行(`0.2.1-alpha.1` 已移除该包)。
+
+### Removed
+
+- 对手判断(`rival` / `split_by`)与「检验可能太弱」的提示:两道难题的 8 组运行里对手 0 次使用,提示连续出现也没改变做法。
+- 运行态卡上的本体提纲与计数:它从没改变过下一步。卡上只出现被判断引用到的本体项。
+- `clearai-dsh root-yaml` / `seed` / `unseed`:它们服务的是旧名册的目录扫描,0.2.x 宿主里没有这个名册。`doctor` 改为检查组合里有没有 `preset-clearai` 声明行。
+
+### Fixed
+
+- 判断几乎从不升格成事实:升格只看模型自己给步骤标的等级,而 L0–L2 允许自判,五个长程任务的 9 次运行里模型一律标 L1/L2,一条事实都没有。现在结案那次独立评估顺带逐条判还活着的判断,判为支持的升格(证据记为独立、等级按目标门槛),判为推翻的不升格并照常复核已有事实;不多派评估者。
+- 别的会话留下的事实被新证据推翻时不会问人:这一问只认本目标的判断编号。现在判断可带 `retests: "<事实 id>"`,复检被推翻就当场问人撤回还是维持,结论写回事实文件。
+- 复检旧事实时模型把判断写成「旧事实被推翻」,评估判支持后它升格成一条与旧事实相反的新事实,旧事实照旧「已确立」,也没人被问。`retests` 的说明和提示词现在要求 claim 照抄旧事实原来的说法。
+
+## [0.4.0] — 2026-10-02
+
+这一版包括「少即是多」改造的全部六个阶段(见下面各段)、本体改成文件树,以及中英两种语言的完整支持。
+
+**两种语言。** 系统自己写的每一句话都跟着人说话的语言走。`STATE_VERSION` 16(投影多了 `language`);旧会话不迁移。
+
+### Added
+
+- **语言跟着人走**:人用中文写就是中文,用英文写就是英文,按会话、按人写的消息判(系统注入的消息不算)。覆盖工具结果、运行态卡、问人的话(选项按两种语言都认)、三段提示词、六件工具的说明与参数说明(英文会话在装配提示词时换成英文版)、评估者任务书与裁决 schema、技能、`clear/` 下系统写的文件(目标文档、事实总览、阶段归档、过程本体货架)、本体文件的校验信息。面板跟着界面语言,命令行跟着 `--lang` 或系统语言。
+- **两个真实案例**:[JEPA 世界模型](docs/cases/jepa-world-model.zh-CN.md)与 [Navier–Stokes](docs/cases/navier-stokes.zh-CN.md),原始记录在 `docs/cases/runs/`,中英截图在 `docs/shots/{zh,en}/`(在真 DSH 里回放两场真跑拍的)。
+
+### Changed
+
+- **文档只写现在的设计**:删掉改造方案、诊断与过程记录,旧的三个虚构案例换成两个真实案例。
+
+**本体改成文件树。** 设计见 [领域本体](docs/domain-ontology.zh-CN.md) 第 5、6 节。
+
+### Changed
+
+- **本体是 `clear/ontology/` 下的 JSON 文件树**:`concepts/`、`relations/`、`entities/`,`X.json` 描述 X,孩子放在同级 `X/` 目录(概念嵌套 = is_a,实体嵌套 = 组成)。模型用原生文件工具写,系统写一份 `SCHEMA.json` 说明格式。
+- **三道检查**:写时单文件校验(不合格拒写);读时跨文件校验(只标不拦,问题列在卡上与图下);升格时全量校验(不合格不升格)。
+- **事实写成文件并跨会话累积**:每条一份 `clear/knowledge/facts/<id>.json`,带所用定义的指纹;定义改了,这条事实标「定义已变」进「待处理」。`INDEX.md` 从全部事实文件渲染。
+- **图上目录嵌套成可收起的子图**:点多时默认收到第一层,+N 展开。
+- 结案后提示模型把可复用的做法写成原生技能(`.agents/skills/<名字>/SKILL.md`)。
+
+### Fixed
+
+- 后一次 `Conclude` 会把之前目标的假设再升格一次。
+- 相对路径能绕过受保护目录;读受保护目录的文件也被拦。
+
+### Removed
+
+- 4 件本体工具 `Define` / `Deprecate` / `RegisterInstance` / `Assert`(工具 10 → 6),以及 `clear/ontology/domain.md` 读面。
+
+
+**「少即是多」第六阶段:呈现。** 按改造方案第六阶段的改动清单。机制、十件工具、账本事件与 `STATE_VERSION` 都不变。
+
+### Changed
+
+- **本体格改成图为主。** 页眉一行问题、一行计数、「待处理」和一条进度轨(判断 → 检验 → 已验证 → 入本体);中间是本体图 / 实体图二选一(星图式,已验证的关系实线、待核验虚线);下面是结论清单,一条一行,按 已验证 / 待核验 / 验证中 / 不确定 / 已推翻 / 已替换 分组。点开一条依次是 进度、可信度怎么变的、补充。
+- **判断有短名。** `Frame` 的每条判断可带 `name`(十二字以内),没给就取主张开头;工具里引用判断时 id、短名、主张原文都认。账本里的 id 不变。
+- **说人话。** 运行态卡与工具结果不再出现内部编号与 `support / refute`;单次结果只说 支持 / 推翻 / 不确定(`AdvancePlan` 也收这三个中文词),等级写成 自己推了一遍 / 引用已有材料 / 可复算 / 独立核验 / 人放行。卡没变就不再附。
+- **世界树**改成目录式:每步一行,点开才看检验了哪条判断、结果是什么;页眉不带计划编号。
+- 英文界面里右栏页签叫 World Tree(此前误作 Worldlines),结果与状态词首字母大写。
+
+### Removed
+
+- 面板上的命题货架、缺口栏、状态流转图、词汇维护区与本体编辑抽屉;`/api/clearai/gate` 整条路由(人门自第三阶段起由开门的那次调用当场问人)。
+- 收件箱:换成派生的「待处理」(计划连拦停下、结论互相矛盾),只陈述、不放按钮;本体格页眉与输入框旁「待处理 N」读同一份。
+
+
+**「少即是多」第五阶段:提示词收成三段。** 按改造方案第五阶段的改动清单。
+
+### Changed
+
+- **提示词 21 段 → 3 段**,约 1.5 万字收到 2 千字出头:身份(`clearai/identity`)、循环(`clearai/loop`)、对人说话(`clearai/speaking`)。每个工具怎么用写在工具自己的说明里,现在是什么状态由运行态卡给。
+- 人格前缀只留一句身份;`clearai-loop` 技能只讲提示词与工具说明都没写的部分:准入核什么、被拦之后怎么走、评估卡怎么读。
+
+### Removed
+
+- 讲原生工具用法的段(文件读写、网页、技能、委派、Python 环境)、已删机制的残留说法(`lab/` 与 `products/` 目录约定、`PROJECT.md` 占位、`setup_cjk()`、`retract_fact` / `keep_fact`),以及只由提示词承载的「引擎级异常降权只读恢复」细则(身份段留一句:结局不明先看当前事实)。机制、工具、状态形状都不变。
+
+**「少即是多」第四阶段:Conclude 门收紧,工具面收拢。** 按改造方案第四阶段的改动清单。
+
+### Changed
+
+- **Conclude 只剩一道实体门**(`requireLandedEntities`),而且只管**将要升格**的判断(存活、零推翻、支持等级够升格):它断言里的每个主体都得是实体图上的实例节点(登记过的实例,或 Assert / 已升格事实带出来的节点)。「落图」从「要有一条边」改成「节点在」,所以 `RegisterInstance` 一次就够,不必再 `Assert` 同一句话。门在派评估者之前判,拦下不花评估。
+- **缺口 7 → 3**:留下 `untouched_claims`、`prose_only_claims`、`entities_unlanded`。`entities_unlanded` 的读数列出具体的 `类型|id`,出路写明 `RegisterInstance` 或 Frame 修订。
+- **工具 19 → 10**:`Frame`、`Conclude`、`CreatePlan`、`AdvancePlan`、`RevisePlan`、`ClosePlan`、`Define`、`Deprecate`、`RegisterInstance`、`Assert`。`RevisePlan` 以 `action: add | refine | void` 合并了改计划、补判据、作废一步;`Define` 给了 `range` 是谓词、否则是概念,同 id 再 Define 是修订展示字段,改语义(上位、定义域、值域、函数性)拒为 `semantics_changed`;`Deprecate` 兼管概念与谓词。账本事件名不变。
+- 投影状态版本升到 14:假设带 `unlanded`,不再有 `skips` / `untouchedLevels`。
+
+### Removed
+
+- 配置 `requireTypedPromotion`、`requireLevelReasons`(写了在组装时报 `unknown_config`);缺口 `no_language`、`unstructured_facts`、`levels_skipped`、`orphan_terms`。
+- 整套跳级机制:`ExplainLevelSkip`、运行态卡的「未走过」、面板的等级导引。旧账本里的 `level/skipped` 折叠时静默跳过。
+- `CheckPlan`(运行态卡每回合都在)与 `QueryKnowledge`(两轮六场模拟里一次没被调用;词表在 `clear/knowledge/`)。
+
+**「少即是多」第三阶段:目标层挂到原生 goal,交付与裁决分开。** 按改造方案第三阶段的改动清单。
+
+### Changed
+
+- **完成与结果分开。** 交付成立 ⇒ 这一步完成,不论结果是支持、推翻还是说不清;推翻和说不清都是合法结果,各记一条证据(带 `hypothesis`)。此前推翻的那一步收不了尾,只能作废。
+- **评估者给两份判断**:交付成不成立(`holds`: yes / no / unclear),以及对每条被检验判断的结果(`results[]`)。交付不成立才不推进、计一次连拦。评估卡版本 `clearai.audit.v2`;旧形状的 `verdict` 仍读得懂。
+- **一步可以检验多条判断**:`tests: { hypotheses: [...], level }`(旧的 `tests.hypothesis` 仍接受)。`AdvancePlan` 的参数是 `basis` 与 `results`(L0–L2);L3 以上由评估者给结果。
+- **`SetGoal` → `Frame`、`CloseGoal` → `Conclude`。** `Frame` 在宿主原生 goal 上建(或改)一条目标,续跑由原生 goal 驱动;`Conclude` achieved ⇒ 原生 goal 完成并声明交付物,abandoned ⇒ 原生 goal 置阻塞。守卫拦住原生 `update_goal` 直接完成目标。
+- **人门当场问。** L4 放行、计划连拦到阈值、推翻证据碰到已确立的事实,都由开门的那次调用经原生提问卡(`userQuestions`)当场问人;没人能答 ⇒ 原生 goal 置阻塞(`clearai-needs-human`)。面板上的人门动词只剩本体四个;旧日志里的撤回 / 维持照样折得出来。
+- 挂上原生 `tool-goal`、`command-goal`、`plan-mode`。工具面 19 件,提示词 21 段(澄清协议只剩一段)。投影状态版本升到 13。
+
+### Removed
+
+- ClearAI 自己的续跑窗口(`turnDemand`、布防 / 按住 / 收兵、`continuation/set`)与续跑额度(`maxAutoTurns`)。
+- 运行档(`autonomy`)与两套澄清措辞。
+- 计划审阅记号(`RequestPlanReview`、`plan/confirmed`、`confirmed_by`):它从来不是门;动手前给人看计划用原生 `/plan`。
+- 收件箱里等人处置的条目与面板上的撤回 / 维持按钮;「连续两次无法判定就强制改」那条规则(说不清是合法结果)。
+
+---
+
+**「少即是多」第二阶段:宿主已经有的,交还宿主。** 按改造方案第二阶段的清单删除;机制骨架(目标 / 计划 / 准入 / 证据 / 本体)不动。
+
+### Removed
+
+- **世界线**(`ForkPlan` `AdvanceWorldline` `ConvergeFork` `WorldlineStatus` `AwaitWorldlines` `AbandonFork`、执行者子任务、横评仲裁、世界树里的车道)。并行探索改由原生 `subagent` 承担:做法迥异的路线就是竞争的假设,各由一个步骤检验。
+- **旁路账本与文件恢复**(`FileHistory` `RestoreFile`、回合快照、交付点提交、`ledgerMaxFiles`)。下面「账本不再往用户的仓库里提交」那一节描述的旁路账本随之整体移除;每轮改了什么交给宿主的 `dsh-workspace-changes`。
+- **侦察**(`SpawnScout` `MapScouts`、开工前侦察、资料面)、**外脑**(`brain.js`、`SaveSkill` `WriteMemory`、技能候选与扶正)、**模板技能与铺工作区**(`preset/template/`、空文件夹里的 `PROJECT.md` 与目录骨架)、**自己的 `/` 命令**(`commands.js`)。
+- 界面:产物页签与 `/api/clearai/deliverables`、技能 · 记忆页签与 `/api/clearai/brain`、续跑状态行;人门里与上述机制相关的动作(`adopt_branch` `abandon_fork` `promote_skill` `confirm_provisional`)。
+- 配置键:`templateDir` `scoutToolFilter` `gitWorldlines` `ledgerMaxFiles` `executorToolFilter` `precommitRecon` `mapScoutMax` `mapScoutConcurrency` `autoDispatchExecutors` `autoAdoptMinGap` `forkArbitration`。
+
+### Added
+
+- **同一计划里两步不许声明同一个产物路径**(`CreatePlan` / `AmendPlan` 立约时就拒):子任务共用一个工作区,撞路径的两条路线会互相覆盖。
+
+### Changed
+
+- 工具面 20 件(目标 2 · 计划 8 · 本体 10),提示词 21 段生效。
+- 投影状态版本升到 12。旧会话照样读得开:被删机制的事件被安静跳过,不报错也不显示。
+- 测试与长测剧本同步瘦身:世界线与侦察剧本换成「竞争路线」剧本;套件 17 份。
+
+**账本不再往用户的仓库里提交。** 工作区本身是 git 仓库时,内核的账本(交付点、回合边界快照、恢复)与 git 世界线(分支、合并)此前**直接用那个仓库**:每个回合边界在用户**当前分支**上 `git add -A` 并以 `clearai <clearai@local>` 提交,世界线分支 `clearai/*` 也开在里面。于是用户没写完的改动、模型按技能约定写的 `lab/` `products/`、排查用的 `.tmp-*` 一起进了他的历史,下一次 push 就上了远端——本仓库自己就这样吃进过几十条「探索期快照」(独立验证员 2026-09 也记过同一件事,当时判为「不是源码缺陷」)。
+
+> 过渡修复:后续计划把账本整体交给宿主(`dsh-workspace-changes`),届时本节描述的旁路账本会被移除。
+
+### Fixed
+
+- **账本与世界线一律住在旁路账本**(`$DSH_HOME/storages/clearai/ledger/<slug>`):`gitContext` 删掉「工作区是 git 仓库就直接用它」那条分支。旁路账本认工作树里的 `.gitignore`、自动跳过用户的 `.git/`,所以账本看见的内容与用户看见的一致;`FileHistory` / `RestoreFile` / 世界线的行为不变,只是记录的位置换了。对用户仓库做的**唯一**一件事:在它本地的 `.git/info/exclude` 里加一行 `clear/worldlines/`,让嵌套的工作副本不出现在 `git status` 里(不进历史、不外传)。
+- **分叉前先记一笔工作区快照**:账本的 HEAD 只在回合边界与交付点前进,不记的话世界线从上一笔快照分出去,看不见这之后写下的文件。采纳时主线上有挡路的未跟踪文件,也按「先存快照再合并」处理(此前只认「本地修改」那一种拒绝)。
+- **开场的残留读数两处都数**:旁路账本里的 `clearai/*` 分支,以及**升级前**留在用户仓库里的那些。
+
+### Changed
+
+- 旁路账本的文件数上限(`ledgerMaxFiles`,缺省 20000)从此对 git 工作区也生效:超过上限的大仓库里账本与 git 世界线退化成声明目录,并如实说明原因(此前 git 工作区不受这条限制,因为它写的是用户自己的仓库)。
+- 仓库清理:删除误入版本库的 ClearAI 工作区残留(`lab/`、`products/`、`.tmp-fontdiag/`);案例证据搬到 `docs/cases/runs/`,营销卡片脚本搬到 `tools/marketing/`;`.gitignore` 挡住工作区约定的目录;新增 `tools/check-workspace-residue.mjs` 并接进 CI(不许跟踪工作区产物与根上的 `PROJECT.md`,PR 里不许有 `clearai@local` 的提交)。
+
 ## [0.3.1] — 2026-09-29
 
 **两个死结:计划置 blocked 后再也解不开,续跑窗口的阻塞码收不了兵。** 两条都不是措辞问题,是机制自己在文档承诺的出口上焊死了——0.3.0 的「连拦达阈值 ⇒ 置 blocked、停下等人」写得没错,可人按卡上说的三条出路走,一条也走不出去。

package/README.md

@@ -16,14 +16,14 @@
 ClearAI is an **ontology discovery and exploration platform**, built on two core concepts:
 
 - **Domain ontology** (what you get) — your project's own vocabulary, the knowledge entries established through the loop, and their graphs. At the end of a research session you hold a continuously growing knowledge structure, retrievable next round by concept.
-- **Epistemic loop** (how you get it) — a disciplined seven-stage path: frame, hypothesize, plan, observe, verify, evaluate, record. Every edge is tested by evidence and independent evaluation.
+- **Epistemic loop** (how you get it) — question → judgement (state what would prove it wrong) → a test that could fail → evidence → bounded conclusion → grows into the ontology. Every edge is tested by evidence and independent evaluation.
 
 > Other knowledge graphs pile up edges by extraction and assertion; here every edge has to be earned through the loop.
 
 ```bash
 # Install (npm package, prebuilt — no build step, no allowBuilds prompt)
-dsh plugin --profile web add clearai-dsh@0.3.1
-# or in the app: Plugins → Add plugin → clearai-dsh@0.3.1
+dsh plugin --profile web add clearai-dsh@0.5.0
+# or in the app: Plugins → Add plugin → clearai-dsh@0.5.0
 ```
 
 Restart `dsh web`, then pick **ClearAI** in the preset picker at the top of a new session. That is the whole setup. [Full install notes ↓](#install-and-use)
@@ -34,7 +34,7 @@ Restart `dsh web`, then pick **ClearAI** in the preset picker at the top of a ne
   <img src="docs/diagrams/ontology-hero.png" alt="The epistemic loop (left) growing a domain ontology (right)" width="1200">
 </picture>
 
-*Left: the Epistemic Loop — seven stages. Its emerald fact dot is also the first node of the domain ontology on the right. Right: the ontology graph — dark is a concept, light is a value form, emerald an instance; the instance carries two contradictory assertions — **the two readings are tinted amber**, marking that they do not agree. The system reports the conflict; retracting or keeping is a human decision.*
+*Left: the Epistemic Loop. Its emerald fact dot is also the first node of the domain ontology on the right. Right: the ontology graph — dark is a concept, light is a value form, emerald an instance; the instance carries two contradictory assertions — **the two readings are tinted amber**, marking that they do not agree. The system reports the conflict; retracting or keeping is a human decision.*
 
 ---
 
@@ -66,7 +66,7 @@ Most agent loops track one thing: whether the task is done. The Epistemic Loop a
 
 *Inside the ring is the instrument's read-out: the L0–L4 axis, the **pre-registered** threshold as a dashed line, and five observations with error bars — the supported one filled, the inconclusive drawn as a dashed circle, the refuted left in place with a slash through it (nothing is deleted). The emerald dot at the opening is the one reading that crossed the threshold and settled as a fact.*
 
-At runtime, the seven stages compress into four beats — plan, execute, observe, reflect. State is derived from the session record with no second store; the tools the model holds contain no field in which it could declare a step complete.
+State is derived from the session record with no second store; the tools the model holds contain no field in which it could declare a step complete, and a goal completes only after independent evaluation. ClearAI does only what the host cannot — the epistemic contract, the domain ontology, presentation; goal continuation, subagents, asking you, deliverable cards and file history all come from DSH itself.
 
 ClearAI does **not** claim recursive self-improvement. It provides the epistemic substrate a self-improving system would need. See [Positioning](docs/positioning.md) and the [OpenRSI survey](docs/research-openrsi.md).
 
@@ -74,16 +74,16 @@ ClearAI does **not** claim recursive self-improvement. It provides the epistemic
 
 ## Install and use
 
-**Requirements:** DSH ≥ `0.1.7-alpha.1` — that generation introduced the composition declaration line this preset rides on. Verified against the host's `0.1.7-rc.2` and `0.2.0-rc.1`.
+**Requirements:** DSH ≥ `0.2.0-rc.2` (the current `latest`). The preset is registered through a composition declaration line, which is the only way the host's preset registry finds presets. Verified against the host's `0.2.0-rc.2`, and also checked against `0.2.1-alpha.1`. Hosts older than `0.2.0` are no longer supported.
 
 **Recommended — install it in the app, with the version pinned:**
 
-In the sidebar open **Plugins → Add plugin**, enter `clearai-dsh@0.3.1`, and install. That is DSH's own plugin manager: it hands what you type to pnpm, checks that the package declares a bundle and is compatible with this host, and applies it live. (The Settings page **插件列表 / Plugins** is the read-only inventory — installing happens on the sidebar's Plugins page.)
+In the sidebar open **Plugins → Add plugin**, enter `clearai-dsh@0.5.0`, and install. That is DSH's own plugin manager: it hands what you type to pnpm, checks that the package declares a bundle and is compatible with this host, and applies it live. (The Settings page **插件列表 / Plugins** is the read-only inventory — installing happens on the sidebar's Plugins page.)
 
 **Or from a terminal — the same install:**
 
 ```bash
-dsh plugin --profile web add clearai-dsh@0.3.1
+dsh plugin --profile web add clearai-dsh@0.5.0
 ```
 
 This installs the prebuilt package from the npm registry. Nothing is compiled on your machine, so there is no `allowBuilds` grant to approve — the plugin is ready the moment the command returns.
@@ -116,27 +116,27 @@ dsh plugin --profile web add github:Clearailhc/clearai-dsh
 
 Git fetches source rather than build artifacts, so pnpm ≥10 will refuse to run the `prepare` script until you add an `allowBuilds` entry to the profile's `pnpm-workspace.yaml`. That grant means *permission for this package's code to execute on your machine at install time* — grant it only if you have read the source, and pin a commit. If you just want to use ClearAI, use the npm install above.
 
-The installer's output follows your system language (`--lang zh|en` overrides it, `doctor` / `seed` / `unseed` take the same flag). Its only runtime dependency is `zod`; the graph stack is bundled into the client half at build time.
+The installer's output follows your system language (`--lang zh|en` overrides it, and `doctor` takes the same flag). Its only runtime dependency is `zod`; the graph stack is bundled into the client half at build time.
 
 Restart `dsh web` afterwards (`npx @deepseek-ai/dsh web`), then **create a session and switch to the `ClearAI` mode in the picker at the top**:
 
 1. Open `dsh web` and click "New session";
 2. Click the current mode name at the top (default: **Standard mode**) to open the preset list;
 3. Pick **ClearAI** — its card reads "利用认识论循环构建可信本体。Build a trustworthy ontology through the epistemic loop.";
-4. Just ask your question. Ordinary Q&A runs as usual; once you set a goal and register hypotheses, the system enters knowledge mode by itself: known facts come to you, gaps stay visible, and conclusions earn their place.
+4. Just ask your question. Ordinary Q&A runs as usual; once a goal is set and judgements are registered, the system enters knowledge mode by itself: what is already known comes to you, and conclusions earn their place through evidence. Only decisions only you can make are put to you.
 
 <picture>
-  <img src="docs/shots/zh/jepa-ontology.png" alt="The knowledge graph in ClearAI mode" width="820">
+  <img src="docs/shots/en/jepa-ontology.png" alt="The Ontology pane in ClearAI mode" width="820">
 </picture>
 
-*The ontology graph in ClearAI mode — this real session grew 21 concepts and 9 predicates; the same ledger always yields the same picture. (UI shown is Chinese.)*
+*The Ontology pane after the [JEPA world model](docs/cases/jepa-world-model.md) session: the question, the progress rail, the graph, and the conclusions grouped by status.*
 
 If pnpm is not on PATH: `npm install -g pnpm` (do not `corepack enable` — it installs a version forwarder that may download a pnpm it cannot launch).
 
 From the repository:
 
 ```bash
-npm test                       # 18 suites
+npm test                       # 17 suites
 node tools/build-package.mjs   # assemble dist/ from source
 node tools/verify-package.mjs  # rebuild on the spot, byte-compare
 node docs/diagrams/build-hero.mjs   # redraw the product hero (needs google-chrome)
@@ -148,35 +148,36 @@ node docs/diagrams/build-hero.mjs   # redraw the product hero (needs google-chro
 
 ## What it looks like
 
-The middle column has two switchable views: **Deliverables** and **Ontology**. The right sidebar: **Worldlines** and **External Brain**.
+One pane in the middle: **Ontology**. One pane on the right: **World Tree**. Next to the input box: "to handle N".
 
-**Ontology** — this view is your knowledge home. At the top, a **graph band**: the ontology graph (what your domain looks like) and the entity graph (what you have actually verified) toggle with one click; clicking a node or edge opens the **knowledge inspector** (definition / relations / assertions / evidence chain / history), and "filter by this" is an explicit action inside the detail view. Below that, the **ontology shelf**: established entries, each with assertion chips (click to see what the term means), boundary, and support level; contradictions surface automatically. The vocabulary maintenance block sits collapsed at the bottom — it auto-expands when a language exists before any sentence does.
+**Ontology** — one page for your four questions. At the top: the question, one line of counts, anything you need to handle ("to handle"), and a small progress rail: judgment → test → verified → in ontology. In the middle, the **graph**: the ontology graph (what your domain looks like) and the entity graph (the concrete things found) toggle with one click, and clicking a node filters by it. Below, the **conclusion list**, one line each, grouped by status: verified, awaiting check, testing, uncertain, refuted, replaced; open one to see which station it reached, how its trust changed, and its basis and scope. Two contradictory conclusions light up; retracting or keeping is your call.
 
-<picture>
-  <img src="docs/shots/zh/jepa-band.png" alt="The graph band: ontology graph and entity graph" width="820">
-</picture>
+**World Tree** — the plan's steps and gates, one line per step; open one to see which judgments it tested and what came out.
 
-*The band — the ontology graph and the entity graph share one deterministic projection, so the same ledger always yields the same picture (captured from a real session: 21 concepts, 9 predicates).*
+**Deliverables** — at close, the artefacts accepted for each step appear as DSH's native deliverable cards; what changed each turn is in DSH's native change cards.
+
+**Language** — everything the system writes (tool results, the runtime card, questions to you, the files under `clear/`) follows the language you write in, Chinese or English. The panel follows the UI language.
 
 <picture>
-  <img src="docs/shots/zh/jepa-inspector.png" alt="Knowledge inspector: definition, relations, assertions, evidence chain" width="820">
+  <img src="docs/shots/en/jepa-ontology-graph.png" alt="The ontology graph, full screen" width="820">
 </picture>
 
-*Open any node or edge: definition, relations, assertions, evidence chain, registration and revision history, all in one place. (UI shown is Chinese.)*
-
-**Worldlines** — when two routes genuinely disagree, they run as separate branches with their own readings; the losing one stays on record, and adoption is a human press.
+*The ontology graph, full screen. The ontology graph and the entity graph come from one deterministic projection of the files under `clear/ontology/`, so the same files always give the same picture.*
 
-**Deliverables** — the middle column keeps "what the plan declared" and "what actually exists on disk" apart.
+<picture>
+  <img src="docs/shots/en/ns-refuted.png" alt="A refuted judgment, expanded" width="820">
+</picture>
 
-**External Brain** — skills and memory as DSH-native entries in one merged catalogue.
+*A refuted judgment from the [Navier–Stokes](docs/cases/navier-stokes.md) session: it stopped at the test stage, and the record keeps why.*
 
 ---
 
 ## Cases
 
-- [Physical-world process experiment](docs/cases/physical-experiment.md) — sensor thermal drift: the full chain from raising terms to a conflict surfacing
-- [AI for Science](docs/cases/ai4sci.md) — convergence order of WENO reconstructions, and what "we could not resolve it" honestly means
-- [Mathematics](docs/cases/mathematics.md) — keeping finite numerical evidence strictly separate from proof
+Both are real-model sessions run end to end without asking anything; the screenshots replay them in real DSH.
+
+- [JEPA world models](docs/cases/jepa-world-model.md): a literature review, a toy experiment judged by an independent evaluator, and an ontology of 21 concepts, 8 relations and 27 entities
+- [Was Navier–Stokes solved?](docs/cases/navier-stokes.md): two popular claims refuted and kept, an intake rejection handled honestly, and an ontology of 24 concepts, 13 relations and 59 entities
 
 ---
 
@@ -185,8 +186,7 @@ The middle column has two switchable views: **Deliverables** and **Ontology**. T
 - [Positioning](docs/positioning.md) · [Domain ontology design](docs/domain-ontology.md)
 - [Epistemic loop](docs/epistemic-loop.md) · [Verification ontology](docs/verification-loop.md) · [Loop philosophy](docs/loop-philosophy.md)
 - [Design principles](docs/design-principles.md) · [Soul map](docs/soul-map.md) · [Glossary](docs/glossary.md)
-- [Knowledge-native loop ledger](docs/optimization/knowledge-native-loop.zh-CN.md) (this round: triage / preflight / knowledge gate / graph / inspector; zh-CN)
-- [Development plan](docs/optimization/domain-ontology-plan.md) (with real-run evidence from the Hengtong project)
+- [Mechanism truth table](docs/optimization/truth-table.md) · [State machines](docs/optimization/state-machines.md) · [Timing diagrams](docs/optimization/timing-diagrams.md)
 - [Known gaps](docs/known-gaps.md) · [Authority map](docs/authority-map.md) · [Release verification](docs/release-verification.md)
 
 ## Where it sits in DSH

package/README.zh-CN.md

@@ -16,14 +16,14 @@
 ClearAI 是一个**本体发现与探索平台**，核心由两个概念支撑：
 
 - **领域本体**（你得到什么）——项目自己的词汇、经循环确立的知识条目、以及它们的图。研究结束时你拿到一个持续生长的知识结构，下一轮按概念检索。
-- **认识论循环**（你怎么得到它）——七个阶段的纪律化路径：界定、假设、规划、观测、验证、评估、记录。每条边都要经过证据与独立评估的检验。
+- **认识论循环**（你怎么得到它）——问题 → 判断（写明怎样算错）→ 一次可能失败的检验 → 证据 → 带范围的结论 → 长进本体。每条边都要经过证据与独立评估的检验。
 
 > 别的知识图谱靠抽取与断言堆边；这里的每一条边都要通过循环挣得。
 
 ```bash
 # 安装（npm 包，预构建——无需构建步骤，不会触发 allowBuilds 授权）
-dsh plugin --profile web add clearai-dsh@0.3.1
-# 或在应用里：侧栏「插件」→ 添加插件 → clearai-dsh@0.3.1
+dsh plugin --profile web add clearai-dsh@0.5.0
+# 或在应用里：侧栏「插件」→ 添加插件 → clearai-dsh@0.5.0
 ```
 
 重启 `dsh web`，在新建会话顶部的模式选择器里选 **ClearAI** 即可。这就是全部步骤。[完整安装说明 ↓](#安装与使用)
@@ -34,7 +34,7 @@ dsh plugin --profile web add clearai-dsh@0.3.1
   <img src="docs/diagrams/ontology-hero.zh-CN.png" alt="认识论循环（左）长出领域本体（右）" width="1200">
 </picture>
 
-*左：认识论循环——七阶段。绿点是它落定的事实，也是右侧领域本体的第一个节点。右：本体图——深墨是概念，浅墨是值形态，emerald 是实例；实例上挂着两条互相矛盾的断言——**那两个取值染成 amber**，就是「这两条读数对不上」。系统只报出冲突，撤回或维持由人决定。*
+*左：认识论循环。绿点是它落定的事实，也是右侧领域本体的第一个节点。右：本体图——深墨是概念，浅墨是值形态，emerald 是实例；实例上挂着两条互相矛盾的断言——**那两个取值染成 amber**，就是「这两条读数对不上」。系统只报出冲突，撤回或维持由人决定。*
 
 ---
 
@@ -66,7 +66,7 @@ dsh plugin --profile web add clearai-dsh@0.3.1
 
 *环内是这台仪器的读数面：横轴是 L0–L4 七个等级，那条虚线是**事先登记进判据**的阈值；五个观测各带误差棒——被支持的填实、无法判定的画虚圈、被推翻的留在原位打一道斜杠（什么都不删）。开口处那颗 emerald 是唯一越过判据、落定成事实的读数。*
 
-运行时，七个阶段压缩为四拍——计划、执行、观察、反思。状态从会话记录派生，没有第二份存储；模型的工具里没有可以宣告某一步完成的字段。
+状态从会话记录派生，没有第二份存储；模型的工具里没有可以宣告某一步完成的字段，目标也只能在独立评估通过后完成。ClearAI 只做宿主做不了的那部分——认识论契约、领域本体、呈现；目标续跑、子代理、问人、交付卡片、文件历史都用 DSH 原生的。
 
 ClearAI **不**声称递归自我改进。它提供的是自我改进系统所需要的认识论底座。详见[定位](docs/positioning.zh-CN.md)与[OpenRSI 调研](docs/research-openrsi.md)。
 
@@ -74,16 +74,16 @@ ClearAI **不**声称递归自我改进。它提供的是自我改进系统所
 
 ## 安装与使用
 
-**要求：** DSH ≥ `0.1.7-alpha.1`——预设靠的是那一代引入的组合声明行。已在宿主的 `0.1.7-rc.2` 与 `0.2.0-rc.1` 上验过。
+**要求：** DSH ≥ `0.2.0-rc.2`（当前的 `latest`）。预设靠组合里的声明行注册，宿主的预设名册只认这一种。已在宿主的 `0.2.0-rc.2` 上验过，`0.2.1-alpha.1` 也核过。`0.2.0` 以前的宿主不再支持。
 
 **推荐——在应用里装，并把版本钉住：**
 
-侧栏打开**「插件」→ 添加插件**，填 `clearai-dsh@0.3.1`，安装。这就是 DSH 自己的插件管理器：它把你填的东西交给 pnpm，校验这个包声明了组合包、与当前宿主兼容，然后当场生效。（设置里的**插件列表**是**只读清单**；安装入口在侧栏那个「插件」页。）
+侧栏打开**「插件」→ 添加插件**，填 `clearai-dsh@0.5.0`，安装。这就是 DSH 自己的插件管理器：它把你填的东西交给 pnpm，校验这个包声明了组合包、与当前宿主兼容，然后当场生效。（设置里的**插件列表**是**只读清单**；安装入口在侧栏那个「插件」页。）
 
 **或者开终端——同一次安装：**
 
 ```bash
-dsh plugin --profile web add clearai-dsh@0.3.1
+dsh plugin --profile web add clearai-dsh@0.5.0
 ```
 
 从 npm registry 装预构建产物。本机不跑任何编译，因此不需要批准 `allowBuilds` 授权——命令返回时插件就已经可用。
@@ -116,7 +116,7 @@ dsh plugin --profile web add github:Clearailhc/clearai-dsh
 
 Git 拉的是源码而不是构建产物，所以 pnpm ≥10 会拒绝运行 `prepare` 脚本，直到你在该 profile 的 `pnpm-workspace.yaml` 里加上 `allowBuilds` 条目。那条授权的含义是**允许该包代码在安装时于你机器上执行**——只在你读过源码后再授权，并且固定 commit。如果你只是想用 ClearAI，请用上面的 npm 安装。
 
-安装侧的输出**跟系统语言走**（`--lang zh|en` 可覆盖；`doctor` / `seed` / `unseed` 同样认这个开关）。运行时依赖只有 `zod`——图谱那套栈在构建期就打进客户端了。
+安装侧的输出**跟系统语言走**（`--lang zh|en` 可覆盖；`doctor` 同样认这个开关）。运行时依赖只有 `zod`——图谱那套栈在构建期就打进客户端了。
 
 
 装完重启 `dsh web`（`npx @deepseek-ai/dsh web`），然后**新建会话，在顶部的模式选择器里切换到 `ClearAI`**：
@@ -124,20 +124,20 @@ Git 拉的是源码而不是构建产物，所以 pnpm ≥10 会拒绝运行 `pr
 1. 打开 `dsh web`，点「新建会话」；
 2. 点顶部当前的模式名（默认是「标准模式」），展开预设列表；
 3. 选 **ClearAI**——卡片描述就一句:「利用认识论循环构建可信本体。Build a trustworthy ontology through the epistemic loop.」；
-4. 像平常一样提问。普通问答照常走；一旦你立了目标并登记假设，系统自动进入知识模式：预检把已知送上来，缺口如实读出来，结论过证据才准入。
+4. 像平常一样提问。普通问答照常走；一旦立了目标、登记了判断，系统自动进入知识模式：已知送上来，结论过证据才准入。只有你能做的决定才会来问你。
 
 <picture>
-  <img src="docs/shots/zh/jepa-ontology.png" alt="ClearAI 模式下的知识图谱" width="820">
+  <img src="docs/shots/zh/jepa-ontology.png" alt="ClearAI 模式下的「本体」一格" width="820">
 </picture>
 
-*ClearAI 模式下的本体图——这场真实会话长出 21 个概念、9 条谓词；同一份账本永远得到同一张图。*
+*[JEPA 世界模型](docs/cases/jepa-world-model.zh-CN.md)那场会话之后的「本体」一格：问题、进度轨、图，以及按状态分组的结论。*
 
 如果 PATH 上没有 pnpm：`npm install -g pnpm`（别用 `corepack enable`——它装的是版本转发器，可能下载一个自己启动不了的 pnpm）。
 
 从仓库开发：
 
 ```bash
-npm test                       # 18 份套件
+npm test                       # 17 份套件
 node tools/build-package.mjs   # 由源装配 dist/
 node tools/verify-package.mjs  # 现场重建并逐字节比对
 node docs/diagrams/build-hero.mjs   # 重画产品主图(需 google-chrome)
@@ -149,35 +149,36 @@ node docs/diagrams/build-hero.mjs   # 重画产品主图(需 google-chrome)
 
 ## 它长什么样
 
-中栏两格可切：**产物**与**本体**。右栏：**世界树**与**外脑**。
+中栏一格：**本体**。右栏一格：**世界树**。输入框旁边是「待处理 N」。
 
-**本体**——这一格是你的知识主场。顶部是**图带**：本体图（你的领域长什么样）与实体图（已经验证出了什么）一键切换；点节点或边打开**知识 Inspector**（定义 / 关系 / 断言 / 证据链 / 历史），「按此过滤」是详情里的显式动作。下面是**本体货架**：已确立的条目，每条带断言芯片（点开看这个词什么意思）、边界与等级；互相矛盾的自动亮出来。词汇维护区收在最底下——语言先于句子时它自动展开。
+**本体**——一页回答你的四个问题。最上面一行问题、一行计数、要你处理的事（「待处理」），和一条小进度轨：判断 → 检验 → 已验证 → 入本体。中间是**图**：本体图（你的领域长什么样）与实体图（找到了哪些具体东西）一键切换，点节点即按它过滤。下面是**结论清单**，一条一行，按状态分组：已验证、待核验、验证中、不确定、已推翻、已替换；点开一条看它走到了哪一站、可信度怎么变过来的、依据与范围。互相矛盾的两条会亮出来，撤回或维持由你决定。
 
-<picture>
-  <img src="docs/shots/zh/jepa-band.png" alt="本体图带：本体图与实体图切换" width="820">
-</picture>
+**世界树**——计划的步骤与门，每步一行，点开看它检验了哪条判断、结果是什么。
 
-*图带——本体图与实体图共用同一份确定性投影，同一份账本永远得到同一张图；素材来自一场真实会话（21 概念 · 9 谓词）。*
+**交付**——结案时，各步收下的产物以 DSH 原生交付卡片出现；每轮改了哪些文件，看 DSH 原生的改动卡片。
+
+**语言**——系统自己写的话（工具结果、运行态卡、问你的话、`clear/` 下的文件）都跟着你说话的语言走，中文或英文。面板跟着界面语言。
 
 <picture>
-  <img src="docs/shots/zh/jepa-inspector.png" alt="知识 Inspector：定义、关系、断言、证据链" width="820">
+  <img src="docs/shots/zh/jepa-ontology-graph.png" alt="本体图全屏" width="820">
 </picture>
 
-*点开任一节点或边：定义、关系、断言、证据链、登记与修订史，一处读完。*
-
-**世界树**——两条路线真的分歧时，各自独立跑、各自带读数；落选的那条留在记录里，采纳是人按的那一下。
+*本体图全屏。本体图与实体图来自 `clear/ontology/` 下文件的同一份确定性投影，同样的文件永远得到同一张图。*
 
-**产物**——中栏把「计划声明交付的」与「盘上真有的」分开摆，不许混为一谈。
+<picture>
+  <img src="docs/shots/zh/ns-refuted.png" alt="展开一条被推翻的判断" width="820">
+</picture>
 
-**外脑**——技能与记忆以 DSH 原生条目的形式出现在同一张合并目录里。
+*[Navier–Stokes](docs/cases/navier-stokes.zh-CN.md) 那场会话里一条被推翻的判断：它停在检验这一站，记录留着原因。*
 
 ---
 
 ## 案例
 
-- [物理世界工艺实验](docs/cases/physical-experiment.zh-CN.md)——传感器热漂移：从立词到冲突现形的完整链路
-- [AI for Science](docs/cases/ai4sci.zh-CN.md)——WENO 重构的收敛阶，以及「分辨不出来」意味着什么
-- [数学探索](docs/cases/mathematics.zh-CN.md)——把有限数值证据与形式证明严格分开
+两个都是真模型从头跑到尾、中途没问人的会话；截图是在真 DSH 里回放它们拍的。
+
+- [JEPA 世界模型](docs/cases/jepa-world-model.zh-CN.md)：文献综述、交给独立评估者判的玩具实验，以及 21 个概念、8 种关系、27 个实体的本体
+- [Navier–Stokes 被解决了吗？](docs/cases/navier-stokes.zh-CN.md)：两条流行说法被推翻并保留，一次准入被拦后如实处理，以及 24 个概念、13 种关系、59 个实体的本体
 
 ---
 
@@ -186,8 +187,7 @@ node docs/diagrams/build-hero.mjs   # 重画产品主图(需 google-chrome)
 - [定位](docs/positioning.zh-CN.md) · [领域本体设计](docs/domain-ontology.zh-CN.md)
 - [认识论循环](docs/epistemic-loop.zh-CN.md) · [验证本体](docs/verification-loop.zh-CN.md) · [循环哲学](docs/loop-philosophy.zh-CN.md)
 - [设计原则](docs/design-principles.zh-CN.md) · [灵魂映射](docs/soul-map.zh-CN.md) · [术语表](docs/glossary.zh-CN.md)
-- [知识原生循环执行账本](docs/optimization/knowledge-native-loop.zh-CN.md)（本轮：分诊 / 预检 / 知识门 / 图 / Inspector）
-- [开发计划](docs/optimization/domain-ontology-plan.zh-CN.md)（含亨通真跑读数）
+- [机制真值表](docs/optimization/truth-table.zh-CN.md) · [状态机](docs/optimization/state-machines.zh-CN.md) · [时序图](docs/optimization/timing-diagrams.zh-CN.md)
 - [已知缺口](docs/known-gaps.zh-CN.md) · [权威归属](docs/authority-map.zh-CN.md) · [发布验收](docs/release-verification.zh-CN.md)
 
 ## 它落在 DSH 的哪一层