@wowok/skills 1.1.13 → 1.2.1

package/wowok-guard/SKILL.md

@@ -78,6 +78,101 @@ A Guard is fundamentally a **data computation tree**: deterministic data (on-cha
 
 **Guard essence**: A deterministic data set (Type 1 + Type 4) + submitted data (Type 3, must have constraint rules and defined types) → derived through finite operation rules → a single boolean result. The semantics are deterministic — you only need to fill in the "data object source meaning" and "field meaning" (e.g., "the permission address of service A", "the current node time of workflow B").
 
+### Verifier Constraint Levels — Designing Who Can Pass
+
+When a Guard uses `context(Signer)`, the designer chooses how strictly to constrain the verifier's identity. Three levels exist, trading off **security** against **convenience**. Evaluating designer intent and dismantling the semantic execution plan across these levels is a core capability — choose the right level for each scene.
+
+#### Level 1 — Strict Single-Identity Binding (avoid unless justified)
+
+**Pattern**: `logic_equal[context(Signer), identifier[N](fixed_address)]`
+
+- **Maximally secure**: only ONE address can pass
+- **Maximally inconvenient**: if that address is unavailable (key loss, personnel change, rotation), the Guard permanently blocks the operation — Guards are **immutable** after publish
+- **Use only when**: the role is permanently tied to one address AND the designer explicitly accepts the lock-in risk
+- **Risk rule**: `R-C4-04` (info) flags this pattern with a convenience reminder
+- **Example**: `logic_equal[context(Signer), identifier[5](myshop_merchant)]`
+
+> ⚠️ **Avoid Level 1 unless you understand the lock-in risk.** Prefer Level 2 (identity-set) or Level 3 (scene-combined) whenever possible.
+
+#### Level 2 — Identity-Set Binding (recommended for role-based access)
+
+**Pattern**: `logic_or` of multiple identity checks — Signer is ANY of a valid set.
+
+**Key semantic insight — Address vs Bool return types**:
+Guard queries that verify identity fall into two categories based on their return type, and this determines how they participate in a `logic_or`:
+
+| Return Type | Query Examples | Construction in `logic_or` |
+|-------------|---------------|---------------------------|
+| **Address** | `1562 order.owner`, `1002 permission.owner`, `1488 service.permission` | Must wrap each in `logic_equal[query, context(Signer)]` to produce a Bool |
+| **Bool** (suffix "has") | `1567 order.agent has`, `1004 permission.admin has`, `1006 permission.entity has` | Use **directly** as a `logic_or` child — they already return a verdict; pass `context(Signer)` as a parameter |
+
+**Example — Order-holder identity set** (Signer is owner OR agent):
+```json
+{
+  "type": "logic_or",
+  "nodes": [
+    {
+      "type": "logic_equal",
+      "nodes": [
+        {"type": "query", "query": 1562, "object": {"identifier": 0}, "parameters": []},
+        {"type": "context", "context": "Signer"}
+      ]
+    },
+    {
+      "type": "query",
+      "query": 1567,
+      "object": {"identifier": 0},
+      "parameters": [{"type": "context", "context": "Signer"}]
+    }
+  ]
+}
+```
+Here `1562` returns Address → wrapped in `logic_equal`; `1567` returns Bool → used directly with `context(Signer)` as its parameter.
+
+**Example — Service-provider identity set** (Signer is permission.owner OR has admin):
+
+Three sub-patterns with increasing flexibility:
+
+1. **Static permission address** (simplest, breaks if Service rotates permission):
+   Query `1002`/`1004` against a table-constant permission address. If the Service changes its permission (like a company changing its board), the Guard must be rebuilt.
+
+2. **Dynamic permission address** (survives rotation — **RECOMMENDED**):
+   The caller submits a permission address; the Guard verifies `query(1488: service.permission) == submitted_perm`, then checks `1002`/`1004` against the submitted permission. This survives permission rotation without rebuilding the Guard.
+
+3. **Repository-based address set** (most flexible, most complex — **only for extreme flexibility needs**):
+   The permission address set is stored in a Repository and queried dynamically. This allows runtime configuration of the authorized set, but adds significant complexity.
+
+> 💡 **`logic_or` wrapping of the Signer check suppresses R-C4-04** — this is the recommended Level 2 alternative to Level 1 strict binding.
+
+#### Level 3 — Scene-Combined Constraint (verify whether Signer binding is even needed)
+
+Before adding any Signer binding, evaluate the Guard's usage scene. **Many scenes do not need Signer binding at all** — the scene itself ensures safety through other mechanisms.
+
+| Scene | Is Signer binding needed? | Why |
+|-------|--------------------------|-----|
+| Service `order_allocators` + `sharing.who=Entity` | **NO** | Funds flow to a fixed Treasury/address regardless of caller — `sharing.who` already guarantees recipient safety (R-C3-06 safe) |
+| Service `order_allocators` + `sharing.who=Signer` | **YES (Level 2 dynamic)** | Funds flow to caller — must bind Signer to authorized recipient (e.g., `order.owner`) |
+| Machine `forward` guard | **MAYBE** | Forward's `permissionIndex`/`namedOperator` already verifies operator permission; Signer binding only needed if submitted data must belong to operator |
+| Service `buy_guard` | **Usually NO** | The customer is the caller; identity checks via whitelist/credentials suffice |
+| Reward `guard` | **Depends** | If claim is one-time (record count), no Signer binding needed; if claim amount is submitted, bind Signer |
+| Arbitration `voting_guard` | **NO** (weight from query, not Signer) | Weight must come from on-chain EntityRegistrar, not submission (R-C3-02) |
+
+**Decision flow**:
+1. Does the scene's host object already verify the operator? (e.g., Machine forward) → Signer binding may be redundant
+2. Does `sharing.who` route funds to a fixed recipient? → Signer binding unnecessary (R-C3-06 safe)
+3. Does the resource flow matter more than who triggers it? → Focus on flow safety, not caller identity
+4. Only if resources flow to the caller AND no other layer verifies identity → add Level 2 Signer binding
+
+#### One Guard One Purpose Principle
+
+Each Guard should serve **ONE specific purpose**, documented in its `description`:
+- **Scenario**: where the Guard is attached (which host object, which binding field)
+- **Verification rules**: concise statement of what conditions are checked
+- **Risk notes**: which risks are mitigated (R-C3-01/05/06, etc.) and which trade-offs apply
+- **Verifier constraint level**: which Level (1/2/3) is used and why
+
+General-purpose Guards designed for `rely` composition are the exception — they need explicit general rules and composition documentation. All other Guards should be single-purpose.
+
 ### Where Guards Attach in the Ecosystem
 
 Guards are not standalone — they plug into other WoWok objects as validation rules. Understanding these integration points is essential because the **context** of the Guard determines what data is available to it and what happens when it fails.
@@ -161,7 +256,7 @@ The Guard table is the **complete declaration of information** the Guard consume
 |-------|---------|---------------|
 | `identifier` | Unique index (0–255). The computation tree uses this number to reference the entry. | Always |
 | `b_submission` | Whether the **caller** must provide this value at runtime. `true` = runtime submission; `false` = pre-set constant. | Always |
-| `value_type` | The type of the value: Bool, Address, String, U8–U256, or vector types. Uses numeric type codes (use `wowok_buildin_info` with info `"value types"` for the complete mapping). | Always |
+| `value_type` | The type of the value: Bool, Address, String, U8–U256, or vector types. Accepts both string names (preferred, e.g., `"Address"`, `"U64"`) and numeric codes (e.g., `1`, `6`). Use `wowok_buildin_info` with info `"value types"` for the complete mapping. SDK deserialization returns string names. | Always |
 | `value` | The constant value when `b_submission` is false; a placeholder when `b_submission` is true. | When `b_submission` is false |
 | `name` | Human-readable label describing what this entry represents. | Always |
 
@@ -429,6 +524,102 @@ These constraints are checked at Guard verification time (gen_passport or actual
 - **RUN_TX_01**: The Passport's `tx_hash` must match the current transaction.
 - **RUN_RELY_01**: Rely guards must have been added to the passport.
 
+### Readability Conventions — Prefer String Names Over Numeric IDs
+
+> **Built-in MCP convention**: Whenever the schema accepts BOTH a numeric ID and a human-readable string name for the same field, **always prefer the string name** in examples, documentation, and AI-generated JSON. Numeric IDs are accepted for backward compatibility and compact machine output, but string names are the canonical form for any human-readable artifact.
+
+This convention is grounded in the user-experience principle: *"Wherever the interface supports it, optimize from the user's understanding as the starting point."* A reader who sees `"query": "order.service"` understands the intent immediately; `"query": 1563` requires an extra lookup against the `GUARDQUERY` registry.
+
+#### Fields Affected
+
+| Field | String form (preferred) | Numeric form (avoid) | Source of truth |
+|-------|-------------------------|----------------------|-----------------|
+| `query` | `"order.service"` | `1563` | `GUARDQUERY` registry (375 entries, exported by `@wowok/wowok`) |
+| `value_type` | `"Address"`, `"U64"`, `"String"` | `1`, `6`, `2` | `ValueType` enum |
+| `context` | `"Signer"`, `"Clock"`, `"Guard"` | (numeric not accepted) | `Context` enum |
+| `convert_witness` | `"OrderProgress"`, `"OrderMachine"` | `100`, `101` | `WitnessType` enum (SDK `parseWitnessType` / `witnessTypeToString`) |
+
+#### Why String Names
+
+1. **Self-documenting JSON** — `"query": "order.service"` reads as intent; `1563` is opaque.
+2. **Stable across registry renumbering** — names are part of the public contract; numeric IDs are an implementation detail.
+3. **Case-insensitive matching** — `isValidGuardQueryName` lowercases both sides, so `"Order.Service"` and `"order.service"` are equivalent. Use the canonical lowercase form in examples.
+4. **Lint-friendly** — string names survive refactoring; numeric IDs silently rot when an ID is deprecated.
+
+#### Canonical Name Examples
+
+The most common queries used in allocator Guards (R-C3-05 / R-C3-06 protection):
+
+| Numeric ID | Canonical name | Returns | Typical use |
+|------------|----------------|---------|-------------|
+| `1253` | `progress.current` | String | Verify order is at a named node (with `convert_witness: 100`) |
+| `1563` | `order.service` | Address | Cross-service theft protection (R-C3-05) |
+| `1562` | `order.owner` | Address | Signer binding for refunds (R-C3-06 Level 2 dynamic) |
+| `1272` | `progress.current_time` | U64 | Time-lock comparisons |
+| `1488` | `service.permission` | Address | Verify Service's Permission object |
+| `1002` | `permission.owner` | Address | Signer == permission owner (Level 1 fixed) |
+| `1004` | `permission.admin has` | Bool | Caller is in admin set (Level 2 identity-set) |
+| `1567` | `order.agent has` | Bool | Verify caller is an order agent |
+
+#### WitnessType String Names
+
+The `convert_witness` field accepts both numeric IDs (100-108) and string names. String matching is case-insensitive and accepts both the full enum name (`"TypeOrderProgress"`) and the shortened form without the `"Type"` prefix (`"OrderProgress"`). The shortened form is preferred for readability.
+
+| Numeric ID | Shortened name (preferred) | Full enum name | Source → Target |
+|------------|----------------------------|----------------|-----------------|
+| `100` | `"OrderProgress"` | `"TypeOrderProgress"` | Order → Progress |
+| `101` | `"OrderMachine"` | `"TypeOrderMachine"` | Order → Machine |
+| `102` | `"OrderService"` | `"TypeOrderService"` | Order → Service |
+| `103` | `"ProgressMachine"` | `"TypeProgressMachine"` | Progress → Machine |
+| `104` | `"ArbOrder"` | `"TypeArbOrder"` | Arb → Order |
+| `105` | `"ArbArbitration"` | `"TypeArbArbitration"` | Arb → Arbitration |
+| `106` | `"ArbProgress"` | `"TypeArbProgress"` | Arb → Progress |
+| `107` | `"ArbMachine"` | `"TypeArbMachine"` | Arb → Machine |
+| `108` | `"ArbService"` | `"TypeArbService"` | Arb → Service |
+
+SDK functions: `parseWitnessType(input)` converts string→number; `witnessTypeToString(type)` converts number→string (returns the shortened form). The SDK's Guard deserialization (`parseQueryNode`) already returns `convert_witness` as a string name.
+
+#### Deserialization Output — All Protocol Constants Return Strings
+
+The SDK's Guard deserialization (`query_objects` / `guard2file`) returns ALL protocol constants as user-friendly strings, not numeric IDs:
+
+| Field | Returned as | Example | Conversion function |
+|-------|-------------|---------|---------------------|
+| `query` | String name | `"order.service"` | `GUARDQUERY` registry lookup |
+| `value_type` | String name | `"Address"`, `"U64"` | `valueTypeToString()` |
+| `convert_witness` | String name | `"OrderProgress"` | `witnessTypeToString()` |
+| `context` | String literal | `"Signer"`, `"Clock"`, `"Guard"` | Hardcoded string |
+| `object_type` | String name | `"Order"`, `"Service"` | `numberToObjectType` mapping |
+| `type` (node discriminator) | String literal | `"logic_and"`, `"query"` | Always string |
+
+This means `guard2file` JSON/Markdown output and `query_objects` results are fully self-documenting without requiring numeric ID lookups.
+
+#### Example — Before and After
+
+**Before (numeric, opaque):**
+```json
+{
+  "type": "logic_equal",
+  "nodes": [
+    {"type": "query", "query": 1563, "object": {"identifier": 0, "convert_witness": 100}, "parameters": []},
+    {"type": "identifier", "identifier": 2}
+  ]
+}
+```
+
+**After (string, self-documenting):**
+```json
+{
+  "type": "logic_equal",
+  "nodes": [
+    {"type": "query", "query": "order.service", "object": {"identifier": 0, "convert_witness": "OrderProgress"}, "parameters": []},
+    {"type": "identifier", "identifier": 2}
+  ]
+}
+```
+
+Both forms are schema-valid and produce identical on-chain behavior; the string form is preferred for all human-readable output.
+
 ---
 
 ## Tool Reference

package/wowok-machine/SKILL.md

@@ -36,6 +36,78 @@ Design, build, and operate automated workflow templates.
 
 Machines are **immutable after `publish: true`**; Guards are **CREATE-only**. Design the complete workflow before publishing.
 
+## Semantic Layer (Knowledge Modules)
+
+The Machine knowledge system provides 8 TypeScript modules that encode the canonical design knowledge for Machine generation. These modules power the L4 Harness Plan Loop and are the **source of truth** for scene/template selection, pattern matching, risk evaluation, topology analysis, and the fail-closed publish gate.
+
+> **Design reference**: [Machine Design Reference](../references/machine-design-reference.md) — covering architecture, core elements, puzzle model, translation patterns, risk rules, and publish flow. Verification notes (06 §14) are embedded in code as `MACHINE_VERIFICATION_NOTES`.
+
+### Module API Reference
+
+| Module | Entry Points | Purpose |
+|--------|--------------|---------|
+| `machine-ledger.ts` | `MACHINE_SCENES`, `inferSceneFromFlow(flow)`, `findScene(id)` | 10 industry scenes + keyword-based scene inference |
+| `machine-templates.ts` | `MACHINE_TEMPLATES`, `getTemplateById(id)`, `fillTemplate(id, params)`, `forkTemplate(id, overrides)`, `walkDecisionTree(answers)` | 10 starter templates + parameter fill + Q1-Q9 decision tree |
+| `machine-translation.ts` | `SEMANTIC_TO_MACHINE_RULES`, `MACHINE_CONSTRAINT_RULES`, `matchSemanticPattern(text)`, `identifyExecutionMode(threshold, fwdCount)`, `identifyTopology(pairs)`, `explainForwardPermission(fwd)` | 12 semantic patterns + 28 on-chain constraints (creation/structure/node_operation/publish/runtime) |
+| `machine-topology.ts` | `analyzeTopology(nodes, pairs)`, `identifyTopologyPattern(topology)`, `formatTopologySummary(topology)`, `MAX_NODE_COUNT=200`, `MAX_NODE_PAIR_COUNT=40`, `MAX_FORWARD_COUNT=20` | DAG analysis: entry/terminal/orphaned/dead-branch/cycle, on-chain limit checks |
+| `machine-risk.ts` | `MACHINE_RISK_RULES` (39 rules), `assessMachineRisks(machine, ctx)`, `getRiskRulesByCategory(cat)`, `getRiskSummary(assessment)` | 5 risk dimensions (R-M1 structural, R-M2 guard, R-M3 permission, R-M4 immutability, R-M5 environment) |
+| `machine-puzzle.ts` | `initPuzzleFromIntent(intent)`, `initPuzzleFromTemplate(id)`, `checkPuzzleCompleteness(puzzle)`, `recommendNextStep(puzzle)`, `derivePuzzleFromMachineJson(json)`, `generateConfirmationText(puzzle)` | 8-dimension information model (A-H): business_flow, node_design, guard_acceptance, permission_model, threshold_weight, branch_topology, overall_objective, risk_assessment |
+| `machine-confirm.ts` | `PUBLISH_CHECKLIST` (10 items C-01..C-10), `CONFIRMATION_QUESTIONS` (6 items Q1-Q6), `runStaticChecklist(machine)`, `integrateRiskAssessment(machine, ctx)`, `parseUserConfirmation(input)`, `verifyEnvironment(machine, ctx, isMainnet)`, `confirmPublish(machine, ctx, isMainnet, userInput)`, `progressiveCheck(machine, scope)`, `overrideBlockWithReason(result, reason)`, `generateFullConfirmationText(...)` | 4-layer fail-closed gate: checklist → risk → user → environment. **CRITICAL risks cannot be overridden.** |
+| `machine-context.ts` | `injectMachineContext(intent, mode, options)`, `suggestWorkflow(intent)`, `buildPromptFromContext(bundle)`, `getMachineKnowledgeSnapshot()`, `getRelatedGuardScenes(sceneId)`, `getVerificationNotes(mode?)`, `CONTEXT_PRESETS.{newUserIntent, midDesignReview, prePublishFull, crossMachine, guardIntegration, allocationIntegration}` | Aggregator module. **8 injection modes** select curated subset of knowledge based on user task. Use this as the main entry point. |
+
+### The 8 Context Injection Modes
+
+The user's current task determines what context to surface (never dump everything):
+
+| Mode | When to Use | What It Surfaces |
+|------|-------------|------------------|
+| `initial_design` | User just described intent | Matched scene + top 3 templates + initial puzzle |
+| `mid_design_review` | User is mid-design | Missing puzzle dimensions + structure/node_op constraints |
+| `pre_publish_check` | User about to publish | Full risk assessment + progressive checklist (R5 subset) + verification notes |
+| `post_publish_runtime` | Machine already published | Runtime-only constraints + environment risks |
+| `intent_match` | Lightweight intent inference | Top 2 templates + creation constraints (no verification notes) |
+| `cross_machine` | Cross-Machine dependency design | P-M-CROSS-MACHINE pattern + structure/publish constraints |
+| `guard_integration` | Deep-dive on Guard binding | Guard bridge to `guard-ledger.ts` + R-M2 risks |
+| `allocation_integration` | Deep-dive on Allocator at terminals | P-M-ALLOCATION-INTEGRATED pattern + Allocator-related risks |
+
+### Recommended Usage Pattern
+
+```typescript
+// 1. First user message — lightweight workflow suggestion
+const suggestion = suggestWorkflow(userIntent);
+// suggestion.matched_scene, suggestion.suggested_templates, suggestion.initial_puzzle, suggestion.next_step
+
+// 2. Mid-design — inject context to surface missing info
+const bundle = injectMachineContext(intent, 'mid_design_review', { existing_puzzle: puzzle });
+
+// 3. Pre-publish — full ConfirmGate
+const gate = confirmPublish(machineJson, projectContext, isMainnet, userConfirmationInput);
+if (gate.status !== 'approved') {
+    // STOP — do not call onchain_operations with publish: true
+    console.log(gate.block_reason);
+}
+
+// 4. Or use the preset wrapper for common cases
+const preset = CONTEXT_PRESETS.prePublishFull(intent, machineJson, projectContext);
+const prompt = buildPromptFromContext(preset);  // inject into AI prompt
+```
+
+### Verification Notes (06 §14)
+
+Five topics were verified at the code level. These notes are embedded in `MACHINE_VERIFICATION_NOTES` and surfaced whenever the consumer's mode touches them:
+
+| Topic | Judgment | Verified Semantic |
+|-------|----------|-------------------|
+| `bReplace` | YES | Acts at pairs-list level of an existing node (NOT whole-Machine). `false`=merge, `true`=replace that node's pairs list. |
+| `um` | PARTIAL | Messenger Contact reference (off-chain metadata). Omitting has zero on-chain impact. |
+| `consensus_repositories` | PARTIAL | Declarative-only field. Not consumed by on-chain flow. Hint for off-chain tooling. |
+| `namedOperator_assignment` | PARTIAL | Move `progress::new` does NOT accept namedOperator. MCP/SDK translates to separate `namedOperator_add` tx (permission index 221). |
+| `cross_machine_dependency` | PARTIAL | Indirect via `progress::new -> assert_published`. Use `convert_witness` TypeOrderProgress (100) / TypeOrderProgressSession (103). |
+
+> **Test coverage**: 8 `.spec.ts` files covering machine-ledger, machine-templates, machine-translation, machine-topology, machine-risk, machine-puzzle, machine-confirm, and machine-context — over 400 tests, all passing.
+
+---
+
 ## Machine Architecture
 
 ```

package/wowok-order/APPENDIX.md

@@ -266,27 +266,27 @@ The structure populated by `customer_intelligence` service:
     "risk_score": 72,
     "risk_level": "medium_low",
     "recommendations": [
-      "要求商家配置 Arbitration 服务后再下单",
-      "通过 Messenger 协商退款条款"
+      "Require merchant to configure Arbitration service before ordering",
+      "Negotiate refund terms via Messenger"
     ],
     "reminders": [
       {
         "id": "evaluate_high_risk",
         "stage": "evaluate",
         "priority": "required",
-        "message": "🔴 综合风险分 45/100，强烈建议不购买"
+        "message": "🔴 Comprehensive risk score 45/100, strongly recommend not purchasing"
       },
       {
         "id": "evaluate_ambiguous_guard",
         "stage": "evaluate",
         "priority": "required",
-        "message": "🔴 检测到 2 个模糊 Guard，必须人工审查后才能继续"
+        "message": "🔴 Detected 2 ambiguous Guards, manual review required before proceeding"
       }
     ],
     "preference_match": {
       "score": 78,
-      "matches": ["价格低于均价 10%", "有仲裁", "有赔偿金"],
-      "mismatches": ["交付周期超出期望"]
+      "matches": ["Price 10% below market average", "Has arbitration", "Has compensation fund"],
+      "mismatches": ["Delivery timeline exceeds expectations"]
     }
   }
 }
@@ -299,32 +299,32 @@ The structure populated by `customer_intelligence` service:
 When the user mentions an industry, load the corresponding preference template and risk checks:
 
 **freelance** (free-agent services):
-- Ask: "需要 WIP hash 验证吗？里程碑节点配置了吗？"
+- Ask: "Is WIP hash verification needed? Are milestone nodes configured?"
 - Risk checks: WIP verified, milestone nodes, refund path, Messenger
 - Preference template: 30-day cycle, 4h response, require arb + comp
 
 **rental** (equipment/property rental):
-- Ask: "锁定期多久？赔偿金覆盖订单金额吗？"
+- Ask: "What is the lock duration? Does the compensation fund cover the order amount?"
 - Risk checks: compensation full, lock duration safe, arbitration, user-operable
 - Preference template: 7-day cycle, 8h response, conservative risk appetite
 
 **education** (courses/coaching):
-- Ask: "课程周期长，能接受 90 天交付吗？退款路径清楚吗？"
+- Ask: "The course cycle is long, can you accept 90-day delivery? Is the refund path clear?"
 - Risk checks: refund path, compensation, arbitration, long-cycle tolerance
 - Preference template: 90-day cycle, 24h response, conservative, flexible delivery
 
 **travel** (travel/booking services):
-- Ask: "紧急交付，2 小时内能响应吗？里程碑节点齐全吗？"
+- Ask: "Urgent delivery, can the seller respond within 2 hours? Are milestone nodes complete?"
 - Risk checks: urgent delivery, compensation full, refund path, Messenger
 - Preference template: 14-day cycle, 2h response, conservative, urgent delivery
 
 **subscription** (recurring services):
-- Ask: "订阅无锁定吗？用户可操作路径吗？"
+- Ask: "Is there no lock-in? Is there a user-operable path?"
 - Risk checks: no-lockin (no dead-end), refund path, user-operable, optional comp
 - Preference template: 30-day cycle, 24h response, aggressive risk, basic after-sales
 
 **retail** (physical goods):
-- Ask: "WIP 验证了吗？赔偿金覆盖订单吗？仲裁配置了吗？"
+- Ask: "Has WIP been verified? Does compensation cover the order? Is arbitration configured?"
 - Risk checks: WIP verified, compensation full, refund path, arbitration
 - Preference template: 7-day cycle, 8h response, balanced risk, full after-sales
 
@@ -394,14 +394,14 @@ After R9 (order creation), the post-purchase phase begins. Use `post-purchase.ts
 ```
 User wants refund or refund Allocator fired:
 ├── refunded_amount vs order_amount?
-│   ├── 100% refunded → "退款已完成" (info)
-│   ├── Partial refund → "退款不完整，差额 X" (recommended)
+│   ├── 100% refunded → "Refund completed" (info)
+│   ├── Partial refund → "Refund incomplete, shortfall X" (recommended)
 │   │   └── Next step: query order state + contact merchant via Messenger
-│   ├── 0 refund + user-initiated → "等待商家退款" (recommended)
+│   ├── 0 refund + user-initiated → "Waiting for merchant refund" (recommended)
 │   │   └── Next step: monitor via order_monitor service
-│   ├── 0 refund + refund path exists → "可通过 Allocator 触发退款" (recommended)
+│   ├── 0 refund + refund path exists → "Refund can be triggered via Allocator" (recommended)
 │   │   └── Next step: advance to refund node via order.progress
-│   └── 0 refund + no refund path → "无退款路径，需通过仲裁" (required)
+│   └── 0 refund + no refund path → "No refund path, arbitration required" (required)
 │       └── Next step: file arbitration dispute (see Phase 4)
 ```
 
@@ -410,14 +410,14 @@ User wants refund or refund Allocator fired:
 ```
 User reports quality problem:
 ├── WIP hash comparison
-│   ├── current_wip_hash != original_wip_hash → "WIP 不一致" (required)
+│   ├── current_wip_hash != original_wip_hash → "WIP mismatch" (required)
 │   │   └── Document: re-verify via wip_file, generate WTS evidence
-│   └── wip_hash missing → "要求商家提供 WIP hash 验证" (recommended)
+│   └── wip_hash missing → "Request merchant to provide WIP hash verification" (recommended)
 │
 ├── Evidence collection
-│   ├── evidence empty → "收集证据：截图、聊天记录、交付物样品" (required)
-│   ├── evidence < 3 items → "补充更多证据以增强仲裁胜算" (recommended)
-│   └── evidence ≥ 3 items → "证据充分，可考虑发起仲裁" (info)
+│   ├── evidence empty → "Collect evidence: screenshots, chat logs, delivery samples" (required)
+│   ├── evidence < 3 items → "Add more evidence to strengthen arbitration case" (recommended)
+│   └── evidence ≥ 3 items → "Evidence sufficient, consider filing arbitration" (info)
 │
 └── Next step: hand off to Phase 4 (arbitration support) if unresolved
 ```
@@ -427,12 +427,12 @@ User reports quality problem:
 ```
 Seller not responding on Messenger:
 ├── Days since last reply?
-│   ├── ≤ 3 days → "商家可能忙碌，等待回复" (info)
-│   ├── > 3 days → "持续无响应，发送催促消息" (recommended)
+│   ├── ≤ 3 days → "Merchant may be busy, waiting for reply" (info)
+│   ├── > 3 days → "Persistent non-response, send reminder message" (recommended)
 │   │   └── Next step: send Messenger reminder + document stall
-│   ├── > 7 days + has_arbitration → "建议发起仲裁" (required)
+│   ├── > 7 days + has_arbitration → "Recommend filing arbitration" (required)
 │   │   └── Next step: file arbitration dispute (see Phase 4)
-│   └── > 7 days + no arbitration → "无仲裁通道，资金可能冻结" (required)
+│   └── > 7 days + no arbitration → "No arbitration channel, funds may be frozen" (required)
 │       └── Next step: escalate to WoWok community / off-chain recourse
 │
 └── If order_monitor service is ON, these alerts fire automatically
@@ -443,19 +443,19 @@ Seller not responding on Messenger:
 ```
 Filing arbitration dispute:
 ├── arbitration_initiated?
-│   ├── NO → "建议发起仲裁申请" (required)
+│   ├── NO → "Recommend filing arbitration application" (required)
 │   │   └── Generate application template:
-│   │       title: "订单 {order_id} 交付争议申请"
+│   │       title: "Order {order_id} delivery dispute application"
 │   │       description: template auto-filled from puzzle + evidence
-│   │       evidence_required: [聊天记录, 交付物截图, WIP hash 对比]
+│   │       evidence_required: [Chat logs, Delivery screenshots, WIP hash comparison]
 │   │       claim: refund / compensation / specific performance
 │   │
 │   └── YES → check status
-│       ├── arb_window_days ≤ 3 → "仲裁窗口即将关闭" (required)
+│       ├── arb_window_days ≤ 3 → "Arbitration window closing soon" (required)
 │       │   └── Next step: expedite evidence submission
-│       ├── evidence empty → "补充证据" (required)
-│       ├── evidence < 3 → "补充更多证据以增强仲裁胜算" (recommended)
-│       └── evidence ≥ 3 → "证据充分，等待仲裁结果" (info)
+│       ├── evidence empty → "Submit evidence" (required)
+│       ├── evidence < 3 → "Add more evidence to strengthen arbitration case" (recommended)
+│       └── evidence ≥ 3 → "Evidence sufficient, waiting for arbitration result" (info)
 │
 └── Result interpretation guide:
     ├── State (3) Arbitrated → user can accept or object

package/wowok-provider/SKILL.md

@@ -163,20 +163,34 @@ STEP 5: Post-Publish (MODIFY Service — mutable after publish)
 
 ### Service Object Relationships
 
+> **Authoritative source**: [Object Collaboration Diagram](../references/object-collaboration.md) §1 (22-object collaboration DAG, 83 relationships).
+> This tree is a simplified view. Cross-reference the above for the full graph and [Object Boundary Conditions](../references/object-collaboration.md#boundary-conditions) for mutability rules.
+
 ```
 Service (merchant storefront)
-├── machine → Machine (workflow)
-├── order_allocators → Fund distribution rules
-├── arbitrations → Dispute resolution (optional)
-├── compensation_fund → Customer protection (optional)
-├── sales → Products with WIP files
-├── rewards → Incentive pools (optional)
-└── um → Contact (customer service)
-
-Order (per purchase)
-├── builder → Customer
-├── progress → Workflow state
-└── allocation → Fund distribution engine
+├── permission → Permission (required, mutable after publish)
+├── machine → Machine (required, IMMUTABLE after publish)
+├── order_allocators → Allocation[] (optional, mutable after publish)
+├── arbitrations → Arbitration[] (optional, mutable after publish, max 20)
+├── compensation_fund → Treasury (optional, mutable after publish)
+├── sales → Repository (optional, mutable after publish; products with WIP files)
+├── rewards → Reward[] (optional, mutable after publish)
+├── um → Contact (optional, mutable after publish; customer service)
+├── customer_required → Personal (optional, mutable after publish; customer data schema)
+└── buy_guard → Guard (optional, mutable after publish; gates order placement)
+
+Order (per purchase, runtime-created)
+├── builder → Customer (immutable after creation)
+├── service → Service snapshot (immutable after creation)
+├── machine → Machine (immutable after creation)
+├── progress → Progress (immutable after binding)
+├── arbitration → Arbitration (optional, immutable once set)
+└── allocation → Fund distribution engine (triggered via Progress.forward)
+
+Cross-object references (see [Object Collaboration Diagram §6](../references/object-collaboration.md#guard-and-machine-global-usage) for Guard/Machine global usage):
+- Guard is referenced by 9 object types (Service.buy_guard, Machine.forward.guard, Allocation.allocation_guard, Arbitration.voting_guard, Reward.claim_guard, Repository.write_guard, Treasury.external_guard, Demand.recommend_guard, Passport.guard)
+- Machine is referenced by 4 object types (Service.machine, Order.machine, Progress.machine, Order snapshot)
+- Permission is the central hub — 11 objects hold BuiltinPermissionIndex (see [Object Collaboration Diagram §5](../references/object-collaboration.md#permission-reverse-reference-table) for reverse-reference table)
 ```
 
 ### Allocators + Machine Integration

package/wowok-scenario/SKILL.md

@@ -31,6 +31,16 @@ when_to_use:
 
 A **driving mode** is a curated bundle of: industry traits, default Permission indexes, default Machine node graph, default Guard templates, default Allocator strategy, a 10-round build script, an audit checklist, and a failure playbook. Modes are **presets, not constraints** — every underlying MCP operation remains available. Users can override any default or switch to `general` (free) mode at any time.
 
+> **Authoritative cross-reference**: This skill's mode definitions are aligned with the following internal references:
+> - [Guard Template Library](../references/guard-template-library.md) — Guard templates referenced by mode `Guards` column
+> - [Machine Template Library](../references/machine-template-library.md) — Machine shapes referenced by mode `Machine Shape` column
+> - [Machine Scenario Ledger](../references/machine-scenario-ledger.md) — 10 business scenarios per mode
+> - [Guard Scenario Ledger](../references/guard-scenario-ledger.md) — Guard usage scenarios per mode
+> - [Merchant Scenario Coordination §5](../references/merchant-scenario-coordination.md) — 6 industry modes × merchant perspective
+> - [On-chain Constants](../references/onchain-constants.md) — Permission index ranges and capacity limits
+>
+> When a mode's defaults disagree with these references, the **design references** in this directory are authoritative (P15 decision: bidirectional cross-reference, with design references as single source of truth for object semantics).
+
 ### What Driving Modes Solve
 
 The "object_type wall" — new users do not know which Machine topology, which Guards, which Allocator strategy fits their industry. Modes pre-answer these questions using best practices distilled from real usage (and refined by Loop Engineering over time).

package/wowok-tools/SKILL.md

@@ -266,8 +266,8 @@ When explaining a specific technique to users, reference where it appears:
 
 | Trap | Fix |
 |------|-----|
-| **Transaction fails, gas error** | → [Pre-Flight: Gas & Faucet](#-pre-flight-gas--faucet前置必读). AI should auto-check balance + faucet. |
-| **Don't know how to build a service** | → [Examples Reference](#examples-reference内置示例导航). Match user intent → example, extract JSON templates. |
+| **Transaction fails, gas error** | → [Pre-Flight: Gas & Faucet](#pre-flight-gas--faucet). AI should auto-check balance + faucet. |
+| **Don't know how to build a service** | → [Examples Reference](#examples-reference). Match user intent → example, extract JSON templates. |
 | `gen_passport` called as standalone tool | It's not — use `onchain_operations` with `operation_type: "gen_passport"` |
 | Missing `data` wrapper | Only `gen_passport` omits it; `payment`/`personal` omit `submission` |
 | String `object` passed expecting CREATE | String = existing (MODIFY), Object = new (CREATE) → [safety §1.1](../wowok-safety/SKILL.md) |