@wowok/skills 2.1.3 → 2.2.1

package/wowok-order/SKILL.md

@@ -1,25 +1,44 @@
 ---
 name: wowok-order
 description: |
-  WoWok Customer Guide — complete buyer order lifecycle: pre-purchase due diligence
-  (E1-E11), consensus building, order creation, progress advancement, and arbitration.
+  WoWok Buyer Guide — TWO lifecycles in one skill:
+
+  1. PROSPECT (潜在用户尽调, pre-purchase): E1-E11 due diligence + consensus
+     building + trust-score synthesis, ending in a buy/no-buy decision.
+  2. CUSTOMER (已下单履约, post-order): order creation, progress advancement,
+     fund management, and arbitration.
+
+  For suppliers presenting to Demands, see wowok-supplier. For process
+  operators executing workflow forwards, see wowok-collaborator.
 when_to_use:
-  - User is a customer/buyer placing or managing orders
-  - User wants to evaluate services before purchasing
+  - User is a potential buyer evaluating a service BEFORE purchasing (prospect)
+  - User is a customer/buyer placing or managing orders (customer)
+  - User wants to evaluate services, WIP, guards, allocations, arbitration
   - User needs to communicate with sellers via Messenger
   - User asks about order progress, payments, or refunds
   - User wants to file disputes or arbitration claims
-  - User mentions "buy", "order", "purchase", "refund", "dispute", "arbitration"
+  - User mentions "buy", "order", "purchase", "refund", "dispute", "arbitration", "due diligence"
 ---
 
-# WoWok Customer Guide
+# WoWok Buyer Guide
 
-> **Role**: Customer (Buyer/Order Holder)
-> **Guides**: [wowok-provider](../wowok-provider/SKILL.md) · [wowok-arbitrator](../wowok-arbitrator/SKILL.md) · [wowok-machine](../wowok-machine/SKILL.md) · [wowok-messenger](../wowok-messenger/SKILL.md)
+> **Role**: Buyer — two lifecycles: **Prospect** (pre-purchase due diligence) → **Customer** (post-order fulfillment)
+> **Guides**: [wowok-provider](../wowok-provider/SKILL.md) · [wowok-supplier](../wowok-supplier/SKILL.md) · [wowok-arbitrator](../wowok-arbitrator/SKILL.md) · [wowok-machine](../wowok-machine/SKILL.md) · [wowok-messenger](../wowok-messenger/SKILL.md)
 > Guard patterns / safety rules / tool references live in the MCP knowledge layer — query via `schema_query` (`get_guard_design_patterns`, `get_safety_rules`, `get_tool_reference`).
 
 ---
 
+## Two Lifecycles
+
+| Lifecycle | Role | Phases | Ends with |
+|-----------|------|--------|-----------|
+| **Prospect** (潜在用户尽调) | You have NOT ordered yet | Phase 1 (E1-E11) + Phase 2 | buy / no-buy decision |
+| **Customer** (已下单履约) | You are the Order `builder` | Phase 3-6 + Fund Management | funds withdrawn / dispute resolved |
+
+The prospect lifecycle is served primarily by MCP `trust_score` (`depth: "preorder"`) and the plug-in `evaluation_operation` — this skill keeps the dialogue flow. The customer lifecycle is on-chain (Order/Progress/Allocation/Arb).
+
+---
+
 ## Core Concepts (Design Invariants Not in Schema)
 
 - **Objects**: Purchase creates **Order** (fund escrow, you are `builder`), **Progress** (Machine node tracker), **Allocation** (fund distribution). Only `builder` withdraws; agents operate but never access funds.
@@ -29,7 +48,7 @@ when_to_use:
 
 ---
 
-## Phase 1: Pre-Purchase Due Diligence (MANDATORY GATE)
+## Phase 1: Pre-Purchase Due Diligence (PROSPECT lifecycle — MANDATORY GATE)
 
 > **⛔ Complete E1-E11 in order; user must confirm every item.** **⚠️** = explain risk, wait. **🔴** = strongly advise against.
 
@@ -177,7 +196,7 @@ Clarify via Messenger: deliverables (E2 WIP), timeline (E3 nodes), refund/cancel
 
 ---
 
-## Phase 3: Order Creation
+## Phase 3: Order Creation (CUSTOMER lifecycle)
 
 Not in schema: excess `buy.total_pay` auto-refunded; agents cannot withdraw. Discounts: query `onchain_received` (type `0x2::service::Discount`), filter by `service`, validate time/benchmark; rate = `total_pay × (off / 10000)`; fixed = `min(off, total_pay)`. Post-creation: notify via Messenger with order ID.
 

package/wowok-provider/SKILL.md

@@ -235,6 +235,6 @@ Before forking, verify necessity via `get_project_detail` → `has_published_obj
 
 **AI Reminder**: When fulfilling, check `customer_required` fields. Missing → prompt via Messenger.
 
-**Demand/service matching** (`evaluation_operation`): `demand_match` ranks candidate services for a demand capability vector; `service_match` is the reverse; `capability_gap` lists unmet requirements; `compose_service` combines services to cover a demand. Read-only — the merchant decides whether to `present` (`onchain_operations` → `demand` → `present_service`).
+**Demand/service matching** (`evaluation_operation`): `demand_match` ranks candidate services for a demand capability vector; `service_match` is the reverse; `capability_gap` lists unmet requirements; `compose_service` combines services to cover a demand. Read-only — the merchant decides whether to `present` (`onchain_operations` → `demand` → `present` with `recommend`/`by_guard`/`service`).
 
 ---

package/wowok-supplier/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: wowok-supplier
+description: |
+  WoWok Supplier — the canonical skill for suppliers (sub-order providers) who
+  present their service to a Demand and fulfill the resulting sub-order.
+
+  Covers demand discovery, service presentation (open or passport-gated),
+  sub-order fulfillment via Progress, and settlement collection. The supplier
+  is a PEER role with a two-sided position: deliver (to get paid) + collect
+  (from the upstream merchant).
+
+  For the merchant who owns the main Service, see wowok-provider. For the
+  process operators executing the workflow, see wowok-collaborator.
+when_to_use:
+  - User wants to present their service to a Demand (open RFP or gated call)
+  - User is a sub-order provider / supplier fulfilling part of a transaction
+  - User wants to collect settlement from an upstream merchant
+  - User mentions "supplier", "sub-order", "demand", "present service", "RFP", "fulfill sub-order"
+---
+
+# WoWok Supplier Guide
+
+> **Role**: Supplier (sub-order provider / Demand presenter)
+> **Related Skills**: [wowok-provider](../wowok-provider/SKILL.md) (main merchant), [wowok-collaborator](../wowok-collaborator/SKILL.md) (process operators), [wowok-machine](../wowok-machine/SKILL.md) (workflow), [wowok-messenger](../wowok-messenger/SKILL.md) (evidence exchange)
+
+---
+
+## MCP Knowledge Layer
+
+The following content has been pushed down to the MCP knowledge layer and is applied automatically — this Skill does NOT duplicate it:
+
+| Content | Access via (MCP action) | Applied Via |
+|---------|--------------------------|-------------|
+| Demand semantics (open vs guarded, present paths) | `schema_query` action='get' (demand object schema, or on-demand knowledge) | `onchain_operations` demand |
+| Supplier interest analysis (fund_flow / responsibility / leverage / stakes) | `project_operation` action='participation_radar' | role derivation → `supplier-interest` |
+| Demand/service matching | `evaluation_operation` action='demand_match' | read-only ranking |
+| Safety rules (immutability, object reuse, confirmation) | `schema_query` action='get_safety_rules' | `evaluate_project` + pre-publish |
+
+This Skill keeps the supplier **conversation flow** — discover → present → fulfill → collect. The MCP layer handles rules, matching, and own-interest surfacing.
+
+---
+
+## Role: the two-sided supplier
+
+The supplier is a **peer** (not weak like the customer, not strong like the merchant). Its position is two-sided:
+
+1. **DELIVER** — fulfill the sub-order deliverable to unlock settlement.
+2. **COLLECT** — collect the settlement share from the upstream merchant.
+
+Your payment is a two-hop waterfall: main order escrow → allocation → your sub-order. You must protect BOTH sides — a delivery you can't prove is unpaid work; an upstream stall you don't chase is a lost claim.
+
+---
+
+## Core Interaction Principles
+
+1. **Review-first**: State (a) what the AI understood, (b) the decision order, and (c) the interaction contract — before the first choice.
+2. **User-driven**: Every step is an explicit user decision; the AI provides a `recommend` but never auto-advances.
+3. **Reuse / Customize / Discover (三选一)**: For every component (service, passport, guard), surface reuse / customize / discover.
+4. **Default-config disclosure**: Disclose defaults + caveats BEFORE the user decides.
+
+---
+
+## ⚠️ PRE-FLIGHT: Before Presenting to a Demand
+
+Before ANY presentation, confirm with the user. **Do NOT fabricate, do NOT auto-present.**
+
+| # | Item | User Must Provide | Why Not Fabricate |
+|---|------|-------------------|--------------------|
+| **S1** | **Account** | Which account operates. Default `""`. | Safe default exists |
+| **S2** | **Target Demand** | Which Demand to present to (name/address). | You don't know which RFP they're answering |
+| **S3** | **Service to present** | Which Service represents their offering. | It's their brand/offering identity |
+| **S4** | **Passport (if gated)** | A valid Passport passing the Demand's guards. | Guards filter presentations; wrong passport = rejection |
+
+> ⛔ GATE: S1-S4 confirmed before calling `present` (with `by_guard` for guarded demands). Not confirmed → STOP and ask.
+
+---
+
+## Phase 1: Discover & Present
+
+**Discover** — `query_toolkit` / `onchain_objects` to list open Demands. A Demand is a user's service request with optional reward; presenters submit proposals.
+
+**Match** — `evaluation_operation` action='demand_match' ranks whether your service fits the Demand's capability vector. Read-only; you decide whether to present.
+
+**Present** — `onchain_operations` operation_type='demand':
+- Open Demand → `present`.
+- Guarded Demand → `present` with `by_guard` (a Passport that passes one of the Demand's guards).
+
+> The Demand's `presenters` table records your submission (recommend / service / acceptance_score). The creator may give `feedback` + an `acceptance_score` — that is the selection signal.
+
+---
+
+## Phase 2: Fulfill the Sub-order
+
+If selected, you receive a sub-order. Fulfill it via Progress (same routing rule as the provider):
+
+- Empty `namedOperator` (`""`) → `order.progress`
+- Non-empty role name or `permissionIndex` → `progress.operate`
+- Guard-gated forwards need `b_submission` (evidence) entries.
+
+Upload delivery evidence (Repository/proof) BEFORE advancing — it protects your payment claim and pre-builds your arbitration defense.
+
+---
+
+## Phase 3: Collect Settlement
+
+Your settlement is released through the allocation waterfall when the sub-order completes. It is NOT automatic — verify your share arrived (query your sub-order's Allocation/Treasury).
+
+If the upstream merchant stalls or withholds, escalate in order:
+1. Messenger nudge (WTS evidence).
+2. Arbitration (if the upstream Service binds one).
+3. On-chain reputation — the loss is permanent and public.
+
+---
+
+## Own-Interest Surfacing
+
+Run `project_operation` action='participation_radar' with your account + sub-order progress. The MCP derives your role (supplier) and attaches `supplier-interest` (fund_flow / responsibility / leverage / stakes). Present it as neutral information — the supplier decides.
+
+---
+
+## Design Principles
+
+- **Prove before you advance**: evidence first, then execute.
+- **Protect both sides**: deliver AND collect — neglect either and you lose.
+- **Match honestly**: presenting to every Demand dilutes your reputation; present only where you genuinely fit.
+- **Neutrality**: the AI surfaces trade-offs, never chooses the branch for you.
+
+## Quick Reference
+
+- Open Demand → `present`; Guarded Demand → `present` with `by_guard`.
+- Guarded Demand accepts only Passports that pass its guards.
+- Settlement is two-hop (main order → allocation → sub-order) — verify the second hop too.
+- Upstream compensation_fund is your recourse for unpaid work; empty fund = refund + reputation only.