@wowok/skills 1.2.2 → 1.2.3

package/references/object-collaboration.md

@@ -0,0 +1,362 @@
+# Object Collaboration Reference
+
+> Single authoritative reference for skills needing object collaboration, constraints, and capacity limits.
+> Covers the 22-object collaboration DAG and boundary conditions.
+
+---
+
+## 1. 22-Object Collaboration DAG
+
+### 1.1 Mermaid Diagram
+
+```mermaid
+graph TB
+    %% ── Core Layer ──
+    PERM[Permission<br/>R1 Required]
+    TREAS[Treasury<br/>R2 Required]
+    ALLOC[Allocation<br/>R3 Required]
+    SERV[Service<br/>R4 Required]
+    ORDER[Order<br/>Runtime]
+    PROG[Progress<br/>Runtime]
+    ARB[Arbitration<br/>C6 Optional]
+
+    %% ── Trust Layer ──
+    GUARD[Guard<br/>R5 Required]
+    MACH[Machine<br/>R6 Required]
+    PASS[Passport<br/>Runtime]
+    PROOF[Proof<br/>Runtime]
+
+    %% ── Data Layer ──
+    REPO[Repository<br/>C7 Optional]
+    DEMAND[Demand<br/>Phase 0]
+    REWD[Reward<br/>C8 Optional]
+    CONT[Contact<br/>C1 Conditional]
+    PERS[Personal<br/>C5 Conditional]
+
+    %% ── User Layer ──
+    REG[Registrar+Entity<br/>E9]
+    RES[Resource<br/>Tool]
+    PAY[Payment<br/>Funds]
+    ARBN[Arb Node<br/>Arbitration Node]
+    UTIL[Util<br/>Tool]
+    BRIDGE[Bridge<br/>Cross-chain]
+
+    %% ── Core Layer Dependencies ──
+    PERM --> TREAS
+    PERM --> ALLOC
+    PERM --> SERV
+    PERM --> ARB
+    TREAS --> ALLOC
+    ALLOC --> SERV
+    SERV --> ORDER
+    MACH --> ORDER
+    ORDER --> PROG
+    ORDER --> ARB
+    PROG --> ALLOC
+
+    %% ── Trust Layer Dependencies ──
+    PERM --> GUARD
+    GUARD --> MACH
+    GUARD --> PASS
+    MACH --> SERV
+    MACH --> PROG
+    PASS --> PROOF
+    PROOF --> ARB
+
+    %% ── Data Layer Dependencies ──
+    PERM --> REPO
+    GUARD --> REPO
+    REPO --> REWD
+    PERM --> REWD
+    GUARD --> REWD
+    REWD --> DEMAND
+    PERM --> DEMAND
+    GUARD --> DEMAND
+    PERM --> CONT
+    REG --> CONT
+    SERV --> CONT
+    PERS --> SERV
+
+    %% ── User Layer Dependencies ──
+    REG --> PERS
+    RES --> REG
+    PAY --> TREAS
+    PAY --> ALLOC
+    ARB --> ARBN
+    UTIL --> ALL[All Objects]
+    BRIDGE -.->|mainnet only| TREAS
+
+    %% ── Styles ──
+    classDef required fill:#ffeb3b,stroke:#f57f17,stroke-width:2px
+    classDef runtime fill:#81c784,stroke:#1b5e20,stroke-width:1px
+    classDef optional fill:#bbdefb,stroke:#0d47a1,stroke-width:1px
+    classDef tool fill:#eeeeee,stroke:#424242,stroke-width:1px,stroke-dasharray: 5 5
+
+    class PERM,TREAS,ALLOC,SERV,GUARD,MACH required
+    class ORDER,PROG,PASS,PROOF,ARB runtime
+    class REPO,DEMAND,REWD,CONT,PERS,REG,ARBN optional
+    class RES,PAY,UTIL,BRIDGE tool
+```
+
+### 1.2 ASCII Overview
+
+```
+[CORE LAYER - Merchant Build Pipeline]
+  Permission(1) ──┬──► Treasury(2) ──► Allocation(3) ──┐
+                  │                                      │
+                  ├──► Service(4) ◄──────────────────────┘
+                  │       │
+                  │       ▼
+                  │     Order(5) ──► Progress(6)
+                  │       │              │
+                  │       ▼              ▼
+                  └──► Arbitration(7) ◄──┘
+                            │
+                            ▼
+                         Arb Node(17)
+
+[TRUST LAYER - Workflow & Evidence]
+  Permission(1) ──► Guard ──┬──► Machine ──► Service(4)
+                             │       │            │
+                             │       ▼            ▼
+                             │     Order(5)    Progress(6)
+                             │
+                             └──► Passport(9) ──► Proof(10) ──► Arbitration(7)
+
+[DATA LAYER - Strategy & Incentives]
+  Permission(1) ─┬──► Repository(11) ──► Reward(8) ──► Demand(12)
+                 │                          ▲               │
+                 └──► Reward(8) ────────────┘               │
+                 └──► Demand(12) ◄──────────────────────────┘
+  Guard ──► Repository(11)
+  Guard ──► Reward(8)
+  Guard ──► Demand(12)
+
+[USER LAYER - Contact & Personal]
+  Permission(1) ──► Contact(13) ──► Service(4).um
+  Registrar+Entity(14) ──► Contact(13)
+  Registrar+Entity(14) ──► Personal(18) ──► Service(4).customer_required
+
+[TOOL LAYER - Auxiliary]
+  Resource(15) ──► Registrar(14)
+  Payment(16)   ──► Treasury(2) / Allocation(3)
+  Util(19)      ──► All Objects
+  Bridge(20)    ──► Treasury(2) (mainnet only)
+```
+
+### 1.3 Object Distribution by Layer
+
+| Layer | Objects | Count | Role |
+|-------|---------|-------|------|
+| Core | Permission, Treasury, Allocation, Service, Order, Progress, Arbitration | 7 | Business pipeline |
+| Trust | Guard, Machine, Passport, Proof | 4 | Workflow & evidence |
+| Data | Repository, Reward, Demand | 3 | Strategy & incentives |
+| User | Contact, Personal, Registrar+Entity | 3 | Contact & personal |
+| Tool | Resource, Payment, Util, Bridge, Arb Node | 5 | Auxiliary |
+| **Total** | | **22** | (includes Guard + Machine) |
+
+### 1.4 Collaboration Types (5 Categories)
+
+| Type | Meaning | Count | Example |
+|------|---------|-------|---------|
+| **CREATE** | A creates B (B is child of A) | 18 | Permission creates Service |
+| **BIND** | A references B (B is a field of A) | 35 | Service.machine = Machine |
+| **TRIGGER** | A triggers an operation on B | 12 | Order triggers Progress |
+| **VALIDATE** | A validates B's state | 10 | Guard validates Service |
+| **CONSUME** | A consumes B's output | 8 | Proof consumes Passport |
+| **Total** | | **83** | |
+
+### 1.5 Top 5 High-Frequency Collaboration Objects
+
+| Rank | Object | In-degree | Out-degree | Total |
+|------|--------|-----------|------------|-------|
+| 1 | Permission | 13 | 0 | 13 |
+| 2 | Guard | 9 | 8 | 17 |
+| 3 | Service | 6 | 8 | 14 |
+| 4 | Machine | 4 | 3 | 7 |
+| 5 | Treasury | 4 | 2 | 6 |
+
+Key observations:
+- **Permission** is the highest in-degree object (13), the "gatekeeper" of all writes
+- **Guard** is the highest out-degree object (8), the "validator"
+- **Service** is the "hub" connecting merchant-side and user-side
+
+### 1.6 Permission Reverse Reference (9 Objects with BuiltinPermissionIndex)
+
+| Object | Index Range | Count | Usage |
+|--------|------------|-------|-------|
+| Repository | 100-105 | 6 | Repository operations |
+| Reward | 150-157 | 8 | Reward operations |
+| Machine | 200-208 | 8 | Machine operations |
+| Progress | 220-225 | 6 | Progress operations |
+| Treasury | 250-258 | 9 | Treasury operations |
+| Service | 300-320 | 21 | Service operations |
+| Arbitration | 350-368 | 19 | Arbitration operations |
+| Demand | 400-408 | 9 | Demand operations |
+| Contact | 450-454 | 5 | Contact operations |
+
+Note: Permission and Order do NOT hold BuiltinPermissionIndex entries. Permission is the carrier referenced by other objects; Order references Permission indirectly through Service snapshot.
+
+---
+
+## 2. 5-Dimension Boundary Condition Model
+
+```
+ ┌─────────────────────────────────────────────────────────────────────┐
+ │              Object Boundary Condition 5-Dimension Model             │
+ └─────────────────────────────────────────────────────────────────────┘
+
+   [1. Mutability]    [2. Prerequisites]    [3. Capacity Limits]    [4. Permissions]    [5. Irreversibility]
+        │                    │                     │                     │                     │
+        ▼                    ▼                     ▼                     ▼                     ▼
+   Fields modifiable?    What must exist         Quantity limits?    Operation                Operations
+                         before create                            permissions?             irreversible?
+                         or publish?
+```
+
+| Dimension | Meaning | Values |
+|-----------|---------|--------|
+| 1. Mutability | Whether fields can be modified after creation | `MUTABLE` / `IMMUTABLE_AFTER_PUBLISH` / `IMMUTABLE_AFTER_CREATE` / `FROZEN` |
+| 2. Prerequisites | Conditions that must be met before create/operation | Object list + stage requirements |
+| 3. Capacity Limits | Quantity/size upper bounds | Numeric constants |
+| 4. Permissions | Permission index required for operations | Index value or `owner_only` |
+| 5. Irreversibility | Whether operations can be undone | `REVERSIBLE` / `IRREVERSIBLE` |
+
+---
+
+## 3. Main Boundary Condition Table (All 22 Objects)
+
+| Object | Mutability | Prerequisites | Capacity Limits | Permissions | Irreversibility |
+|--------|-----------|---------------|-----------------|-------------|-----------------|
+| Permission | permission list mutable | None | MAX_PERM_FOR_ENTITY=1000, MAX_ADMIN_COUNT=500 | owner_only | Adding index reversible |
+| Treasury | external_guard/owner_receive/um mutable | Permission | — | owner + 250-258 | deposit/withdraw reversible |
+| Allocation | permission/sharing mutable | Treasury + Permission | MAX_SHARING_COUNT=100 | owner + allocation_guard | allocate irreversible |
+| Service | machine immutable after publish | Permission | MAX_ARBITRATION_COUNT=20 | owner + 300-320 | publish irreversible |
+| Order | service/machine immutable | Service(published) + Machine(published) | MAX_AGENT_COUNT=10 (actual 11), MAX_DISPUTE_COUNT=10 | owner (via Service snapshot) | create irreversible |
+| Progress | machine/order immutable | Order + Machine | — | owner + 220-225 | forward irreversible |
+| Arbitration | permission mutable | Order + Permission | MAX_VOTING_GUARD_COUNT=50 | owner + 350-368 | ruling irreversible |
+| Reward | permission/guard mutable | Repository + Permission | — | owner + 150-157 | distribution irreversible |
+| Passport | — | Guard | Time bound | gen_passport | expiry irreversible |
+| Proof | — | Passport | — | submitter | submission irreversible |
+| Repository | permission/guard mutable | Permission | MAX_POLICY_COUNT=50, MAX_ID_COUNT_ONCE=100 | owner + 100-105 | write reversible |
+| Demand | permission/guard/service mutable | Permission | MAX_GUARD_COUNT_DEMAND=20, MAX_FEEDBACK_COUNT=20 (SDK) | owner + 400-408 | present irreversible |
+| Contact | permission mutable | Permission + Registrar | — | owner + 450-454 | message irreversible |
+| Registrar | — | — | MAX_RECORD_COUNT_REGISTRAR=1000 | owner | registration irreversible |
+| Entity | — | Registrar | — | registrar owner | registration irreversible |
+| Resource | — | — | — | owner | create reversible (delete) |
+| Payment | FROZEN | — | — | — | create = freeze |
+| Arb Node | can exit | Arbitration | — | owner | join reversible (exit) |
+| Personal | registrar immutable | Registrar | — | owner | create reversible (delete) |
+| Util | — | — | — | — | Tool module |
+| Bridge | — | — | — | owner | cross-chain irreversible |
+| Guard | named_operator mutable | Permission | MAX_GUARD_COUNT_PASSPORT=20 | owner | gen_passport regenerable |
+| Machine | permission mutable, nodes immutable after publish | Permission | MAX_NODE_COUNT_SDK=100, MAX_FORWARD_COUNT=20, MAX_FORWARD_ORDER_COUNT=20, MAX_NODE_PAIR_COUNT=40 | owner + 200-208 | publish irreversible |
+
+### Key Observations
+
+1. **Payment** is the only FROZEN object (created in terminal state)
+2. **Service/Machine** are the only two objects with IMMUTABLE_AFTER_PUBLISH semantics
+3. **Order/Progress/Arbitration** are runtime-irreversible objects
+4. **Permission** is the central node, depended on by 9 objects
+5. **Guard** has 3 different MAX_GUARD_COUNT constants (Demand/Passport=20, Reward=200)
+
+---
+
+## 4. Capacity Limits (On-Chain Constants)
+
+| Constant | Value | Source | Applies To | Notes |
+|----------|-------|--------|-----------|-------|
+| `MAX_NODE_COUNT_ONCHAIN` | 200 | machine.move | Machine | On-chain limit |
+| `MAX_NODE_COUNT_SDK` | 100 | onchain-constants.ts | Machine | SDK/MCP stricter |
+| `MAX_FORWARD_COUNT` | 20 | machine.move | Machine | Forwards per Pair |
+| `MAX_FORWARD_ORDER_COUNT` | 20 | machine.move | Machine | Forward order count |
+| `MAX_NODE_PAIR_COUNT` | 40 | machine.move | Machine | Pairs per node |
+| `USER_DEFINED_PERM_INDEX_START` | 1000 | permission.move | Permission | Custom permission start |
+| `MAX_PERM_FOR_ENTITY` | 1000 | permission.move | Permission | Permissions per Entity |
+| `MAX_ADMIN_COUNT` | 500 | permission.move | Permission | Admin count limit |
+| `MAX_AGENT_COUNT` | 10 | order.move | Order | Actual 11 (off-by-one bug) |
+| `MAX_DISPUTE_COUNT` | 10 | order.move | Order | Dispute count limit |
+| `MAX_SHARING_COUNT` | 100 | allocation.move | Allocation | Sharing count limit |
+| `MAX_VOTING_GUARD_COUNT` | 50 | arbitration.move | Arbitration | Voting guard limit |
+| `MAX_POLICY_COUNT` | 50 | repository.move | Repository | Policy count limit |
+| `MAX_ID_COUNT_ONCE` | 100 | repository.move | Repository | Single ID batch limit |
+| `MAX_GUARD_COUNT_DEMAND` | 20 | demand.move | Demand | Guard count for Demand |
+| `MAX_GUARD_COUNT_PASSPORT` | 20 | passport.move | Passport | Guard count for Passport |
+| `MAX_GUARD_COUNT_REWARD` | 200 | reward.move | Reward | Guard count for Reward |
+| `MAX_RECORD_COUNT_REWARD` | 5200 | reward.move | Reward | Records per recipient |
+| `MAX_RECORD_COUNT_REGISTRAR` | 1000 | registrar.move | Registrar | Registrar record count |
+| `MAX_REWARD_COUNT` | 20 | demand.move | Demand | Rewards per Demand |
+| `MAX_CONTEXT_REPOSITORY_COUNT` | 30 | progress.move | Progress | Context repository count |
+| `MAX_ARBITRATION_COUNT` | 20 | service.move | Service | Arbitrations per Service |
+| `MAX_FEEDBACK_COUNT` | 20 | demand.ts (SDK) | Demand | SDK-only, no Move check |
+| `DEFAULT_SETTING_LOCK_DURATION` | 2592000000 | service.move | Service | 30 days (ms) |
+
+### MAX_GUARD_COUNT Name Collision
+
+| Object | Value | Constant Name |
+|--------|-------|--------------|
+| Demand | 20 | MAX_GUARD_COUNT_DEMAND |
+| Passport | 20 | MAX_GUARD_COUNT_PASSPORT |
+| Reward | 200 | MAX_GUARD_COUNT_REWARD |
+
+---
+
+## 5. Key Observations
+
+### 5.1 Irreversibility Summary
+
+| Object | Operation | Irreversibility Reason | Recovery |
+|--------|-----------|----------------------|----------|
+| Service | publish | On-chain state irreversible | New Service |
+| Machine | publish | On-chain state irreversible | New Machine |
+| Order | create | On-chain record cannot be deleted | Wait for TERMINATED |
+| Payment | create | freeze_object | Unrecoverable |
+| Progress | forward | Node flow irreversible | Wait for terminal |
+| Arbitration | dispute/execute | Dispute/verdict irreversible | Unrecoverable |
+| Allocation | allocate | Fund allocation irreversible | Unrecoverable |
+| Reward | claim | Reward distribution irreversible | Unrecoverable |
+
+### 5.2 Service Field Mutability (Critical)
+
+| Field | CONFIGURED | PUBLISHED | ACTIVE |
+|-------|------------|-----------|--------|
+| permission | MUTABLE | MUTABLE | MUTABLE |
+| machine | MUTABLE | **IMMUTABLE** | **IMMUTABLE** |
+| order_allocators | MUTABLE | — | MUTABLE |
+| arbitrations | MUTABLE | — | MUTABLE |
+| buy_guard | MUTABLE | — | MUTABLE |
+| price | MUTABLE | — | MUTABLE |
+| publish_state | — | **SET ONCE** | — |
+
+**Critical constraint**: `Service.machine` is the only core field that becomes immutable after publish.
+
+### 5.3 Prerequisites Summary
+
+| Object | Must Exist Before Create |
+|--------|-------------------------|
+| Treasury | Permission |
+| Allocation | Treasury + Permission |
+| Service | Permission |
+| Machine | Permission |
+| Guard | Permission |
+| Order | Service (published) + Machine (published) |
+| Progress | Order + Machine |
+| Arbitration | Order + Permission |
+| Reward | Repository + Permission |
+| Passport | Guard |
+| Proof | Passport |
+| Repository | Permission |
+| Demand | Permission |
+| Contact | Permission + Registrar |
+| Personal | Registrar |
+| Arb Node | Arbitration |
+
+### 5.4 Network Differences
+
+| Aspect | testnet | mainnet |
+|--------|---------|---------|
+| CREATE | replaceExistName=true, repeatable | replaceExistName=false, no overwrite |
+| BIND | Rebinding allowed | Locked after creation |
+| TRIGGER | Repeatable | Irreversible |
+| VALIDATE | Guard can be rebuilt | Guard rebuild requires updating all references |
+| Bridge | ❌ Not supported | ✅ Supported |

package/references/onchain-constants.md

@@ -0,0 +1,81 @@
+# On-Chain Constants — Unified Management Reference
+
+> **Status**: Unified management reference for on-chain numeric constants across three layers (Move contracts, SDK, MCP).
+
+## Why Unified Management
+
+Before GLM4, on-chain numeric constants were scattered across three layers:
+
+- **Smart contract layer**: Each `.move` file has its own `const MAX_* = N;` (on-chain authority)
+- **SDK layer**: Each `.ts` call file has its own `export const MAX_* = N;` (prone to drift from chain)
+- **MCP layer**: Hardcoded magic numbers (`100`, `1000`, etc.) with no import links
+
+This caused drift risk, magic numbers in MCP, and implicit differences between SDK and on-chain values.
+
+**Solution**: SDK is the single authoritative TS definition; MCP imports from SDK; Move contracts remain unchanged.
+
+## 3-Layer Sync Architecture
+
+```
+┌──────────────────────┐    import    ┌──────────────────────┐
+│ Move smart contracts │ ──────────► │ SDK onchain-constants │
+│ (*.move const MAX_*) │              │ (canonical TS source) │
+└──────────────────────┘              └──────────┬───────────┘
+                                                 │ import
+                                                 ▼
+                                       ┌──────────────────────┐
+                                       │ MCP onchain-constants │
+                                       │ (re-export from SDK)  │
+                                       └──────────────────────┘
+```
+
+### Sync Guarantees
+
+- **SDK ↔ Move**: A spec test parses `.move` files and asserts SDK values match Move `const` declarations
+- **MCP ↔ SDK**: The same test asserts MCP import values equal SDK export values
+- **CI Integration**: Sync tests run on every PR to prevent drift across all three layers
+
+## 18 Constant Entries
+
+| # | Name | Value | Move Source | Purpose |
+|---|------|-------|-------------|---------|
+| 1 | `MAX_NODE_COUNT_ONCHAIN` | 200 | `machine.move:23` | Max nodes on-chain (chain authority) |
+| 2 | `MAX_NODE_COUNT_SDK` | 100 | (SDK custom) | Stricter limit for SDK/MCP (easier human review) |
+| 3 | `MAX_FORWARD_COUNT` | 20 | `machine.move:26` | Max global forwards per Machine |
+| 4 | `MAX_FORWARD_ORDER_COUNT` | 20 | `machine.move:21` | Max forwards per pair |
+| 5 | `MAX_NODE_PAIR_COUNT` | 40 | `machine.move:22` | Max pairs per node |
+| 6 | `USER_DEFINED_PERM_INDEX_START` | 1000 | (convention) | Custom permission_index start (0-999 reserved for built-in) |
+| 7 | `MAX_PERM_FOR_ENTITY` | 1000 | `permission.move:15` | Max permissions per Entity |
+| 8 | `MAX_ADMIN_COUNT` | 500 | `permission.move:17` | Max admins per Permission object |
+| 9 | `MAX_AGENT_COUNT` | 10 | `order.move:12` | Max agents per Order |
+| 10 | `MAX_DISPUTE_COUNT` | 10 | `order.move:13` | Max concurrent disputes per Order |
+| 11 | `MAX_SHARING_COUNT` | 100 | `allocation.move:17` | Max sharing entries per allocator |
+| 12 | `MAX_VOTING_GUARD_COUNT` | 50 | `arbitration.move:25` | Max voting guards per Arbitration |
+| 13 | `MAX_POLICY_COUNT` | 50 | `repository.move:22` | Max policies per Repository |
+| 14 | `MAX_ID_COUNT_ONCE` | 100 | `repository.move:25` | Max IDs per Repository operation |
+| 15 | `MAX_REWARD_COUNT` | 20 | `demand.move:21` + `repository.move:26` | Max rewards per Demand/Repository (same name, same value, different scopes) |
+| 16 | `MAX_CONTEXT_REPOSITORY_COUNT` | 30 | `progress.move:23` | Max context repositories per Progress |
+| 17 | `MAX_NAMED_OPERATOR_COUNT` | 60 | `progress.move:24` | Max named operators per Forward |
+| 18 | `MAX_NAMED_OPERATOR_ADDRESS_COUNT` | 80 | `progress.move:25` | Max addresses per named operator |
+
+> Note: 18 entries total (including `MAX_NODE_COUNT_ONCHAIN` and `MAX_NODE_COUNT_SDK` as two variants), corresponding to 15 unique on-chain constant concepts.
+
+## Naming Conventions
+
+- Constant names match Move names exactly (e.g., `MAX_FORWARD_ORDER_COUNT`, not rewritten)
+- When the SDK is intentionally stricter than on-chain: chain value uses `*_ONCHAIN` suffix, SDK value uses `*_SDK` suffix, bare name (e.g., `MAX_NODE_COUNT`) aliases the SDK value
+- `USER_DEFINED_PERM_INDEX_START` is a **convention**, not a Move `const` (permission.move implicitly reserves 0-999)
+
+## Special Case: `MAX_REWARD_COUNT`
+
+`MAX_REWARD_COUNT = 20` is defined in both `demand.move:21` (Demand reward cap) and `repository.move:26` (Repository reward cap). Same name and value but semantically independent. If the chain ever diverges, split into `MAX_REWARD_COUNT_DEMAND` and `MAX_REWARD_COUNT_REPOSITORY`.
+
+## Key Design Principles
+
+1. **Move contracts are the ultimate source of truth**: SDK must always align with Move. When a discrepancy is found, **fix the SDK** (unless the Move contract itself has a bug requiring an on-chain upgrade).
+2. **SDK is the single authoritative definition**: `onchain-constants.ts` in the SDK is the sole canonical source for the SDK/MCP layer; MCP does not redefine constants.
+3. **Explicit imports**: MCP uses explicit imports (not `export *`) for auditability.
+4. **Three-way sync**: SDK ↔ Move ↔ MCP are kept consistent via automated tests.
+5. **On-chain vs SDK distinction**: When the SDK is stricter than on-chain, use `*_ONCHAIN` / `*_SDK` suffixes to make the difference explicit.
+6. **JSDoc with Move source**: Every constant's JSDoc must annotate the source Move file location.
+7. **Consumer mapping**: `ONCHAIN_CONSTANT_MCP_CONSUMERS` records where each constant is used in MCP for audit purposes.

package/scripts/install.js

@@ -160,6 +160,14 @@ function installSkills(targetDir, target) {
     console.log(`[wowok-skills]   installed: ${dir} → ${dest}`);
   }
 
+  // Copy references/ directory (shared reference docs linked by SKILL.md files)
+  const refsSrc = path.join(pkgRoot, 'references');
+  if (fs.existsSync(refsSrc)) {
+    const refsDest = path.join(targetDir, 'references');
+    copyDir(refsSrc, refsDest);
+    console.log(`[wowok-skills]   installed: references/ → ${refsDest}`);
+  }
+
   return count;
 }
 
@@ -175,6 +183,13 @@ function uninstallSkills(targetDir) {
     }
   }
 
+  // Remove references/ directory
+  const refsPath = path.join(targetDir, 'references');
+  if (fs.existsSync(refsPath)) {
+    removeDir(refsPath);
+    console.log(`[wowok-skills]   removed: ${refsPath}`);
+  }
+
   return count;
 }
 

package/wowok-onboard/APPENDIX.md

@@ -9,6 +9,18 @@
 
 Every round follows the same shape: state the goal, ask the key question(s), execute the MCP calls, verify success criteria, persist checkpoint, fall back on failure.
 
+## Project-Based Deployment Integration
+
+The onboarding flow is integrated with the MCP project-based 5-stage deployment pipeline. Each stage gates progression to the next, with `project_operation` action calls providing deterministic validation:
+
+- **Stage 1 (Project Naming)** → R1-R2 — establish `project` namespace and `version` for all subsequent calls
+- **Stage 2 (Business Puzzle)** → R2 calls `project_operation` → `action: "analyze_intent"` to obtain the Object Dependency Graph (ODG), missing field list (puzzles), and `next_step` guidance that drives R3-R8 field completion
+- **Stage 3 (Risk Calibration)** → after R8 checkpoint, calls `project_operation` → `action: "aggregate_risks"` to evaluate risk across all puzzles; CRITICAL risks block progression
+- **Stage 4 (Deployment Doc)** → once risks pass, calls `project_operation` → `action: "generate_deployment_doc"` to produce the deployment document; D-errors block progression to R9
+- **Stage 5 (Substep Trace)** → R9-R10 calls `project_operation` → `action: "trace_substeps"` to validate substep linkage integrity (D-10 check) before execution via `onchain_operations`
+
+All `project_operation` calls return a `can_proceed` boolean and a `next_action` hint. The onboarding AI MUST honor the gate semantics: stop on `can_proceed: false`, fix the reported issues, and only proceed when `can_proceed: true`.
+
 ### R1: Welcome + Account Setup
 
 **AI Goal**: Confirm the user is new (or resuming), establish the working account, fund it via faucet if empty.
@@ -28,7 +40,7 @@ Every round follows the same shape: state the goal, ask the key question(s), exe
 
 **Fallback**: Faucet fails → instruct user to wait 60s and retry, or fund via `transfer` from another account they own. Account name collision → append `_v1`, `_v2` per wowok-safety §1.1.
 
-**Checkpoint**: Persist `{ round: R1, account: <name>, balance: <n> }` via `local_info_operation`.
+**Checkpoint**: Persist `{ round: R1, account: <name>, balance: <n>, project: <project_name>, version: <version> }` via `local_info_operation`. The `project` and `version` fields establish the Stage 1 Project Naming namespace and MUST be carried forward in every subsequent `project_operation` call (Stage 2-5) and referenced in checkpoints R2-R10.
 
 ---
 
@@ -42,6 +54,7 @@ Every round follows the same shape: state the goal, ask the key question(s), exe
 - Will you need to ship physical goods?
 
 **Tool Calls**:
+0. `project_operation` → `action: "analyze_intent"` with `project`, `version`, `user_intent`, `industry` — 获取 ODG + 缺失字段清单 + 下一步建议。MCP 返回的 puzzles 和 next_step 指导后续 R3-R8 的字段补全。
 1. Internally classify the user's answers into `traits` (`has_logistics`, `communication_heavy`, `pure_digital`, `long_cycle`, `deposit_required`, `multi_tier_allocation`).
 2. Match to a mode via [wowok-scenario](../wowok-scenario/SKILL.md) §Mode Selection Logic:
    - freelance (Phase 1) — pure digital, no deposit, milestone allocation
@@ -73,7 +86,7 @@ Every round follows the same shape: state the goal, ask the key question(s), exe
 1. `onchain_operations` → `operation_type: "service"` with:
    - `data.name`, `data.type_parameter`, `data.description`
    - `data.permission` left empty for now (Permission comes in R4) OR pass a Permission object shape that auto-creates (wowok-safety §1.1 — SDK auto-creates a Permission if object shape passed)
-   - `publish: false` (mandatory — Service stays draft)
+   - `publish: false` (mandatory — **DRAFT** creation, Service stays draft until R10 publish; this is a deliberate two-phase pattern: draft in R3-R8 allows iterative MODIFY, then irreversible publish in R10)
    - `env.account` = R1 account
 2. (Optional, physical goods) `wip_file` → `generate` to produce WIP file URL + hash for product metadata
 3. `local_mark_operation` → tag the new Service with a friendly name (e.g., `freelance_logo_v1`)
@@ -204,6 +217,18 @@ Every round follows the same shape: state the goal, ask the key question(s), exe
 
 **Checkpoint**: Persist `{ round: R8, allocators: [{name, id, trigger_guard}], refund_path_covered: true }`.
 
+**Stage 3 Gate: Risk Calibration**
+After R8 checkpoint, call `project_operation` → `action: "aggregate_risks"` with `project`, `version`, `puzzles` (from R2's analyze_intent).
+- If `can_proceed: false` (CRITICAL risks) → fix risks before proceeding
+- If `can_proceed: true` → proceed to Stage 4
+- The `next_action` field tells you the next step
+
+**Stage 4 Gate: Deployment Document**
+After risks pass, call `project_operation` → `action: "generate_deployment_doc"` with `project`, `version`, `business_intent`, `objects`, `edges`, `steps`, `risk_status`, `risk_critical_count`, `risk_high_count`.
+- If `can_proceed: false` (D-errors) → fix doc errors
+- If `can_proceed: true` → proceed to R9 (deployment execution)
+- The `next_action` field tells you the next step
+
 ---
 
 ### R9: Test Order (Dry Run)
@@ -215,6 +240,9 @@ Every round follows the same shape: state the goal, ask the key question(s), exe
 - Confirm test parameters: test amount, test deliverable hash.
 
 **Tool Calls**:
+0. `project_operation` → `action: "trace_substeps"` with `project`, `version`, `network`, `substeps` (from Stage 4 deployment doc) — 验证子步骤衔接完整性 (D-10 check).
+   - If `can_proceed: false` → fix substep issues
+   - If `can_proceed: true` → execute substeps via onchain_operations
 1. `account_operation` → `gen` (second account, the "buyer")
 2. `account_operation` → `faucet` for the buyer
 3. `onchain_operations` → `operation_type: "order"` CREATE — buyer places order on the Service draft
@@ -244,9 +272,9 @@ Every round follows the same shape: state the goal, ask the key question(s), exe
    - `machineNode2file` → export Machine, verify topology
    - `guard2file` → export all Guards, verify logic
    - `query_toolkit` → `onchain_objects` → re-check Permission, Service, Machine, Progress, Guards, Allocation all exist and are correctly bound
-2. `onchain_operations` → `operation_type: "machine"` with `publish: true` — Machine locked
+2. **Publish Machine FIRST** — `onchain_operations` → `operation_type: "machine"` with `publish: true` (PUBLISH, irreversible). Machine locked. This MUST happen before Service publish because the Service depends on a published Machine.
 3. `onchain_operations` → `operation_type: "service"` MODIFY to bind `data.machine = "<published_machine_id>"`
-4. `onchain_operations` → `operation_type: "service"` with `publish: true` — Service locked
+4. **Publish Service SECOND** — `onchain_operations` → `operation_type: "service"` with `publish: true` (PUBLISH, irreversible). Service locked. Order is mandatory: **Machine first, then Service** (Service depends on Machine).
 5. (Optional) `onchain_operations` → `operation_type: "service"` MODIFY to add `compensation_fund_add` and `setting_locked_time_add`
 6. Post-publish verification:
    - `query_toolkit` → `onchain_objects` (Service) → confirm `bPublished: true`, `machine` field is locked, `order_allocators` is locked

package/wowok-planner/APPENDIX.md

@@ -9,6 +9,18 @@
 
 Each round follows: state the goal, ask the minimum questions needed, gather inputs (LLM translation only when free text is ambiguous), update the ODG in memory, persist checkpoint, advance.
 
+## Project-Based Deployment Integration
+
+The planner flow integrates with the MCP project-based deployment pipeline (5 stages). Each stage maps to specific R rounds:
+
+- **Stage 1 (Project Naming)** → R1 — establish the `project` and `version` identifiers used by all subsequent `project_operation` calls.
+- **Stage 2 (Business Puzzle)** → R1 — call `project_operation` → `action: "analyze_intent"` to replace internal Scenario Registry matching; the MCP side performs Scenario Registry matching + ODG skeleton generation + puzzle initialization in one call.
+- **Stage 3 (Risk Calibration)** → R9 — call `project_operation` → `action: "aggregate_risks"` to perform L1/L2/L3 risk assessment on the assembled puzzles.
+- **Stage 4 (Deployment Doc)** → after R9 — call `project_operation` → `action: "generate_deployment_doc"` to produce the markdown deployment doc with D-01..D-18 scanner checks.
+- **Stage 5 (Substep Trace)** → R10 — call `project_operation` → `action: "trace_substeps"` to verify substep continuity before handoff to the Harness.
+
+All `project_operation` calls use the unified `project` + `version` keys established in R1. The `next_action` field returned by each call drives the stage transition.
+
 ### R1: Intent Capture
 
 **AI Goal**: Capture the user's natural-language intent and classify it against the Scenario Registry.
@@ -20,7 +32,7 @@ Each round follows: state the goal, ask the minimum questions needed, gather inp
 
 **Tool Calls**:
 1. `query_toolkit` → `local_names` — check for any prior planning checkpoint to offer a resume path.
-2. (Internal) Match intent against the Scenario Registry §Intent Keywords. If two candidates score equally, ask one disambiguating question (LLM-translated to a typed choice).
+2. `project_operation` → `action: "analyze_intent"` with `project`, `version`, `user_intent`, `industry` (if known) — MCP 内部完成 Scenario Registry 匹配 + ODG 生成 + puzzle 初始化. Returns `puzzles`, `next_step`, `next_action`. If `next_action: "aggregate_risks"` indicates puzzles are complete, you can proceed directly to Stage 3.
 3. If no candidate matches → select `general` scenario (no failure — the fallback is intentional).
 
 **Success Criteria**: A `scenario` field is set on the ODG (one of `freelance`, `rental`, `digital_goods`, `travel_package`, `general`). The scenario's ODG template is loaded as the working skeleton.
@@ -193,6 +205,9 @@ Each round follows: state the goal, ask the minimum questions needed, gather inp
 - Confirm the fund-risk paths (deposit escrow, refund Allocator)?
 
 **Tool Calls**:
+0. `project_operation` → `action: "aggregate_risks"` with `project`, `version`, `puzzles` (from R1's analyze_intent) — MCP 内部完成 L1/L2/L3 风险评估. Returns `findings`, `can_proceed`, `next_action`.
+   - If `can_proceed: false` (CRITICAL risks) → record in ODG risk_assessment, block execution
+   - If `can_proceed: true` → proceed to Stage 4
 1. (Internal) Compute `reversible` per object (see §Reversibility Matrix).
 2. (Internal) Estimate `estimated_time` per phase from scenario template defaults (Tier 1 ≈ 10 min, Tier 2 ≈ 30 min, Tier 3 ≈ 60 min, excluding human response time).
 3. (Internal) List every object whose creation or publish is irreversible; require explicit per-item acknowledgment.
@@ -203,6 +218,12 @@ Each round follows: state the goal, ask the minimum questions needed, gather inp
 
 **Checkpoint**: Persist `{ round: R9, risk_assessment, acknowledgments: [...] }`.
 
+**Stage 4 Gate: Deployment Document**
+After risks pass, call `project_operation` → `action: "generate_deployment_doc"` with `project`, `version`, `business_intent`, `objects`, `edges`, `steps`, `risk_status`, `risk_critical_count`, `risk_high_count`.
+- Returns markdown deployment doc + D-01..D-18 scanner checks
+- If `can_proceed: false` (D-errors) → fix doc errors
+- If `can_proceed: true` → proceed to R10
+
 ---
 
 ### R10: Execution Handoff
@@ -214,6 +235,9 @@ Each round follows: state the goal, ask the minimum questions needed, gather inp
 - Which execution delegate should run the phases? (default: wowok-onboard for a fresh build; wowok-provider for extensions)
 
 **Tool Calls**:
+0. `project_operation` → `action: "trace_substeps"` with `project`, `version`, `network`, `substeps` (from Stage 4 deployment doc) — 验证子步骤衔接完整性.
+   - If `can_proceed: false` → fix substep issues before handoff
+   - If `can_proceed: true` → handoff to Harness/wowok-onboard for execution
 1. (Internal) Emit the Harness handoff packet (see §Handoff Protocol).
 2. `local_info_operation` → persist the final ODG under a stable `task_id` key so the Harness can read it.
 3. (Internal) Register per-phase verification hooks: after each phase, the Harness must re-query on-chain state and reconcile with the ODG before advancing.