clearai-dsh 0.3.0 → 0.4.0

package/presets/clearai/skills/clearai-loop/SKILL.md

@@ -1,92 +1,106 @@
 ---
 name: clearai-loop
-description: Use when working inside the ClearAI preset and you need the loop's contract rather than its prompt — how a claim becomes a fact (hypothesis → verification → observation → evaluation → evidence → fact), which tool is the only completion verb, what observation admission does and does not decide, who may write a verdict at each level (L0–L4), what "doer does not judge themselves" costs you, and what happens when a step fails admission. Load it before planning multi-step work, before declaring anything finished, or when a step keeps getting blocked.
+description: Use when working inside the ClearAI preset and a delivery keeps getting rejected, a plan is blocked, an ontology file write is refused or flagged, or you need to read an evaluator's verdict card — what admission checks, what to do after a rejection, how the two-part verdict is read, and how the ontology files are checked.
 ---
 
-# ClearAI 循环契约
+# ClearAI 循环:被拦了怎么办
 
-这份技能是**机制的手册**,不是劝告。它描述的每条规则都已经在 `clearai-kernel` 里强制执行:你读它,是为了知道系统会替你做什么、以及你能做什么。
+循环本身写在提示词的「循环」一段,每个工具的用法写在工具说明里。这份技能只讲那两处没写的:准入核什么、被拦之后怎么走、评估卡怎么读、本体文件怎么被检查。这里的每条规则都由 `clearai-kernel` 执行,不是劝告。
 
-## 术语与状态
+## 准入只回答「收不收」
 
-九个对象是:目标 → 计划 → 命题 → 验证 → 观测 → 评估 → 证据 → 事实 → 世界线(等级 L0–L4 只决定**谁可以写裁决**与是否需要人放行)。状态不存,全部由台账现算;本技能描述的规则就是当前契约的全部。
+`AdvancePlan` 交付时,系统按这个次序核对:
 
-## 知识模式的启动协议(不等用户提醒)
+1. 声明的产物**存在**吗?不存在就拒,出路三条:把它做出来、改声明、或用 `RevisePlan(action="void")` 带因作废这一步。
+2. 声明的是**目录**吗?目录不是物证,改为声明具体文件。零字节文件同样拒:空文件不是观测。
+3. **结构合法**吗?`.json` 要能解析;`.md` 去掉标题行后不足 20 个字算「只有标题」。别的扩展名不做结构判定。
+4. 一个产物都没声明 → `no_anchor`:不改变世界的步骤没有可验收的东西。
+5. 都过了且判据非空 → 不是放行,而是送评(L3 以上派独立评估者;L0–L2 用你给的 `basis` 与 `results`)。
 
-目标一立、命题一登记,系统就把**知识预检**送进运行态卡:当前主张文本命中的概念 / 谓词 / 可复用事实。按这个顺序走:
+准入不看判据里的任何断言:数值、口径、一致性都不看。`touch` 一个文件也能过准入,所以过了准入绝不等于这一步做完了。
 
-| 情况 | 动作 |
-|---|---|
-| 命中的词条能表达 | 直接用 id 引用,不重复登记 |
-| 要写断言但谓词不存在 | `RegisterTerm` / `RegisterPredicate` 立最小一组(每个带依据) |
-| 核心假设准备登记 | `SetGoal` 里连 `assertions` 一起写 |
-| 预检摘要不够精确 | `QueryKnowledge` 按概念 / 谓词 / 主体精确取 |
-| 只出现一次且不需要比较 | 保留 claim,不造词 |
-| 单步、一次性、无复用 | 不建本体(普通任务连知识模式都不进) |
+## 被拦之后
 
-**别为了让门放行而编词**:词汇是约定,它将长期约束这个项目怎么写结论。确实不值得留下形态的结论,如实 `CloseGoal(outcome="abandoned")`。
+- **准入拒了**:按返回的缺口改产物或改声明再交。判据本身写错了,用 `RevisePlan(action="refine")` 改,旧判据留在账上。
+- **评估者说交付不成立**:读它的 `shortfalls`(哪条判据、看到了什么、还缺什么),补齐再交。不要换个说法重交同一份东西。
+- **同一步连拦到阈值**:计划置为 blocked,系统当场问人是按缺口再改还是作废这一步;没人能答就停下等人。别硬试下一次。
+- **在 L3 以上带了 `results`**:被拒(`verdict_not_accepted`),去掉 `results` 重交,系统会派评估者。
 
-## 一句话
+## 评估卡怎么读
 
-**让模型负责智能判断,让系统负责事实边界。** 你负责理解材料、提出假设、选择路线、判断哪条证据更可信。系统负责什么算完成、状态是什么、一个事实能不能写进知识库、谁的裁决有效。
+一张卡两项裁决,各管各的:
 
-推论很硬:**凡是被存储的状态都是潜在的谎言**,所以状态不存,全部由台账现算。你不能声明进度、不能声明阶段、不能声明假设成立——你只能交付。
+| 项 | 回答什么 | 取值 |
+|---|---|---|
+| `holds` | 交付成立吗:判据逐条满足、观测真实 | yes / no / unclear |
+| `results` | 这一步检验的每条判断,对照推翻条件读出了什么 | support / refute / inconclusive |
 
-## 四拍与唯一的完成动词
+`holds=yes` 这一步就完成,不管 `results` 是支持、推翻还是说不清。推翻和说不清照样记成证据,判断的状态由证据算。评估卡写不进来时裁决降级为 `unknown`,这一步不推进,绝不静默放行。
 
-| 拍 | 你做什么 | 系统做什么 |
-|---|---|---|
-| 计划 | `CreatePlan`:每步写 `do`、`artifacts`(以何物为证)、`done_criteria`(判定标准) | 强制判据非空、自指检测、≤25 步、步骤 id 唯一 |
-| 执行 | 用文件、bash、公网做实际工作;产物落盘 | 只读并行 / 写入串行;沙箱;每次写入进账 |
-| 观察 | 拿到结果 | 登记观测(只追加) |
-| 反思 | `AdvancePlan` 交付 | 观测准入 → 裁决 → 写证据 → 推进 |
+评估卡、证据、事实由系统落盘;`clear/evidence`、`clear/knowledge/facts`、`clear/goals` 你都写不了。重评产生新证据,旧证据不改不删。
+
+## 本体文件被拒或被标出来
+
+本体文件(`clear/ontology/{concepts,relations,entities}/**.json`)查三道:
 
-`AdvancePlan` 是**唯一**能推进循环的动词。另外三个动词明确不动进度,并在返回值里告诉你 `progress_changed: false`:
+1. **写入时只查这一个文件**:JSON 能解析、字段齐且类型对、`id` 等于文件名、取值合法。不过这次写入就被拒,原因原样回给你;照 `clear/ontology/SCHEMA.json` 改好再写。引用的东西在不在这时不查,所以先写实体、后补它的概念也可以。用 bash 写进来的文件跳过这一道,但躲不过下一道。
+2. **读取时查跨文件**:引用的 id 存在、id 不重复、主语和宾语的类型对得上(下位概念也算)、单值关系只有一个取值。有问题的节点或关系不进图,卡上「本体文件有 N 处问题」逐条列出;它只提示,不拦你干活。
+3. **升格时把断言涉及的本体全查一遍**:结案通过时,判断里的断言用到的关系、类型、主体此刻都要成立;不成立这条判断就不写进长期知识,回执里写明卡在哪。
 
-- `AmendPlan` —— 补一步(漏了活)。
-- `RefinePlan` —— 改判定标准(不改进度;旧判据留痕)。
-- `VoidPlanStep` —— 带因作废(作废留痕光明正大;为凑完成而造证是大忌)。
+卡上某条事实标「定义已变」:它升格时用到的某个概念或关系后来改了含义(释义、上位、主语域、宾语域、单值性)。看一眼它还成不成立:不成立就在新目标里把它当待检验的判断重新检验;改名、改别名不会触发这个标记。
 
-## 观测准入:它只回答「收不收」
+## 结案之后
+
+结案成功、而这次摸出了一套以后还会用的做法(怎么查、怎么算、怎么验),把它写成原生技能:`.agents/skills/<名字>/SKILL.md`,开头的 `description` 写清什么时候用。下次宿主会把它列出来。只做了一次、不会再用的,不写。
+
+---
 
-交付时系统按这个次序检查（以当前 ClearAI DSH 内核的准入契约为准）：
+# The ClearAI loop: what to do when blocked (English)
 
-1. 声明的产物**存在**吗?不存在 → 硬拦 `l1`,并告诉你三条合法出路(做出来 / 改声明 / 带因作废)。
-2. 存在但是**空**吗?空目录、零字节文件 → 同样硬拦:空文件不是观测。
-3. **结构合法**吗?`.json` 必须能解析;`.md` 去掉标题行后实质文本不足 20 字符算「仅有标题」。其他扩展名不做结构判定(不误伤)。
-4. 一个坐标都没声明 → `no_anchor` 硬拦:不改变世界的步骤没有可验收的东西。
-5. 坐标齐备且判据非空 → **不是放行,是送评**(`needs_audit`)。
+The loop itself is in the "loop" section of the prompt, and each tool's usage is in its own description. This skill covers only what those leave out: what intake checks, how to proceed after a rejection, how to read an evaluator's card, and how ontology files are checked. Every rule here is enforced by `clearai-kernel`; none of it is advice.
 
-准入**不判**判据里的任何断言:数值、口径、一致性都不看。坐标齐备只是必要条件——`touch` 一个文件也能让坐标齐备,所以齐备绝不等于这一步做完了。判据里的断言由评估者逐条核对。
+## Intake only answers "accept or not"
 
-连续 3 次未过闸,计划会被置为 `blocked` 并停下等人。别硬试第四次:改产物、改判据,或者把这一步作废。
+When you deliver with `AdvancePlan`, the system checks in this order:
 
-## 谁可以写裁决
+1. Do the declared outputs **exist**? If not, it refuses, with three ways out: produce them, change the declaration, or void the step with a reason via `RevisePlan(action="void")`.
+2. Is a declared output a **directory**? A directory is not proof; declare concrete files. Zero-byte files are refused too: an empty file is not an observation.
+3. Is the **structure valid**? `.json` must parse; a `.md` with fewer than 20 characters after removing the title line counts as "title only". Other extensions get no structural check.
+4. No output declared at all → `no_anchor`: a step that changes nothing has nothing to accept.
+5. All passed and the criteria are non-empty → this is not approval but referral (an independent evaluator from L3 up; your `basis` and `results` at L0–L2).
 
-| 等级 | 定义 | 谁判 |
+Intake does not look at any assertion in the criteria: values, definitions and consistency are not checked. `touch` on a file passes intake, so passing intake never means the step is done.
+
+## After a rejection
+
+- **Intake refused**: fix the output or the declaration according to the reported gap, then deliver again. If the criterion itself is wrong, change it with `RevisePlan(action="refine")`; the old one stays in the ledger.
+- **The evaluator says the delivery does not hold**: read its `shortfalls` (which criterion, what it saw, what is missing), fill the gaps, then deliver again. Do not hand in the same thing reworded.
+- **The same step blocked up to the threshold**: the plan is marked blocked and the system asks a person right there whether to revise against the gaps or void the step; if nobody can answer, it stops and waits. Do not force another attempt.
+- **`results` given at L3 or above**: refused (`verdict_not_accepted`). Deliver again without `results`, and the system dispatches an evaluator.
+
+## Reading an evaluator's card
+
+One card carries two verdicts, each answering its own question:
+
+| Item | Answers | Values |
 |---|---|---|
-| L0 | 只靠推理的快速合理性检查 | 你自己(`verdict` + `basis`,依据必须可复查) |
-| L1 | 已有知识:文献、数据库是否已回答 | 你自己 |
-| L2 | 已有数据或小规模计算 | 你自己 |
-| L3 | 新产生的、可重复的证据 | **独立评估者**(系统派,fresh context,只读产物) |
-| L4 | 新产生的、不可重复或来自外部的证据 | **独立评估者**,并且没有人放行不能开始;做的人自己写的文件不算观测 |
+| `holds` | Does the delivery hold: every criterion met, observations real | yes / no / unclear |
+| `results` | For each judgment the step tests, what the observation shows against its refutation condition | support / refute / inconclusive |
+
+With `holds=yes` the step is complete, whatever `results` says. Refute and inconclusive are recorded as evidence all the same, and the judgment's status is computed from the evidence. If the card cannot be written, the verdict degrades to `unknown` and the step does not advance; it is never silently let through.
 
-在 L3 以上交付时带上 `verdict` 会被直接拒绝(`verdict_not_accepted`):做的人不判自己。这不是建议——去掉 `verdict` 重新交付,系统会派评估者,你拿回的是评估卡上的裁决。
+The system writes evaluator cards, evidence and facts; you cannot write `clear/evidence`, `clear/knowledge/facts` or `clear/goals`. A re-evaluation adds new evidence; old evidence is never changed or deleted.
 
-评估者只核对、不发挥、不执行,产出结构化评估卡;卡由系统落盘(写不进卡时裁决降级 `unknown`,这一步就不推进,绝不静默放行)。你也不能写 `clear/evidence`、`clear/knowledge/facts`、`clear/goals` 里的任何文件——那些是系统所有的面。
+## When an ontology file is refused or flagged
 
-## 目标:跨计划的一等对象
+Ontology files (`clear/ontology/{concepts,relations,entities}/**.json`) go through three checks:
 
-目标带着一份「怎样算回答了」的判据(`done_criteria`)和候选假设。每条假设必须有**推翻条件**:没有推翻条件的假设无法被检验。
+1. **On write, only this file is checked**: the JSON parses, fields are present with the right types, `id` equals the file name, values are legal. If it fails, the write is refused and the reason comes back verbatim; fix it according to `clear/ontology/SCHEMA.json` and write again. Whether referenced things exist is not checked here, so you can write an entity first and its concept later. Files written through bash skip this check but not the next one.
+2. **On read, across files**: referenced ids exist, ids are unique, subject and object types fit (narrower concepts count), single-valued relations have one value. Nodes or relations with problems stay off the graph, and the card lists them under "ontology files have N problems"; this only warns, it does not stop your work.
+3. **On promotion, every part of the ontology an assertion uses is checked**: when a conclusion passes, the relations, types and subjects used by a judgment's assertions must all hold at that moment; if not, that judgment is not written to long-term knowledge, and the receipt says where it is stuck.
 
-- `SetGoal` 修订必须带 `reason`,版本 +1,旧值全部留痕;同一时间只开一个目标。
-- 一张 Plan 只承载目标的一个阶段。`ClosePlan` 之后目标若未达成,继续 `CreatePlan` 开下一阶段,不用等人说「继续」。
-- `CloseGoal(outcome="achieved")` 会**无条件**触发一次目标级独立评估:评估者逐条核对判据与转写忠实度,只有它说达成才结案;它说没达成,目标保持开放并把缺口回注给你。
-- 达升格门槛且无推翻的假设,在结案时由系统升格为事实,写进 `clear/knowledge/facts/`。被推翻的假设留在台账里——一条被推翻的假设是有价值的资产。
+A fact marked "definition changed" on the card: a concept or relation it used at promotion later changed meaning (definition, broader term, subject domain, object range, single-valuedness). Check whether it still holds; if not, test it again as a judgment in a new goal. Renaming or changing aliases does not trigger this mark.
 
-## 证据的形态
+## After concluding
 
-- 假设的状态由证据**算**出来,不打分:支持到第几级、有几条推翻、有几次无法判定。你读到的是派生结果。
-- `inconclusive` 是诚实的答案。一次如实推翻假设的步骤照样可以通过验收——不要为了让步骤通过而写 support。
-- 重评产生**新证据**,旧证据不改、不删。
-- 结算单记四列:意图(判据)/ 事实(坐标)/ 评估者 / 差额(依据或缺口)。
+If the conclusion succeeds and the run found a method worth reusing (how to look up, compute or verify), write it as a native skill: `.agents/skills/<name>/SKILL.md`, with a `description` at the top that says when to use it. The host lists it next time. Skip anything done once and never needed again.