@shgroup/dsh-serenity-hooks 1.51.5 → 1.52.0

package/lib/invariant.d.ts

@@ -24,5 +24,9 @@ export declare function verifyToolConsistency(manifestPath: string, registeredTo
  * v1.51（**D104**）：新增 **`diagram`**（标签源码 → 进程内光栅化成 PNG；**缺省关**，
  * 关时连 `ctx.tools.register` 都不调用）⇒ **12**。同规格：开关关着**不影响这里列它** ——
  * 本常量描述的是"插件**具备**的工具面"，不是"此刻注册了几个"。
+ *
+ * v1.52（**D121**，owner 2026-10-11 裁「引擎搬进 ACC」）：新增 **`ontology`** —— 本体工程
+ * **引擎**（原为 CCC 的 MSM `ontology-engineering`，逐字搬迁；见 `src/ontology/engine.ts` 文件头
+ * 的三处改写）。它与 `praxis ontology`（**方法文本**）是**同一领域的两个面**：一个说、一个跑 ⇒ **13**。
  */
-export declare const REGISTERED_TOOLS: readonly ["container_fs", "container_trajectory", "dashboard", "container_git", "msm", "praxis", "handyman", "localstore", "container_admin", "im-bridge", "acc-diag", "diagram"];
+export declare const REGISTERED_TOOLS: readonly ["container_fs", "container_trajectory", "dashboard", "container_git", "msm", "praxis", "handyman", "localstore", "container_admin", "im-bridge", "acc-diag", "diagram", "ontology"];

package/lib/invariant.js

@@ -45,6 +45,10 @@ function verifyToolConsistency(manifestPath, registeredTools) {
 * v1.51（**D104**）：新增 **`diagram`**（标签源码 → 进程内光栅化成 PNG；**缺省关**，
 * 关时连 `ctx.tools.register` 都不调用）⇒ **12**。同规格：开关关着**不影响这里列它** ——
 * 本常量描述的是"插件**具备**的工具面"，不是"此刻注册了几个"。
+*
+* v1.52（**D121**，owner 2026-10-11 裁「引擎搬进 ACC」）：新增 **`ontology`** —— 本体工程
+* **引擎**（原为 CCC 的 MSM `ontology-engineering`，逐字搬迁；见 `src/ontology/engine.ts` 文件头
+* 的三处改写）。它与 `praxis ontology`（**方法文本**）是**同一领域的两个面**：一个说、一个跑 ⇒ **13**。
 */
 const REGISTERED_TOOLS = [
 	"container_fs",
@@ -58,7 +62,8 @@ const REGISTERED_TOOLS = [
 	"container_admin",
 	"im-bridge",
 	"acc-diag",
-	"diagram"
+	"diagram",
+	"ontology"
 ];
 //#endregion
 export { REGISTERED_TOOLS, verifyToolConsistency };

package/lib/ontology/engine.d.ts

@@ -0,0 +1,168 @@
+/**
+ * engine.ts — Ontology Definition, Validation & Semantic Review（ACC 侧引擎）
+ *
+ * 来源：宁静号 CCC 的 MSM `ontology-engineering`
+ *   （原 `.opencode/skills/home-ontology/scripts/ontology-engineering.ts`；
+ *    2026-10-11 owner 裁「搬到 ACC」）。
+ *   搬迁方式 = **复制 ＋ 机械改写**，不是重写 —— 判据群（M1–M10／L1–L5／D1–D8／V1–V4）与
+ *   全部输出文案**逐字保留**，只在"如何被调用/如何吐字"这一层做了三处改写（见下）。
+ *
+ * 本文件是**纯引擎**：只用 node 内建模块，不依赖宿主与 CCC。三段分工：
+ *   · 引擎（本文件）＝ 解析与检查；
+ *   · 工具壳 `src/tools/ontology-eng.ts` ＝ 参数、路径守卫、把结果翻成回执；
+ *   · 方法手册 `src/tools/ontology.ts`（praxis 第四段）＝ 人/模型读的方法论。
+ *
+ * 🔴 搬迁改写清单（相对原 MSM 脚本，行为差异仅此三处）：
+ *   ① **输出不再直写 `process.stdout`** ⇒ 经 `emit()`／`emitErr()` 汇聚。宿主是**长驻进程**，
+ *      工具调用必须**返回文本**（且不能污染服务器自己的 stdout）。
+ *   ② **`main()` ＋ `process.argv` 守卫 ⇒ 导出 `runOntologyCli(argv, opts)`**：**不再 `process.exit`**，
+ *      退出码（0/1/2/4）改为**返回值**，由工具壳翻译成可读回执。
+ *   ③ **运行时工作目录由调用方给**（`opts.cwd` = CCC 根）：引擎多处按相对路径解析
+ *      `.opencode/skills` ⇒ 改用**显式基准目录 `BASE`**（一律 `resolve(BASE, …)`），
+ *      **不用 `process.chdir`** —— chdir 在 **worker 线程里不被支持**
+ *      （`ERR_WORKER_UNSUPPORTED_OPERATION`；vitest 就用 worker 跑），且长驻进程
+ *      改全局 cwd 是隐患。`BASE` 只在本进程内、由 `runOntologyCli` 的 try/finally
+ *      保存与恢复；`resolve(BASE, x)` 对**绝对路径天然无害**（原样返回）⇒ 生产路径
+ *      （工具壳传绝对路径进来）行为不变。
+ *
+ * subcommands（与原脚本逐一对应）：
+ *   init       <path> [--template minimal|full]       写一份 Turtle 模板
+ *   check      <path> [--level normal|strict]         M1–M10 结构检查（strict 另出 L1–L5 提示）
+ *   explain    <path>                                 自然语言摘要
+ *   verify     <path> [--level operational|continuity|full]  V1–V4 运行时合规
+ *   review     <path> [--level semantic|onto-clean|full] [--format prompt|json]  语义审查提示词
+ *   compliance <path> [--skills <dir>] [--format prompt|json]  公理↔skill 合规清单
+ *
+ * 退出码：0 成功 ／ 1 user（参数或校验失败）／ 2 system（文件缺失／解析失败）／ 4 internal
+ * 错误码：PARAMETER_MISSING ／ PARAMETER_INVALID_VALUE ／ ONTO_FILE_NOT_FOUND ／ ONTO_PARSE_ERROR
+ *        ／ ONTO_AXIOM_PARSE_ERROR ／ ONTO_VALIDATION_FAILED ／ INTERNAL_UNHANDLED_STATE
+ */
+type Category = "user" | "system" | "operator" | "internal";
+declare class MsmError extends Error {
+    code: string;
+    category: Category;
+    message: string;
+    context: Record<string, unknown>;
+    remediation?: string | undefined;
+    cause?: unknown | undefined;
+    constructor(code: string, category: Category, message: string, context?: Record<string, unknown>, remediation?: string | undefined, cause?: unknown | undefined);
+    toStderr(): string;
+    exitCode(): number;
+}
+interface PropertyDef {
+    type: string;
+    cardinality?: string;
+    values?: string[];
+}
+interface TypeDef {
+    description?: string;
+    superTypes?: string[];
+    rigidity?: "rigid" | "anti-rigid" | "semi-rigid";
+    identity?: string[];
+    dependsOn?: string[];
+    properties?: Record<string, PropertyDef>;
+    axioms?: string[];
+}
+interface RelationDef {
+    domain?: string;
+    range?: string;
+    cardinality?: string;
+    functional?: boolean;
+    transitive?: boolean;
+    symmetric?: boolean;
+    asymmetric?: boolean;
+    reflexive?: boolean;
+    irreflexive?: boolean;
+}
+interface AxiomDef {
+    description?: string;
+    rule: string;
+    type?: string;
+}
+interface OntologyDefinition {
+    name?: string;
+    version?: string;
+    imports?: string[];
+    types?: Record<string, TypeDef>;
+    relations?: Record<string, RelationDef>;
+    axioms?: AxiomDef[];
+}
+type ExprNode = PropAccessNode | LiteralNode | FuncCallNode | QuantifierNode | BinaryOpNode | UnaryOpNode | ImplicationNode | ParensNode;
+interface PropAccessNode {
+    kind: "propAccess";
+    path: string[];
+    pos: number;
+}
+interface LiteralNode {
+    kind: "literal";
+    value: string | number | boolean | null;
+    raw: string;
+    pos: number;
+}
+interface FuncCallNode {
+    kind: "funcCall";
+    name: string;
+    args: ExprNode[];
+    pos: number;
+}
+interface QuantifierNode {
+    kind: "quantifier";
+    quant: "exists" | "forall";
+    variable: string;
+    typeName: string;
+    body: ExprNode;
+    pos: number;
+}
+interface BinaryOpNode {
+    kind: "binaryOp";
+    op: string;
+    left: ExprNode;
+    right: ExprNode;
+    pos: number;
+}
+interface UnaryOpNode {
+    kind: "unaryOp";
+    op: "not" | "minus";
+    operand: ExprNode;
+    pos: number;
+}
+interface ImplicationNode {
+    kind: "implication";
+    antecedent: ExprNode;
+    consequent: ExprNode;
+    pos: number;
+}
+interface ParensNode {
+    kind: "parens";
+    expr: ExprNode;
+    pos: number;
+}
+interface CheckIssue {
+    check: string;
+    severity: "error" | "warning";
+    message: string;
+}
+declare function validateOnto(onto: OntologyDefinition, level: "normal" | "strict"): CheckIssue[];
+export interface OntologyRunOptions {
+    /** 运行时工作目录（= CCC 根）：引擎多处按相对路径解析 `.opencode/skills` 等。
+     *  ⇒ 落到**解析基准 `BASE`**（改写 ③）；**不做 `process.chdir`**（worker 线程不支持）。 */
+    cwd?: string;
+    /** 顶层 skill 名（缺省 `home-serenity`）：容器级资产（根标记／MSM 注册表／合规扫描）按它定位 */
+    topSkill?: string;
+    /** `sr:` 命名空间（缺省 `http://home-serenity/ontology#`） */
+    namespace?: string;
+}
+export interface OntologyRunResult {
+    /** 退出码：0 成功 ／ 1 user ／ 2 system ／ 4 internal */
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * runOntologyCli —— 同步跑一次引擎调用，**返回**输出与退出码（不打印、不退出）。
+ *
+ * 调用方（工具壳 `src/tools/ontology-eng.ts`）负责：路径守卫（必须落在 CCC 内）、
+ * 以及把 `code !== 0` 翻成响亮的回执（引擎的 stderr 文案**逐字保留**，不重写）。
+ */
+export declare function runOntologyCli(argv: string[], opts?: OntologyRunOptions): OntologyRunResult;
+export { MsmError, validateOnto, type OntologyDefinition, type CheckIssue, type ExprNode };

package/lib/tools/ontology-eng.d.ts

@@ -0,0 +1,14 @@
+export interface OntologyToolResult {
+    ok: boolean;
+    code: number;
+    command: string;
+    /** 容器内相对路径（回执里给相对路径：它是可重建的那一个） */
+    path: string;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * 本体工程引擎（`ontology`）—— 六个子命令：init/check/explain/verify/review/compliance。
+ * 只读的五个不写任何文件；`init` 会在容器内**新建** .ttl 模板。
+ */
+export declare function createOntologyTool(): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/tools/ontology.d.ts

@@ -9,4 +9,4 @@
  *   · 判据群（M/L/D/V）是方法的**标准编号**（与参考实现同源），容器不必有同名引擎也能用；
  *   · **模型语料（.ttl）与具体公理内容属 CCC**，不在本文件。
  */
-export declare const ONTOLOGY_CONTENT = "# Ontology Engineering \u2014 Method Family (\u672C\u4F53\u8BBA\u5DE5\u7A0B\u65B9\u6CD5\u7FA4)\n\n> **Any creative action \u2014 a new concept, a new term, a new skill, a new MSM, a new architectural layer \u2014\n> is preceded by explicitly encoding WHAT EXISTS, HOW THINGS RELATE, and WHAT IS CONSTRAINED.**\n>\n> Without it: idea \u2192 implementation (all \u0394H_in becomes H_op).\n> With it: idea \u2192 structure \u2192 implementation (structure absorbs part of \u0394H_in).\n\n## 1. When to invoke\n\n- introducing a new concept, term, or vocabulary\n- creating a skill, or changing an existing skill's scope/dependencies\n- creating an MSM (Mech or Semi-Mech)\n- introducing a new architectural layer or a cross-domain concept\n- any moment of \"what IS this thing here, and how does it relate to everything else?\"\n\n## 2. Core cognition\n\n**Ontology = before acting, make explicit what exists, how it relates, and what is constrained.**\n\nOntology is one of CCE's `\u0394H_org` operators: it records the *structure* of new content at the moment the\ncontent is produced, so that future agents do not have to reverse-engineer structure out of prose.\nIt is EAP applied at the layer of domain structure:\n\n| EAP demand | How ontology satisfies it |\n|---|---|\n| E\u2191 Explicitness | types / relations / axioms are stated, not implied |\n| R\u2193 Reconstructability | a new agent reads structure directly instead of inferring it |\n| S\u2191 Stability | the `.ttl` file is the single structural source of truth |\n\n**Consequence**: in a container, *every act of creation adds an entity to a domain* \u2014 so updating the\nontology is part of the creative act, not an extra chore.\n\n## 3. Encoding \u2014 Turtle (`.ttl`)\n\nAll models use W3C Turtle. **Why Turtle**: LLMs already carry RDF/OWL/Turtle in their training data, so the\nnotation costs ~zero context to explain.\n\n- **Standard namespaces**: `rdf:`, `rdfs:`, `owl:`, `xsd:`\n- **Container-local namespace**: `sr:` \u2014 a container-chosen URI used for `rigidity`, `identity`,\n  `unity`, `dependence`, `cardinality`, `axiom`, `dependsOn`, \u2026 (the container fixes the URI; the\n  method does not)\n\n**Modelling vocabulary**: *Type* \u00B7 *Relation* (with domain/range) \u00B7 *Axiom* (a named constraint), plus\n**meta-properties** attached to types: rigidity (`+R` rigid / `~R` semi-rigid / `-R` anti-rigid),\nidentity, unity, dependence.\n\n## 4. Judgement set A \u2014 structural validation `M1\u2013M10` (deterministic, machine)\n\nRun after every write; these are decidable from the file alone.\n\n| ID | Check | Catches |\n|---|---|---|\n| **M1** | Referential integrity | a type/relation/type-in-relation is referenced but not defined |\n| **M2** | Taxonomy acyclicity | a cycle in the `subClassOf` graph |\n| **M3** | Rigidity inheritance | a child is **more rigid** than its parent (rigid must not subsume anti-rigid) |\n| **M4** | Identity presence | a **rigid** type carries no identity (own or inherited) |\n| **M5** | Dependency acyclicity | a cycle in the existence-dependency graph |\n| **M6** | Cardinality consistency | malformed or mutually contradictory cardinalities |\n| **M7** | Enum coverage | an enumerated value set is incomplete/inconsistent with its use |\n| **M8** | Axiom syntax | an axiom is not syntactically well-formed |\n| **M9** | Axiom reference check | an axiom references an undefined type/relation |\n| **M10** | Import/file error | an imported `.ttl` is missing or unparsable |\n\n## 5. Judgement set B \u2014 semantic hints `L1\u2013L5` (strict mode; machine emits, model judges)\n\nThese are **questions, not verdicts** \u2014 the engine prints them so an LLM can answer them.\n\n| ID | Hint |\n|---|---|\n| **L1** | type has **no rigidity label** \u2014 should it be rigid or anti-rigid? |\n| **L2** | **missing constraints** \u2014 are temporal / state axioms absent? |\n| **L3** | **identity adequacy** \u2014 is the declared identity sufficient for uniqueness? |\n| **L4** | **type semantics** \u2014 are there missing distinctions between types? |\n| **L5** | **axiom coverage** \u2014 do axioms reference concepts that are not defined as types? |\n\n## 6. Judgement set C \u2014 semantic review `D1\u2013D8` (model, ideally a read-only subagent)\n\nStructure can pass `M*` and still be wrong. `D*` is where an LLM reviews meaning.\n\n| ID | Dimension | Asks |\n|---|---|---|\n| **D1** | Type semantics | are names/descriptions/boundaries clear and correct? split or merge needed? |\n| **D2** | Taxonomy quality | does every `subClassOf` pass the **is-a test**? missing/incorrect links? disjointness? sensible depth (3\u20137 levels typical)? |\n| **D3** | Rigidity audit | is every rigid/anti-rigid/semi-rigid assignment justified? is inheritance consistent? |\n| **D4** | Identity criteria | do identity keys guarantee uniqueness? natural vs surrogate? any identity resting on mutable properties? |\n| **D5** | Relation semantics | real-world interpretation? domain/range correct? property characteristics true? cardinalities physically possible? |\n| **D6** | Axiom completeness & correctness | sound? missing temporal / state / dependency / instance-level cardinality constraints? |\n| **D7** | Domain completeness | what real-world entities are **not** modelled? missing relations? lifecycle/state machines? edge cases? wide/deep enough? |\n| **D8** | OntoClean deep review | the six meta-properties, applied down the whole taxonomy |\n\n**OntoClean's six meta-properties** (the vocabulary `D8` reason with):\n\n| Meta-property | Notation | Question |\n|---|---|---|\n| Identity | `+I` / `-I` | what criterion distinguishes instances of this type? |\n| Unity | `+U` / `~U` / `-U` | can instances form a whole? any anti-unity type (\"pile of sand\")? |\n| Rigidity | `+R` / `~R` / `-R` | is the property essential to every instance, in every context? |\n| Dependence | `+D` / `-D` | does this type's existence necessarily imply another's? |\n| Sortal vs non-sortal | \u2014 | can an identity criterion exist at all? |\n| Backbone taxonomy | \u2014 | does the rigid-only backbone form a consistent tree? |\n\n## 7. Judgement set D \u2014 runtime compliance `V1\u2013V4` (declaration \u2194 reality)\n\nOntology is not only a model of the world \u2014 it also **declares facts about the container itself**, so those\ndeclarations must be checked against the container's actual state.\n\n| ID | Check |\n|---|---|\n| **V1** | declared skill directories exist |\n| **V2** | orphan directories (present on disk, absent from the model) |\n| **V3** | MSM registration consistency (declared ownership \u2194 registry) |\n| **V4** | session health (duplicate goals \u00B7 session count \u00B7 stale sessions) |\n\n## 8. The OEPE loop \u2014 Ontology \u2192 EAP \u2192 Prompt-Enhancement\n\nThe reusable audit cycle. **Do not spend human effort hand-reviewing prose** \u2014 let the ontology be the\nstructural blueprint, let a subagent do semantic review in an isolated context, and let the human only\nconfirm the direction of repair.\n\n```\nO \u2500\u2500 Ontology\n\u2502    \u2460 write the domain .ttl: types + relations + axioms\n\u2502    \u2461 check --level strict         \u2192 0 errors\n\u2502    \u2462 explain                      \u2192 natural-language summary (reasoning context for the next stage)\n\u2502    \u2463 review --level onto-clean    \u2192 structured review prompt (D7 + D8)\n\u2502\n\u251C\u2500\u2500 E \u2500\u2500 EAP audit\n\u2502    \u2464 take the ontology axioms as the TOP constraint; evaluate the target artifact against each\n\u2502    \u2465 EAP scoring (E/R/S) + ambiguous-word scan\n\u2502    \u2466 emit a compliance matrix: PASS / WEAK / VIOLATION\n\u2502\n\u2514\u2500\u2500 PE \u2500\u2500 Prompt-Enhance\n     \u2467 VIOLATION \u2192 repair (P1)\n     \u2468 WEAK \u2192 strengthen (P2)\n     \u2469 PASS \u2192 keep\n     \u246A re-run check \u2192 audit \u2192 until everything is PASS\n```\n\n**Severity classes** used across the review dimensions:\n\n| Class | Meaning |\n|---|---|\n| **P0 Critical** | causes incorrect behaviour, data corruption, or violates a domain law |\n| **P1 High** | makes the ontology misleading, or unable to serve its stated purpose |\n| **P2 Medium** | reduces quality / clarity / reusability |\n| **P3 Low** | minor improvement or style suggestion |\n\n**Typical artifacts**: `<domain>-ontology.ttl` (O) \u00B7 `onto-clean-review.md` (O) \u00B7 `skill-audit-report.md` (E).\n\n## 9. Workflows\n\n**New skill**\n```\n\u2460 what type is this skill? which skills does it depend on? what are its domain entities?\n\u2461 if the domain is complex enough \u2192 build a domain ontology (types / relations / axioms)\n\u2462 write SKILL.md so that its declared dependencies match the axioms\n\u2463 structural check \u2192 0 errors\n\u2464 axiom compliance \u2192 no violation of existing axioms\n```\n\n**New concept / term**\n```\n\u2460 is this a SUBTYPE of an existing type, or a NEW type?\n\u2461 new type \u2192 add a subClassOf to the container-level registry ontology\n\u2462 subtype   \u2192 add a subClassOf to the domain ontology\n\u2463 does it need a new relation or axiom?\n\u2464 structural check \u2192 0 errors\n```\n\n**New MSM**\n```\n\u2460 Mech (deterministic) or Semi-Mech (model in the loop)?\n\u2461 which ONE skill owns it?\n\u2462 consistent with the container's BuiltinTool/MSM type in the architecture ontology?\n\u2463 record it in that skill's ontology entry\n\u2464 register it through the container's registry (never by editing the registry file directly)\n```\n\n## 10. Universal axioms (violating any of these is a defect, not a style choice)\n\n| Axiom | Content | Consequence of violation |\n|---|---|---|\n| Unique name | two skills may not share a name | routing becomes ambiguous |\n| SKILL.md required | every skill has a SKILL.md | agents cannot locate the domain knowledge |\n| Dependency complete | using another skill's tool \u21D2 declare the dependency | implicit coupling surfaces at runtime (H_op\u2191) |\n| MSM ownership | every MSM belongs to exactly one skill | the MSM cannot be indexed |\n| Dependency acyclic | `skillDependsOn` must not form a cycle | load order becomes undefined |\n\n**Axiom discipline**: axioms are named (`AX-*`), individually citable, and each carries a rationale.\nBreaking an axiom is allowed only by stating the break explicitly and recording the reason.\n\n## 11. Dispatching a review subagent\n\nBoth OEPE review stages run in an isolated context. Three rules make them work:\n\n1. **Mandatory opening block** \u2014 the prompt must begin by requiring the subagent to load the ontology\n   method (and EAP, for the audit stage). Without it the subagent does not know the standard it is applying,\n   and its output is worthless.\n2. **Read-only** \u2014 the reviewer never edits files. Review and repair are separated: the reviewer reports,\n   the human confirms direction, the agent repairs.\n3. **Structured output** \u2014 one line per finding: `<ID> [<Severity>] <Finding> \u2014 <Evidence> \u2014 <Suggestion>`,\n   then a summary: top issues \u00B7 health grade (A\u2013F) \u00B7 prioritized repair list. Findings are written to the\n   session directory, never into the skill directory.\n\n## 12. Anti-patterns\n\n| Anti-pattern | Why it is wrong |\n|---|---|\n| modelling **instances** as **types** | the taxonomy inflates and stops carrying meaning |\n| an \"is-a\" relation that fails the **is-a test** in some context | structural checks pass, semantics rot |\n| a rigid type with **no identity** | nothing distinguishes its instances (M4) |\n| identity resting on a **mutable property** | the entity's identity changes as data changes |\n| a child that is **more rigid** than its parent | OntoClean violation (M3) |\n| putting **implementation detail** into the domain ontology | the model then tracks code, not the domain |\n| a second, competing source of truth for structure | E\u2193, and the drift is silent |\n| writing the model **after** the code | structure is reverse-engineered from accidents |\n\n## 13. Relation to the other praxis frameworks\n\n- **EAP** \u2014 how a piece of knowledge should be structured (static quality). Ontology is EAP applied to\n  domain structure.\n- **CCE** \u2014 how structured knowledge keeps evolving without losing coherence (dynamic persistence).\n  Ontology is one of CCE's `\u0394H_org` operators.\n- **Neat** \u2014 the collaboration protocol for the *design conversation* that produces the model.\n";
+export declare const ONTOLOGY_CONTENT = "# Ontology Engineering \u2014 Method Family (\u672C\u4F53\u8BBA\u5DE5\u7A0B\u65B9\u6CD5\u7FA4)\n\n> **Any creative action \u2014 a new concept, a new term, a new skill, a new MSM, a new architectural layer \u2014\n> is preceded by explicitly encoding WHAT EXISTS, HOW THINGS RELATE, and WHAT IS CONSTRAINED.**\n>\n> Without it: idea \u2192 implementation (all \u0394H_in becomes H_op).\n> With it: idea \u2192 structure \u2192 implementation (structure absorbs part of \u0394H_in).\n\n## 1. When to invoke\n\n- introducing a new concept, term, or vocabulary\n- creating a skill, or changing an existing skill's scope/dependencies\n- creating an MSM (Mech or Semi-Mech)\n- introducing a new architectural layer or a cross-domain concept\n- any moment of \"what IS this thing here, and how does it relate to everything else?\"\n\n## 2. Core cognition\n\n**Ontology = before acting, make explicit what exists, how it relates, and what is constrained.**\n\nOntology is one of CCE's `\u0394H_org` operators: it records the *structure* of new content at the moment the\ncontent is produced, so that future agents do not have to reverse-engineer structure out of prose.\nIt is EAP applied at the layer of domain structure:\n\n| EAP demand | How ontology satisfies it |\n|---|---|\n| E\u2191 Explicitness | types / relations / axioms are stated, not implied |\n| R\u2193 Reconstructability | a new agent reads structure directly instead of inferring it |\n| S\u2191 Stability | the `.ttl` file is the single structural source of truth |\n\n**Consequence**: in a container, *every act of creation adds an entity to a domain* \u2014 so updating the\nontology is part of the creative act, not an extra chore.\n\n## 3. Encoding \u2014 Turtle (`.ttl`)\n\nAll models use W3C Turtle. **Why Turtle**: LLMs already carry RDF/OWL/Turtle in their training data, so the\nnotation costs ~zero context to explain.\n\n- **Standard namespaces**: `rdf:`, `rdfs:`, `owl:`, `xsd:`\n- **Container-local namespace**: `sr:` \u2014 a container-chosen URI used for `rigidity`, `identity`,\n  `unity`, `dependence`, `cardinality`, `axiom`, `dependsOn`, \u2026 (the container fixes the URI; the\n  method does not)\n\n**Modelling vocabulary**: *Type* \u00B7 *Relation* (with domain/range) \u00B7 *Axiom* (a named constraint), plus\n**meta-properties** attached to types: rigidity (`+R` rigid / `~R` semi-rigid / `-R` anti-rigid),\nidentity, unity, dependence.\n\n## 4. Judgement set A \u2014 structural validation `M1\u2013M10` (deterministic, machine)\n\nRun after every write; these are decidable from the file alone.\n\n| ID | Check | Catches |\n|---|---|---|\n| **M1** | Referential integrity | a type/relation/type-in-relation is referenced but not defined |\n| **M2** | Taxonomy acyclicity | a cycle in the `subClassOf` graph |\n| **M3** | Rigidity inheritance | a child is **more rigid** than its parent (rigid must not subsume anti-rigid) |\n| **M4** | Identity presence | a **rigid** type carries no identity (own or inherited) |\n| **M5** | Dependency acyclicity | a cycle in the existence-dependency graph |\n| **M6** | Cardinality consistency | malformed or mutually contradictory cardinalities |\n| **M7** | Enum coverage | an enumerated value set is incomplete/inconsistent with its use |\n| **M8** | Axiom syntax | an axiom is not syntactically well-formed |\n| **M9** | Axiom reference check | an axiom references an undefined type/relation |\n| **M10** | Import/file error | an imported `.ttl` is missing or unparsable |\n\n## 5. Judgement set B \u2014 semantic hints `L1\u2013L5` (strict mode; machine emits, model judges)\n\nThese are **questions, not verdicts** \u2014 the engine prints them so an LLM can answer them.\n\n| ID | Hint |\n|---|---|\n| **L1** | type has **no rigidity label** \u2014 should it be rigid or anti-rigid? |\n| **L2** | **missing constraints** \u2014 are temporal / state axioms absent? |\n| **L3** | **identity adequacy** \u2014 is the declared identity sufficient for uniqueness? |\n| **L4** | **type semantics** \u2014 are there missing distinctions between types? |\n| **L5** | **axiom coverage** \u2014 do axioms reference concepts that are not defined as types? |\n\n## 6. Judgement set C \u2014 semantic review `D1\u2013D8` (model, ideally a read-only subagent)\n\nStructure can pass `M*` and still be wrong. `D*` is where an LLM reviews meaning.\n\n| ID | Dimension | Asks |\n|---|---|---|\n| **D1** | Type semantics | are names/descriptions/boundaries clear and correct? split or merge needed? |\n| **D2** | Taxonomy quality | does every `subClassOf` pass the **is-a test**? missing/incorrect links? disjointness? sensible depth (3\u20137 levels typical)? |\n| **D3** | Rigidity audit | is every rigid/anti-rigid/semi-rigid assignment justified? is inheritance consistent? |\n| **D4** | Identity criteria | do identity keys guarantee uniqueness? natural vs surrogate? any identity resting on mutable properties? |\n| **D5** | Relation semantics | real-world interpretation? domain/range correct? property characteristics true? cardinalities physically possible? |\n| **D6** | Axiom completeness & correctness | sound? missing temporal / state / dependency / instance-level cardinality constraints? |\n| **D7** | Domain completeness | what real-world entities are **not** modelled? missing relations? lifecycle/state machines? edge cases? wide/deep enough? |\n| **D8** | OntoClean deep review | the six meta-properties, applied down the whole taxonomy |\n\n**OntoClean's six meta-properties** (the vocabulary `D8` reason with):\n\n| Meta-property | Notation | Question |\n|---|---|---|\n| Identity | `+I` / `-I` | what criterion distinguishes instances of this type? |\n| Unity | `+U` / `~U` / `-U` | can instances form a whole? any anti-unity type (\"pile of sand\")? |\n| Rigidity | `+R` / `~R` / `-R` | is the property essential to every instance, in every context? |\n| Dependence | `+D` / `-D` | does this type's existence necessarily imply another's? |\n| Sortal vs non-sortal | \u2014 | can an identity criterion exist at all? |\n| Backbone taxonomy | \u2014 | does the rigid-only backbone form a consistent tree? |\n\n## 7. Judgement set D \u2014 runtime compliance `V1\u2013V4` (declaration \u2194 reality)\n\nOntology is not only a model of the world \u2014 it also **declares facts about the container itself**, so those\ndeclarations must be checked against the container's actual state.\n\n| ID | Check |\n|---|---|\n| **V1** | declared skill directories exist |\n| **V2** | orphan directories (present on disk, absent from the model) |\n| **V3** | MSM registration consistency (declared ownership \u2194 registry) |\n| **V4** | session health (duplicate goals \u00B7 session count \u00B7 stale sessions) |\n\n## 8. The OEPE loop \u2014 Ontology \u2192 EAP \u2192 Prompt-Enhancement\n\nThe reusable audit cycle. **Do not spend human effort hand-reviewing prose** \u2014 let the ontology be the\nstructural blueprint, let a subagent do semantic review in an isolated context, and let the human only\nconfirm the direction of repair.\n\n```\nO \u2500\u2500 Ontology\n\u2502    \u2460 write the domain .ttl: types + relations + axioms\n\u2502    \u2461 check --level strict         \u2192 0 errors\n\u2502    \u2462 explain                      \u2192 natural-language summary (reasoning context for the next stage)\n\u2502    \u2463 review --level onto-clean    \u2192 structured review prompt (D7 + D8)\n\u2502\n\u251C\u2500\u2500 E \u2500\u2500 EAP audit\n\u2502    \u2464 take the ontology axioms as the TOP constraint; evaluate the target artifact against each\n\u2502    \u2465 EAP scoring (E/R/S) + ambiguous-word scan\n\u2502    \u2466 emit a compliance matrix: PASS / WEAK / VIOLATION\n\u2502\n\u2514\u2500\u2500 PE \u2500\u2500 Prompt-Enhance\n     \u2467 VIOLATION \u2192 repair (P1)\n     \u2468 WEAK \u2192 strengthen (P2)\n     \u2469 PASS \u2192 keep\n     \u246A re-run check \u2192 audit \u2192 until everything is PASS\n```\n\n**Severity classes** used across the review dimensions:\n\n| Class | Meaning |\n|---|---|\n| **P0 Critical** | causes incorrect behaviour, data corruption, or violates a domain law |\n| **P1 High** | makes the ontology misleading, or unable to serve its stated purpose |\n| **P2 Medium** | reduces quality / clarity / reusability |\n| **P3 Low** | minor improvement or style suggestion |\n\n**Typical artifacts**: `<domain>-ontology.ttl` (O) \u00B7 `onto-clean-review.md` (O) \u00B7 `skill-audit-report.md` (E).\n\n## 9. Workflows\n\n**New skill**\n```\n\u2460 what type is this skill? which skills does it depend on? what are its domain entities?\n\u2461 if the domain is complex enough \u2192 build a domain ontology (types / relations / axioms)\n\u2462 write SKILL.md so that its declared dependencies match the axioms\n\u2463 structural check \u2192 0 errors\n\u2464 axiom compliance \u2192 no violation of existing axioms\n```\n\n**New concept / term**\n```\n\u2460 is this a SUBTYPE of an existing type, or a NEW type?\n\u2461 new type \u2192 add a subClassOf to the container-level registry ontology\n\u2462 subtype   \u2192 add a subClassOf to the domain ontology\n\u2463 does it need a new relation or axiom?\n\u2464 structural check \u2192 0 errors\n```\n\n**New MSM**\n```\n\u2460 Mech (deterministic) or Semi-Mech (model in the loop)?\n\u2461 which ONE skill owns it?\n\u2462 consistent with the container's BuiltinTool/MSM type in the architecture ontology?\n\u2463 record it in that skill's ontology entry\n\u2464 register it through the container's registry (never by editing the registry file directly)\n```\n\n**Retrofit \u2014 modelling a system that already exists** (the reverse direction; the three workflows above\nassume the model comes first, which is not how it usually goes)\n\n```\n\u2460 draw the boundary as an ACTIVITY, not as a system (\"developing X\", not \"the whole of X\")\n\u2461 enumerate the artefacts by MEASURING, never by recall \u2014 list the files, the registry entries, the\n  running processes; a model built from memory reproduces memory's errors\n\u2462 classify each artefact: type \u00B7 instance \u00B7 property. Only types get a class\n\u2463 for every type: rigidity + identity. A role/stage is anti-rigid; a thing that persists is rigid\n\u2464 write the relations that carry OWNERSHIP and CAUSALITY first (owner \u00B7 produces \u00B7 guards \u00B7 proves)\n\u2465 write axioms from the rules you ALREADY follow but never wrote down \u2014 that is where the payout is\n\u2466 record known failure modes as INSTANCES, not as prose paragraphs\n\u2467 strict check \u2192 0 errors; then the semantic review\n```\n\n\uD83D\uDD34 **The tell that a retrofit model is worth keeping**: running it surfaces at least one\n**contradiction in the existing system** \u2014 a thing owned in two places, a declared value that does not\nmatch reality, a rule everyone follows that nobody wrote down. A model that only restates what was\nalready obvious has not earned its maintenance cost.\n\n## 10. Universal axioms (violating any of these is a defect, not a style choice)\n\n| Axiom | Content | Consequence of violation |\n|---|---|---|\n| Unique name | two skills may not share a name | routing becomes ambiguous |\n| SKILL.md required | every skill has a SKILL.md | agents cannot locate the domain knowledge |\n| Dependency complete | using another skill's tool \u21D2 declare the dependency | implicit coupling surfaces at runtime (H_op\u2191) |\n| MSM ownership | every MSM belongs to exactly one skill | the MSM cannot be indexed |\n| Dependency acyclic | `skillDependsOn` must not form a cycle | load order becomes undefined |\n\n**Axiom discipline**: axioms are named (`AX-*`), individually citable, and each carries a rationale.\nBreaking an axiom is allowed only by stating the break explicitly and recording the reason.\n\n### The axiom rule expression (what `M8` parses, and what `M9` resolves against)\n\n`sr:rule` is **not free text** \u2014 it is a small expression language:\n\n```\nexpr        ::= implication\nimplication ::= or_expr ('implies' or_expr)?\nor_expr     ::= and_expr ('or' and_expr)*\nand_expr    ::= not_expr ('and' not_expr)*\nnot_expr    ::= 'not' not_expr | comparison\ncomparison  ::= additive (cmp additive)?          \u2190 at most ONE comparison; it does not chain\ncmp         ::= == | != | > | >= | < | <= | in    \u2190 there is no 'not in'; see the traps below\nadditive    ::= primary (('+' | '-') primary)*\nprimary     ::= quantifier | func_call | prop_access | literal | '(' expr ')'\nquantifier  ::= ('exists' | 'forall') ident 'in' Type ':' expr\nfunc_call   ::= ident '(' (expr (',' expr)*)? ')'\nprop_access ::= ident ('.' ident)*\nliteral     ::= number | 'string' | true | false | null\n```\n\n\uD83D\uDD34 **The property that makes every other trap dangerous**: `M8` accepts a rule as soon as a **prefix**\nparses. It never requires the input to be consumed to the end, so whatever follows the longest parsable\nprefix is **silently dropped** \u2014 and `M9` then checks only the AST that survived, so the dropped tail is\ninvisible to **both** checks. Measured, with its control: `Thing.count >= 1 NoSuchType.x == 1` passes\n**clean**, while the same fragment alone (`NoSuchType.x == 1`) raises an M9 warning. And\n`Thing.count >= 1 garbage here` passes clean. \u21D2 **A green check does not mean the whole rule was\nunderstood.** Keep one rule to a single clause; if you suspect a fragment is being dropped, put it alone\nin a throwaway axiom \u2014 a fragment that complains alone but not in place is a fragment being dropped.\n\n**Traps, each measured against the engine** (`check --level strict`, one probe axiom per boundary):\n\n| Trap | What the engine actually does |\n|---|---|\n| `exists` / `forall` / `in` are **reserved words** | they cannot be used as identifiers or property names: `ReleaseTag.exists` \u21D2 `Expected identifier after '.'`. Express existence through a counted property (`X.count >= 1`) instead |\n| there is **no `distinct`** | `count(distinct version)` \u21D2 `Expected ')' after args of count` (the argument parse stops at `distinct`, then hits `version`). Put the derived quantity in its own property (`VersionTriple.distinctCount == 1`) |\n| there is **no `not in`** | the operator is unreachable: `x not in y` parses as `x` and the rest vanishes **with no message**. Write `not (x in y)` \u2014 verified clean |\n| comparisons do **not chain** | `a >= 1 >= 0` parses as `a >= 1`; the tail is dropped silently. Use `and` |\n| `M9` checks **exactly two things** | (a) dotted paths of **two or more** segments \u21D2 **warning** when the head is neither a declared type nor a relation; (b) a quantifier's **type name** \u21D2 **error** when undeclared. Single bare identifiers and **function-call names are never checked**: `noSuchFunction(X) == 1` and `noSuchBareThing == 1` both pass clean \u21D2 a mistyped relation inside `occupies(\u2026)` is invisible |\n| `M8` errors are fatal, **M9's property tier is only a warning** | `check` can exit non-zero on M8 alone while a wrong head name slips past as a warning \u21D2 read the warnings, not just the exit code |\n\n**Rule of thumb**: if a constraint cannot be said in this grammar, it is probably a\n**description + rationale** (prose) rather than a rule \u2014 say it there, do not bend the syntax.\n\u26A0\uFE0F Prose is also the honest place for anything the checks **cannot** see: a constraint the engine silently\ndrops is worse than an unstated one, because it reads as verified.\n\n## 11. Dispatching a review subagent\n\nBoth OEPE review stages run in an isolated context. Three rules make them work:\n\n1. **Mandatory opening block** \u2014 the prompt must begin by requiring the subagent to load the ontology\n   method (and EAP, for the audit stage). Without it the subagent does not know the standard it is applying,\n   and its output is worthless.\n2. **Read-only** \u2014 the reviewer never edits files. Review and repair are separated: the reviewer reports,\n   the human confirms direction, the agent repairs.\n3. **Structured output** \u2014 one line per finding: `<ID> [<Severity>] <Finding> \u2014 <Evidence> \u2014 <Suggestion>`,\n   then a summary: top issues \u00B7 health grade (A\u2013F) \u00B7 prioritized repair list. Findings are written to the\n   session directory, never into the skill directory.\n\n## 12. Anti-patterns\n\n| Anti-pattern | Why it is wrong |\n|---|---|\n| modelling **instances** as **types** | the taxonomy inflates and stops carrying meaning |\n| an \"is-a\" relation that fails the **is-a test** in some context | structural checks pass, semantics rot |\n| a rigid type with **no identity** | nothing distinguishes its instances (M4) |\n| identity resting on a **mutable property** | the entity's identity changes as data changes |\n| a child that is **more rigid** than its parent | OntoClean violation (M3) |\n| putting **implementation detail** into the domain ontology | the model then tracks code, not the domain |\n| a second, competing source of truth for structure | E\u2193, and the drift is silent |\n| writing the model **after** the code | structure is reverse-engineered from accidents |\n\n## 13. Relation to the other praxis frameworks\n\n- **EAP** \u2014 how a piece of knowledge should be structured (static quality). Ontology is EAP applied to\n  domain structure.\n- **CCE** \u2014 how structured knowledge keeps evolving without losing coherence (dynamic persistence).\n  Ontology is one of CCE's `\u0394H_org` operators.\n- **Neat** \u2014 the collaboration protocol for the *design conversation* that produces the model.\n";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shgroup/dsh-serenity-hooks",
-  "version": "1.51.5",
+  "version": "1.52.0",
   "description": "宁静号 ACC harness（Native Cordis 插件）——给 DeepSeek Harness 装一个「AI 工作区」：12 个工具（container_fs/container_trajectory/dashboard/container_git/msm/praxis/handyman/localstore/container_admin/im-bridge/acc-diag/diagram）+ 机械约束（安全模式/工作区围墙/密钥守卫/对外输出守卫）+ 工作日志与原地重建 + 网页登录入口/微信桥/子角色/对外问答页/trajectory 唤醒注册表。适配 DSH 0.1.7-rc.1。",
   "license": "MIT",
   "repository": {