@wowok/skills 1.2.4 → 1.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wowok/skills",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "WoWok AI Skills for Claude and other AI assistants - Helping AI use WoWok MCP tools correctly",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,6 @@
   },
   "files": [
     "dist/",
-    "references/",
     "wowok-provider/",
     "wowok-arbitrator/",
     "wowok-guard/",
@@ -23,6 +22,7 @@
     "wowok-scenario/",
     "wowok-planner/",
     "wowok-auditor/",
+    "wowok-distill/",
     "examples/",
     "scripts/install.js",
     "README.md",

package/scripts/install.js

@@ -6,8 +6,8 @@
  *   preuninstall → remove SKILL.md folders from all installed client dirs
  *
  * Environment variables:
- *   WOWOK_SKILLS_TARGETS  Comma-separated client targets (claude,agents,codebuddy)
- *                         Defaults to "claude". Example: "claude,agents"
+ *   WOWOK_SKILLS_TARGETS  Comma-separated client targets (claude,codex,agents,codebuddy,cursor,copilot)
+ *                         Defaults to "claude". Example: "claude,agents,cursor"
  */
 
 const fs = require('fs');
@@ -28,6 +28,7 @@ const SKILL_DIRS = [
   'wowok-scenario',
   'wowok-planner',
   'wowok-auditor',
+  'wowok-distill',
 ];
 
 const CLIENT_DIRS = {
@@ -160,14 +161,6 @@ 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;
 }
 
@@ -183,13 +176,6 @@ 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-arbitrator/SKILL.md

@@ -18,7 +18,21 @@ when_to_use:
 
 Build trust through fair dispute resolution. Arbitration services enable neutral third parties to resolve conflicts between customers and merchants, earning fees while establishing on-chain reputation.
 
-> **Related Skills**: [wowok-order](../wowok-order/SKILL.md) (customer disputes), [wowok-provider](../wowok-provider/SKILL.md) (service arbitration config), [wowok-guard](../wowok-guard/SKILL.md) (voting_guard design), [wowok-machine](../wowok-machine/SKILL.md) (workflow analysis), [wowok-messenger](../wowok-messenger/SKILL.md) (evidence exchange), [wowok-safety](../wowok-safety/SKILL.md) (safety)
+> **Related Skills**: [wowok-order](../wowok-order/SKILL.md) (customer disputes), [wowok-provider](../wowok-provider/SKILL.md) (service arbitration config), [wowok-machine](../wowok-machine/SKILL.md) (workflow analysis), [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 no longer duplicates it:
+
+| Content | MCP Knowledge Module | Applied Via |
+|---------|---------------------|-------------|
+| Guard design rules (structural layers, data source classification, voting_guard table design) | `knowledge/guard-design-patterns.ts` (`GUARD_DESIGN_PATTERNS`) | `project_operation.aggregate_risks` (via `assessGuardRisks`) |
+| Safety rules (confirmation levels, immutability, object reuse) | `knowledge/safety-rules.ts` (`CONFIRMATION_RULES`) | Pre-publish checks + `project_operation.aggregate_risks` |
+| Arbitration-specific risks | `knowledge/arb-risk.ts` (`assessArbitrationRisks`) | `project_operation.aggregate_risks` |
+
+This Skill keeps the arbitration **conversation flow**, **evidence collection** scripts, and **dispute resolution** guidance — the MCP layer handles the rule evaluation.
 
 ---
 
@@ -50,13 +64,7 @@ User says "just make something up" → REFUSE and explain why each item matters.
 
 ### Information Collection Protocol
 
-```
-STEP 0: Present checklist R1-R6 to user
-├── Each item: "Reuse or create new? Provide details."
-├── Track status: [pending] / [confirmed: reuse <id>] / [confirmed: create]
-└── ⛔ GATE: ALL R1-R6 must be [confirmed] before any on-chain action
-    └── NOT confirmed → STOP. Ask. Do NOT suggest creating arbitration.
-```
+Present checklist R1-R6 to user. Each item: "Reuse or create new? Provide details." Track status: [pending] / [confirmed: reuse <id>] / [confirmed: create]. ⛔ GATE: ALL R1-R6 must be [confirmed] before any on-chain action — NOT confirmed → STOP. Ask. Do NOT suggest creating arbitration.
 
 All subsequent on-chain operations use R1 (Account) as `env.account`.
 
@@ -133,11 +141,10 @@ Customer dispute creates Arb directly at (1). State (0) entered only via `reset`
   - `FixedValue(u32)`: Equal weight for all qualified voters
   - `GuardIdentifier(u8)`: Dynamic weight from credential (e.g., reputation score, token balance)
 - Max 50 guards — enables tiered voting (experts + community, token-holders + NFT-holders)
-- **Guard table design**: When using `GuardIdentifier`, the referenced index must be a `b_submission: true` entry of **numeric type** (U8–U256). Its value is cast to u32 as the voter's weight. The `name` field of that entry should explain its purpose to Passport applicants.
 
 **Voting Flow**: Voter selects a voting guard → System verifies voter's Passport against that guard → Calculates weight based on guard's rule → Applies weight to selected propositions. One vote per voter per case.
 
-> **Guard Design Reference**: Voting guards follow the same construction as all Guards. See [wowok-guard](../wowok-guard/SKILL.md) for table design, computation trees, and the full type requirements by object.
+> **Guard Design Reference**: Voting guard construction rules (table design, computation trees, `GuardIdentifier` submission-type requirements) now live in the MCP knowledge layer — see `knowledge/guard-design-patterns.ts` (`GUARD_DESIGN_PATTERNS`), auto-applied via `project_operation.aggregate_risks`. Test voting logic with `gen_passport` before finalizing.
 
 ---
 
@@ -168,19 +175,7 @@ Customer dispute creates Arb directly at (1). State (0) entered only via `reset`
 
 ### Revenue Flow
 
-```
-Customer pays fee
-      │
-      ▼
-  Arb.fee (locked per case)
-      │
-      │ arb_withdraw()
-      ▼
-  Arbitration.balance
-      │
-      ├──→ Allocation (revenue sharing)
-      └──→ Treasury (controlled withdrawal)
-```
+Customer pays fee → locked in `Arb.fee` per case → `arb_withdraw()` transfers to `Arbitration.balance` → distributed via Allocation (revenue sharing) or Treasury (controlled withdrawal).
 
 ### Compensation System
 
@@ -217,20 +212,6 @@ Providers list approved Arbitrations in their Service. Customers choose from thi
 
 ## Quick Reference
 
-### Essential Operations
-
-| Operation | State | Purpose |
-|-----------|-------|---------|
-| `confirm` | (1)→(2) | Start voting, set deadline |
-| `reset` | (1)→(0), (4)→(0) | Request revision (requires feedback) |
-| `vote` | (2) | Cast weighted votes |
-| `arbitration` | (2)→(3) | Finalize verdict (**irreversible**) |
-| `arb_withdraw` | (5), (3), (4) | Extract fee (30-day wait if not finished) |
-
-### Common Workflows
-
-See [Core Architecture > Key Flows](#arb-state-machine) above.
-
 ### Critical Constraints
 
 - Max 20 propositions per case
@@ -241,14 +222,6 @@ See [Core Architecture > Key Flows](#arb-state-machine) above.
 - ⛔ `arbitration` verdict is **irreversible** by arbitrator — only customer can object
 - ⛔ `feedback` is **permanently public on-chain** — use Messenger for privacy-sensitive communication
 
-### Schema Access
-
-```javascript
-wowok({ tool: "schema_query", data: { action: "get", name: "onchain_operations_arbitration" } })
-wowok({ tool: "schema_query", data: { action: "get", name: "onchain_operations_order" } })
-wowok({ tool: "schema_query", data: { action: "get", name: "messenger_operation" } })
-```
-
 ---
 
 ## Best Practices
@@ -273,15 +246,3 @@ wowok({ tool: "schema_query", data: { action: "get", name: "messenger_operation"
 | **Unverified evidence** | Ruling based on invalid claims | Always verify WTS first |
 
 ---
-
----
-
-## Appendices (Progressive Disclosure)
-
-> The following sections have been extracted to [APPENDIX.md](./APPENDIX.md) for on-demand loading:
-> - Dialogue Scripts (R1-R10) — guided conversation scripts
-> - Decision Trees — branching logic reference
-> - Failure Playbooks — recovery scenarios
-> - Tier Layering — expertise-tier based guidance
->
-> Load APPENDIX.md when the user needs guided dialogue, recovery help, or tier-specific guidance.

package/wowok-auditor/SKILL.md

@@ -26,9 +26,23 @@ writes on-chain; it queries (`query_toolkit`, `onchain_events`), exports
 (`guard2file`, `machineNode2file`), evaluates rule tables, and emits a
 pass / warn / fail report. A FAIL blocks the publish in R10.
 
-> **Role**: Auditor (read-only). Sibling to [wowok-safety](../wowok-safety/SKILL.md) (pre-write gate) — safety runs on every write; auditor runs only on publish.
+> **Role**: Auditor (read-only). The pre-write safety gate now lives in the MCP knowledge layer (`knowledge/safety-rules.ts`), applied on every write; this auditor runs only on publish.
 > **Layer**: L3 Skill, knowledge base for L4 Verify Loop.
-> **Related Skills**: [wowok-safety](../wowok-safety/SKILL.md) (gate), [wowok-guard](../wowok-guard/SKILL.md) (Guard authoring), [wowok-machine](../wowok-machine/SKILL.md) (Machine design), [wowok-onboard](../wowok-onboard/SKILL.md) (publish flow), [wowok-tools](../wowok-tools/SKILL.md) (schema reference).
+> **Related Skills**: [wowok-machine](../wowok-machine/SKILL.md) (Machine design), [wowok-onboard](../wowok-onboard/SKILL.md) (publish flow).
+
+---
+
+## MCP Knowledge Layer
+
+The following content has been pushed down to the MCP knowledge layer and is applied automatically — this Skill no longer duplicates it:
+
+| Content | MCP Knowledge Module | Applied Via |
+|---------|---------------------|-------------|
+| Safety rules (confirmation levels, immutability rules, object reuse rules) | `knowledge/safety-rules.ts` (`CONFIRMATION_RULES`, `ConfirmLevel`) | Pre-publish checks + `project_operation.aggregate_risks` |
+| Machine-executable audit rules | `knowledge/audit-rules.ts` (`AUDIT_RULES`, `auditService`) | `project_operation.aggregate_risks` |
+| Guard completeness / Machine soundness / fund-flow risks | `knowledge/guard-risk.ts`, `machine-risk.ts`, per-object risk modules | `project_operation.aggregate_risks` (via per-object assessors) |
+
+This Skill keeps the **audit flow**, the **4 audit dimensions** (Guard completeness, Machine soundness, fund flow, publish readiness), and the **checklist structure** as the human-readable knowledge base for the L4 Harness Verify Loop. The MCP layer runs the machine-executable rule evaluation.
 
 ---
 
@@ -98,13 +112,3 @@ pass / warn / fail report. A FAIL blocks the publish in R10.
 | Backup export | `machineNode2file` + `guard2file` backups persisted | WARN: no backup |
 
 ---
-
-## Appendices (Progressive Disclosure)
-
-> The following sections have been extracted to [APPENDIX.md](./APPENDIX.md) for on-demand loading:
-> - Dialogue Scripts (R1-R10) — guided conversation scripts
-> - Decision Trees — branching logic reference
-> - Failure Playbooks — recovery scenarios
-> - Tier Layering — expertise-tier based guidance
->
-> Load APPENDIX.md when the user needs guided dialogue, recovery help, or tier-specific guidance.

package/wowok-distill/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: wowok-distill
+description: |
+  WoWok Distillation Review Orchestrator — guides merchants through reviewing and applying
+  AI-generated improvement proposals from the Loop Engineering flywheel.
+
+  This skill is a STATELESS CONVERSATION ORCHESTRATOR (per GLM5 §6.3): it does not hold
+  persistent state. All data comes from MCP project_operation actions:
+    - get_improvement_queue: list pending/approved proposals
+    - apply_improvement: review + apply a proposal (config_override or source_patch)
+    - get_flywheel_config: query reflow loop status
+
+  Use when: user asks "what improvements are suggested?", "show me optimization proposals",
+  "what did the system learn from my operations?", or wants to review/apply/reject
+  improvement proposals generated by the offline flywheel.
+when_to_use:
+  - User asks about improvement suggestions or optimization proposals
+  - User wants to review what the flywheel has learned from their operations
+  - User wants to apply or reject a distillation proposal
+  - User mentions "improvement", "optimization", "flywheel", "distillation", "proposal", "override"
+  - User wants to see how their operational patterns have evolved
+---
+
+# WoWok Distillation Review Orchestrator
+
+> **Role**: Distillation Review Orchestrator (Stateless)
+> **Design**: GLM5 §6.3-§6.4 — zero persistent state, all data from MCP actions
+> **Related Skills**: [wowok-provider](../wowok-provider/SKILL.md) (merchant context), [wowok-tools](../wowok-tools/SKILL.md) (MCP tool usage)
+
+---
+
+## Core Concept
+
+The WoWok MCP server runs an offline flywheel (Loop Engineering pipeline) that:
+1. Collects operational signals from your project deployments
+2. Updates industry cognition (trait drift, health scores)
+3. Generates improvement proposals (risk threshold tweaks, description refinements, scenario defaults)
+4. Persists proposals to `~/.wowok/improvement-queue.jsonl`
+
+**This skill helps you review and act on those proposals.** It is a conversation orchestrator —
+it asks questions, presents proposals in human-readable form, and calls MCP actions to apply
+your decisions. It does NOT hold state between conversations.
+
+---
+
+## Orchestration Flow (6 Steps)
+
+### Step 1: Retrieve the Improvement Queue
+
+Call the MCP `project_operation` action with:
+```json
+{
+  "action": "get_improvement_queue",
+  "queue_filter_status": "pending"
+}
+```
+
+This returns a list of pending proposals. Each proposal has:
+- `proposal_id`: unique identifier
+- `type`: proposal category (risk-threshold / descriptions / industry-profiles / scenario-defaults / recovery-priorities)
+- `priority`: P0 (critical) / P1 (high) / P2 (medium) / P3 (low)
+- `title`: short description
+- `description`: detailed explanation
+- `confidence`: 0.0-1.0 (how confident the flywheel is)
+- `apply_mode`: "config_override" (writes to ~/.wowok/overrides/) or "source_patch" (produces patches/)
+- `proposed_change`: the specific change being proposed
+
+### Step 2: Present Proposals with Narrative
+
+For each proposal, present to the user:
+
+```
+📋 Proposal [P1] proposal-001: "Lower retry threshold for rental deposits"
+
+   Type: risk-thresholds
+   Confidence: 0.82 (high)
+   Apply Mode: config_override (safe — writes to ~/.wowok/overrides/risk-thresholds.json)
+
+   Current: max_deposit_retries = 5
+   Proposed: max_deposit_retries = 3
+
+   Rationale: Based on 23 rental operations analyzed, 92% of successful deposits
+   complete within 3 retries. Reducing the threshold saves gas on failed retries
+   without impacting success rate.
+
+   Impact: Affects rental industry profile only. No effect on other industries.
+```
+
+### Step 3: Explain the "Why" (Narrative)
+
+Use the proposal's `description` and `evidence` fields to explain:
+- **What pattern was detected** in the user's operational history
+- **Why the flywheel recommends this change** (data-driven, not opinion)
+- **What happens if applied** (immediate effect on future operations)
+- **What happens if rejected** (no change — proposal stays in queue as "rejected")
+
+### Step 4: Guide User Decision
+
+Present three options for each proposal:
+
+| Option | Action | MCP Call |
+|--------|--------|----------|
+| **Apply** | Approve + apply immediately | `apply_improvement` with `review_status: "approved"` |
+| **Reject** | Mark as not wanted | `apply_improvement` with `review_status: "rejected"` |
+| **Later** | Skip for now (stays pending) | No call — move to next proposal |
+
+### Step 5: Execute the Decision
+
+When the user chooses "Apply", call:
+```json
+{
+  "action": "apply_improvement",
+  "proposal_id": "proposal-001",
+  "review_status": "approved"
+}
+```
+
+The MCP server will:
+- For `config_override`: write the override to `~/.wowok/overrides/<category>.json`
+- For `source_patch`: produce a patch file in `~/.wowok/patches/`
+- Update the proposal status to "applied"
+- Refresh the knowledge layer cache (so future actions use the new config)
+
+### Step 6: Confirm the Result
+
+After applying, present:
+```
+✅ Proposal proposal-001 applied successfully!
+
+   Override written to: ~/.wowok/overrides/risk-thresholds.json
+   Effect: Future rental operations will use max_deposit_retries=3
+
+   The knowledge layer has been refreshed. New operations will use the updated
+   threshold immediately. No restart needed.
+```
+
+---
+
+## Flywheel Status Query
+
+If the user asks about the overall flywheel status (not specific proposals), call:
+```json
+{
+  "action": "get_flywheel_config"
+}
+```
+
+This returns:
+- `queue_path`: where proposals are stored
+- `overrides_dir`: where overrides live
+- `patches_dir`: where patches are produced
+- `total_proposals` / `pending_count` / `approved_count` / `applied_count` / `rejected_count`
+- `override_files`: list of existing override files
+- `recent_proposals`: recent 10 proposals (all statuses)
+- `reflow_status`: "active" (pending proposals exist) / "idle" (no proposals) / "blocked" (approved but not applied)
+
+---
+
+## Override Categories (§4.4 Whitelist)
+
+Only these 5 categories can be overridden via `config_override`:
+
+| Category | Description | Example |
+|----------|-------------|---------|
+| `risk-thresholds` | Risk assessment thresholds | max_retries, min_deposit, severity_cutoffs |
+| `descriptions` | Text descriptions for AI guidance | industry descriptions, role advice |
+| `industry-profiles` | Industry trait profiles | rental traits, freelance traits |
+| `scenario-defaults` | Default parameters per scenario | default allocators, default machine nodes |
+| `recovery-priorities` | Error recovery priority orders | which failures to fix first |
+
+**Source patches** (`source_patch` mode) are for changes that can't be expressed as config
+overrides — they produce `.patch` files that the user can manually review and apply to the
+MCP source code.
+
+---
+
+## Conversation Patterns
+
+### Pattern A: "What improvements do you have?"
+
+```
+User: What improvements do you have for me?
+AI: Let me check your improvement queue...
+    [calls get_improvement_queue with queue_filter_status="pending"]
+AI: You have 3 pending proposals:
+    1. [P1] Lower retry threshold for rental deposits (confidence: 82%)
+    2. [P2] Update freelance industry description (confidence: 71%)
+    3. [P3] Adjust default allocator for travel scenarios (confidence: 65%)
+    Would you like to review them one by one?
+```
+
+### Pattern B: "Tell me more about proposal 1"
+
+```
+User: Tell me more about proposal 1
+AI: 📋 Proposal proposal-001: "Lower retry threshold for rental deposits"
+    ...
+    [presents full details per Step 2-3]
+    Would you like to Apply, Reject, or review later?
+```
+
+### Pattern C: "Apply proposal 1"
+
+```
+User: Apply proposal 1
+AI: Applying proposal-001...
+    [calls apply_improvement with proposal_id="proposal-001", review_status="approved"]
+AI: ✅ Applied! The override is now active.
+    Next rental operations will use the new threshold.
+```
+
+---
+
+## Version Negotiation
+
+When the MCP server is upgraded, this skill automatically negotiates compatibility:
+
+| Version Difference | Skill Behavior | User Impact |
+|-------------------|----------------|-------------|
+| MCP major > skill major | **Passthrough** — skill only forwards MCP responses, no orchestration | Reduced narrative, MCP actions still work |
+| MCP minor > skill minor | **Full** — skill works normally, new MCP actions may not be orchestrated | Some new features need client AI to handle |
+| Versions match | **Full** — best experience | Optimal |
+
+The user does not need to manage this — the skill detects the MCP version from the
+`get_flywheel_config` response and adapts automatically.
+
+---
+
+## Anti-Patterns
+
+| Never... | Because... |
+|----------|------------|
+| Fabricate proposal content | Proposals come from data-driven flywheel analysis — always use MCP data |
+| Apply proposals without user confirmation | Overrides affect future operations — user must explicitly approve |
+| Skip the narrative explanation | User needs to understand WHY before deciding |
+| Hold conversation state between sessions | This skill is stateless — re-fetch from MCP each time |
+| Modify the improvement-queue.jsonl directly | Always use `apply_improvement` action for audit trail |