@wowok/skills 3.1.2 → 3.2.1

package/wowok-auditor/SKILL.md

@@ -2,7 +2,7 @@
 name: wowok-auditor
 description: "WoWok pre-publish auditor — the static-analysis Skill that verifies Guard completeness, Machine soundness, fund-flow safety, permission consistency, and publish readiness BEFORE any irreversible publish operation (Service publish, Machine publish, Allocator binding freeze). This Skill is the orchestration guide for the L4 Harness Verify Loop. It does not mutate objects. It triggers the MCP risk engine, gathers evidence, and presents a pass/warn/fail report plus a publish decision. Use when: User is about to publish a Service, Machine, or lock an Allocator set; User asks to \"audit\", \"verify\", \"review\", \"check before publish\"; L4 Harness Verify Loop is invoked before an irreversible operation; User mentions \"fund flow\", \"refund path\", \"allocation sum\", \"guard completeness\"; User mentions \"machine cycle\", \"unreachable state\", \"permission index conflict\"; User wants a pre-publish go/no-go decision; A publish operation failed and root-cause analysis is needed."
 metadata:
-  version: "2.1.0"
+  version: "2.1.1"
   role: shared
   related: "wowok-planner, wowok-provider, wowok-machine"
 ---
@@ -39,7 +39,7 @@ Run an audit immediately before any irreversible operation:
 
 1. **Service publish** — machine bound + published, allocators locked, arbitration/compensation invariants, buy_guard, contact, permission indices.
 2. **Machine publish** — nodes/pairs/forwards become immutable afterward.
-3. **Allocator-set freeze** (`order_allocators` bind) — fund-flow paths lock with the Service.
+3. **Service fund-template lock** — `order_allocators` (the order distribution template and its trigger guards) is a Service create/update FIELD that becomes permanently immutable at `publish=true`; there is no separate bind op.
 4. **Post-failure root-cause analysis** — a publish/assert failed (e.g. `E_ARBITRATION_NOT_SET_WITH_COMPENSATION_FUND`, `E_ARBITRATION_PERMISSION_CONFLICT`); re-run to identify every remaining blocker, not just the one that aborted.
 
 Scope adapts to blast radius: a single Service with no Machine skips machine checks automatically; a stack with cross-Machine supply chains runs the full chain. The engine derives applicable checks from the objects — do not hand-pick rules.
@@ -83,7 +83,7 @@ Presentation rules:
 
 1. **FAIL blocks, WARN asks, PASS is silent.** CRITICAL/blocked findings are hard stops fixed by the owning Skill; MEDIUM/LOW are surfaced as advisories.
 2. **Blast-radius first**: order findings by irreversibility — a post-publish Guard logic bug is permanent; an untested Guard or missing backup is recoverable.
-3. Report grouped by the four coverage dimensions — **Guard completeness, Machine soundness, fund flow, publish readiness** — and state explicitly which objects were in scope. The individual checks inside each dimension are whatever MCP currently evaluates; quote the finding text returned, never a local rule list.
+3. Group by the five coverage aspects — **Guard completeness, Machine soundness, fund-flow safety, permission consistency, publish readiness** (map each finding via its returned `object_type` and `risk_rule_id`), and state explicitly which objects were in scope. Quote the finding text the engine returns; never maintain a local rule list.
 
 ---
 

package/wowok-collaborator/SKILL.md

@@ -2,7 +2,7 @@
 name: wowok-collaborator
 description: "WoWok Collaborator — the canonical skill for process collaborators who execute workflow forwards on behalf of a merchant: internal staff (permission entities) and external operators (named operators). Covers permission-index and named-operator routing, guard-gated evidence submission, and reputation protection. The collaborator carries PROCESS responsibility (no direct settlement stake) — the goal is to keep the workflow flowing and avoid stall blame. For the merchant who owns the Service, see wowok-provider. For the supplier who presents to Demands, see wowok-supplier. Use when: User is an operator/employee executing workflow steps (permission index); User is an external named operator advancing a Machine forward; User wants to submit guard evidence (proof/repository) for a forward; User mentions \"collaborator\", \"operator\", \"permission index\", \"named operator\", \"execute forward\"."
 metadata:
-  version: "2.0.0"
+  version: "2.1.0"
   role: collaborator
   related: "wowok-provider, wowok-machine, wowok-messenger"
 ---
@@ -11,88 +11,48 @@ metadata:
 
 > **Role**: Collaborator (internal permission entity OR external named operator)
 > **Related Skills**: [wowok-provider](../wowok-provider/SKILL.md) (merchant), [wowok-machine](../wowok-machine/SKILL.md) (workflow), [wowok-messenger](../wowok-messenger/SKILL.md) (evidence exchange)
+> Mechanics — routing, permission indexes, guard field lists, thresholds — are emitted by the MCP per query. Read them from the output; do not hand-maintain them here. Guard patterns: `schema_query` (`get_guard_design_patterns`, `get_safety_rules`).
 
----
-
-## 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 |
-|---------|--------------------------|-------------|
-| Collaborator interest analysis (fund_flow / responsibility / leverage / stakes) | `query_toolkit` query_type='participation_radar' | role derivation → `collaborator-interest` |
-| Progress routing rule (namedOperator vs permissionIndex) | `schema_query` action='get_safety_rules' | `onchain_operations` progress/order |
-| Guard design + submission patterns | `schema_query` action='get_guard_design_patterns' | guard-gated forwards |
-| Node game (threshold cooperation) | `evaluation_operation` action='node_game' | multi-role forward evaluation |
+## What is pushed down (do not duplicate)
 
-This Skill keeps the collaborator **conversation flow** — what you can execute now, what evidence to submit, and how to stay in scope.
-
----
+| Capability | Where it surfaces |
+|---|---|
+| What you can execute now, and how | `query_toolkit` `participation_radar` — `operable[]` with per-forward `execution_path`, `permission_index` / `named_operator`, `guard`, and **`recommended_call`** |
+| Concrete execution route | each operable forward's **`recommended_call`** (`tool` + `path` + `reason`) — the single source of truth; never hand-route from operator names |
+| Interest analysis | radar `interest_analysis` (fund_flow / responsibility / leverage / stakes), derived as `collaborator-interest` |
+| Guard design & safety rules | `schema_query` `get_guard_design_patterns` / `get_safety_rules` |
+| Threshold cooperation (multi-contributor forwards) | `evaluation_operation` action `node_game` |
 
 ## Role: process responsibility, not settlement
 
-The collaborator has **no direct settlement stake**. Your compensation is typically outside the on-chain order (salary/contract) unless the allocation explicitly routes a slot to you. Your stake is **reputation** — the stall/dispute metrics are public and read by future counterparties.
-
-Two sub-kinds (derived on-chain, never asserted):
-- **permission entity** (internal staff): granted a `permissionIndex` in the Service's Permission.
-- **named operator** (external): resolved via Progress.namedOperator → LocalMark.
-
----
-
-## Core Interaction Principles
-
-1. **Review-first**: State what you understand + what you can execute + the interaction contract before acting.
-2. **User-driven**: the AI surfaces options; you decide; never auto-advance.
-3. **Stay in scope**: only execute forwards your permission/named-operator grants — out-of-scope action creates semantic responsibility without authority.
-4. **Default-config disclosure**: disclose defaults + caveats before acting.
-
----
-
-## What You Can Execute Now
-
-Run `query_toolkit` query_type='participation_radar' with `radar_account` (your account) and `radar_targets: [{ progress: <the order's Progress object>, order: <the Order, optional but recommended> }]` (1–20 targets). It returns:
+- You typically have **no direct settlement stake** (compensation is salary/contract off-chain, unless an Allocation slot explicitly routes to you).
+- Your real stake is **reputation**: stall and dispute metrics are public and read by future counterparties.
+- Sub-kind is **derived on-chain, never asserted**: `permission_entity` (granted a permission index in the Service's Permission) or `named_operator` (Progress.namedOperator → LocalMark). The radar tells you which.
 
-- `operable` — forwards YOU can execute right now (permission / named-operator path).
-- `waiting_on` — what the workflow waits on from other roles.
-- `collaborator_kind` — internal vs external.
-- `interest_analysis` → `collaborator-interest` (fund_flow / responsibility / leverage / stakes).
+## Working procedure
 
-Present it neutrally; the collaborator decides.
-
----
+1. **Review-first**: state what you understood, what the account can execute, and the interaction contract before acting.
+2. **Read the radar**: `query_toolkit` `participation_radar` with `radar_account` and `radar_targets: [{ progress, order? }]` (1–20 targets). Present `operable` neutrally; if `branch_choice` is present, the user picks the branch — never auto-advance.
+3. **Execute per `recommended_call`**: call exactly the tool/path the forward gives (the reason text carries the failure code you would hit on the wrong path). No `recommended_call` → that forward is not executable by this account; say so instead of trying.
+4. **Stay in scope**: only execute forwards the account's permission/named-operator grants. Out-of-scope action creates semantic responsibility without authority.
 
-## Routing
+## Guard-gated forwards
 
-- Empty `namedOperator` (`""`) → `order.progress` (the order holder, NOT you).
-- Non-empty role name → `progress.operate` with the named operator.
-- `permissionIndex` → `progress.operate` with your granted index.
-
-Wrong path → "Permission denied" (abort code 5). The MCP safety rules carry the authoritative classification.
-
----
-
-## Guard-gated Forwards
-
-A forward with a guard requires a `b_submission` (retained submission) before execution. Prepare your evidence (Repository/proof) in advance:
-
-1. Upload evidence (Repository/proof data).
-2. Execute the forward (two-phase: call → submission prompt → re-call with submission).
-3. Advance the workflow.
-
-Uploading evidence BEFORE executing reduces dispute probability and pre-builds the merchant's arbitration defense — your diligence is visible on-chain.
-
----
+- The forward's `guard` field (and `workflow_operation` `list`/`task` → `options[].guard_submissions`) tells you exactly which `b_submission` fields must be supplied (name, value type, object type).
+- Prepare evidence (Repository / Proof) **before** executing; exchange it via Messenger when it comes from another party.
+- Execute once, with the `submission` values attached to the same call. Pre-uploading evidence reduces dispute probability and builds the merchant's arbitration defense — your diligence is visible on-chain.
 
-## Design Principles
+## Principles
 
-- **Momentum**: advance when you can; the stall is publicly visible.
-- **Scope discipline**: never interfere outside your permission/named-operator scope.
-- **Evidence first**: guard-gated forwards are only as strong as the submission behind them.
-- **Neutrality**: the AI surfaces trade-offs, never chooses the branch for you.
+- **Momentum**: advance when you can; a stall is publicly visible.
+- **Scope discipline**: never interfere outside your granted forwards.
+- **Evidence first**: a guarded forward is only as strong as its submission.
+- **Neutrality**: surface trade-offs and options; the role decides, you do not.
+- **Defaults disclosed**: disclose defaults and caveats before acting.
 
-## Quick Reference
+## Quick reference
 
-- You carry no settlement stake — your currency is reputation.
-- `permissionIndex` → `progress.operate`; `namedOperator` role name → `progress.operate`.
-- Guard-gated forward needs `b_submission` evidence before execution.
-- Threshold cooperation (`node_game`) surfaces multi-role forward needs when a pair's threshold > 1.
+- No settlement stake — your currency is reputation.
+- Route via `operable[].recommended_call`; do not infer the tool from the operator kind yourself.
+- Guarded forward: read `guard_submissions`, collect the values, submit with the execute call.
+- `node_game` surfaces the cooperation picture when a pair's threshold needs multiple distinct contributors.

package/wowok-governance/SKILL.md

@@ -2,7 +2,7 @@
 name: wowok-governance
 description: "WoWok Governance — the canonical skill for on-chain permission, data, and financial governance: the account that OWNS the objects keeps them healthy after setup. Covers Permission lifecycle (indexes, role assignment, entity table, admin transfer), Treasury/Allocation fund stewardship (deposit/withdraw, history audit, unclaimed payments), and Personal data boundaries (public identity, profile records). Governance is a continuous loop — inventory, decide, execute, audit — not a one-time setup. For building services, see wowok-provider. For market operations, see wowok-market. Use when: User wants to manage who can operate their objects (permission indexes, entity table); User wants to deposit/withdraw treasury funds or audit fund history; User has unclaimed payments or wants to check claimable balances; User wants to update their public on-chain profile or personal data; User mentions \"permission\", \"treasury\", \"governance\", \"manage assets\", \"audit funds\"."
 metadata:
-  version: "1.0.0"
+  version: "1.1.0"
   role: shared
   related: "wowok-provider, wowok-market, wowok-messenger"
 ---
@@ -11,85 +11,46 @@ metadata:
 
 > **Role**: Object owner/admin — the account that carries administrative responsibility for Permission, Treasury, and Personal objects
 > **Related Skills**: [wowok-provider](../wowok-provider/SKILL.md) (service build), [wowok-market](../wowok-market/SKILL.md) (market ops), [wowok-messenger](../wowok-messenger/SKILL.md) (contact)
+> Exact op shapes, field lists and enums live in the tool schemas — read `schema_query` `get` with `onchain_operations` (see the `permission` / `treasury` / `personal` `operation_type` branches) before mutating. Safety rules: `get_safety_rules`.
 
----
-
-## 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 |
-|---------|--------------------------|-------------|
-| Permission safety rules (owner/admin/entity hierarchy) | `schema_query` action='get_safety_rules' | `onchain_operations` permission |
-| Treasury/Permission/Personal object schema | `schema_query` action='get' name='treasury'/'permission'/'personal' | governance operations |
-| Unclaimed-payment detection | `keeper_operation` (payment_unclaimed scan) | monitor loop |
-| Fund-flow event meanings (TreasuryEvent / AllocationEvent / RewardClaimEvent / RewardFundEvent) | event semantic registry | audit & monitor |
-
-This Skill keeps the governance **conversation flow** — what to inventory, what to decide, what to execute, and how to audit.
-
----
-
-## Governance Is a Loop, Not a Setup
-
-Inventory → Decide → Execute → Audit. Governance objects are LIVE: a permission change takes effect on the next call, a withdraw is irreversible, a personal profile record is permanently public. Every change deserves an audit pass after execution.
-
----
-
-## Domain 1: Permission Governance
+## Governance is a loop, not a setup
 
-A Permission object defines WHO can perform WHICH operations on your business objects (Service / Machine / Treasury …).
+Inventory → decide → execute → **audit (re-query the post-state every time)**. These objects are live: a grant change applies on the next call, a withdraw is irreversible, a profile record is permanently public.
 
-- **Indexes**: role indexes are numeric IDs (custom indexes start at 1000 — built-ins are reserved). Naming one for readability is a `remark {op:'set', index, remark}` write, not a "create index" call.
-- **Grants** (`table` field): assign with `add perm by index` (one index → many entities) or `add perm by entity` (one entity → many indexes); `set` variants REPLACE the existing list. `admin {op:'add'|'remove'|'set'}` controls admins; entity-level hygiene uses `del`/`swap`/`replace`/`copy`. A mis-assigned grant takes effect immediately. Exact op shapes: `schema_query` action='get' name='permission'.
-- **Entity table**: review-first — read the current Permission via `query_toolkit` query_type='onchain_objects' before mutating.
-- **Audit**: `query_toolkit` query_type='onchain_table_item_permission_perm' checks what a specific address may do; query_type='address_profile' shows an address's permission memberships across all objects.
+## Domain 1 — Permission governance
 
-Rules of thumb:
-- One Permission per business object family; reuse named indexes, don't proliferate unnamed ones.
-- Removing an entity is immediate — the next operation by that address fails with "Permission denied" (abort code 5).
-- Admin transfer is a high-trust operation: the new admin controls the whole table.
+- **Inventory before mutating**: read the Permission via `query_toolkit` `onchain_objects`; audit one address with `onchain_table_item_permission_perm`; see every membership an address holds across objects with `address_profile` (batch form `address_profiles`, up to 50).
+- **Index naming is not an "index creation"**: custom permission indexes are the numeric IDs 1000–65535 (built-ins reserved below); a readable name is just a `remark` write (`set` / `remove` / `clear`).
+- **Choose the op family by shape** (`permission_operation`, exact params in schema):
+  - one index → many entities: `add|set|remove perm by index`;
+  - one entity → many indexes: `add|set|remove perm by entity`;
+  - `set` REPLACES the whole list — warn before using; prefer `add`/`remove`;
+  - entity hygiene: `swap` / `replace` / `copy` / `del`;
+  - admins: `admin` `add|remove|set` — high-trust: a new admin controls the whole table.
+- A removed entity's next call fails with permission#5 "Permission denied". Prefer one Permission per business-object family; reuse named indexes.
 
----
-
-## Domain 2: Financial Governance
-
-Fund stewardship across Treasury / Allocation / Reward / Payment.
-
-- **Treasury**: deposit joins coins in (a Payment receipt is minted); withdraw splits balance out — irreversible, and when an `external_guard` is set the guard must validate first. `query_toolkit` query_type='onchain_table_item_treasury_history' audits every flow (op 0 Withdraw / 1 Deposit / 2 Receive) with amount + guard + timestamp.
-- **Allocation**: runs distribute pool funds per sharing mode (Amount / Rate in bps — base 10000 = 100% / Surplus). Review allocator guards periodically — a stale guard blocks legitimate distributions.
-- **Unclaimed payments**: recipients hold frozen CoinWrappers until they unwrap. The keeper `payment_unclaimed` scan owns this reminder surface — run `keeper_operation` to list claimable payments and nudge recipients via Messenger. NewPaymentEvent is deliberately NOT push-bridged, to avoid duplicate reminders (P2-4 channel split).
-- **Reward pools**: RewardFundEvent in / RewardClaimEvent out; a dry pool blocks claims — watch balances before announcing campaigns.
-
----
+## Domain 2 — Financial governance
 
-## Domain 3: Data Governance
+- **Treasury**: deposit joins coins in (Payment receipt minted); withdraw splits balance out — irreversible, and an `external_guard` on the Treasury must authorize it. Audit every flow with `query_toolkit` `onchain_table_item_treasury_history` (op `0` Withdraw / `1` Deposit / `2` Receive; amount + guard + timestamp).
+- **Allocation**: modes Amount (fixed) / Rate (basis points, 10000 = 100%; pure-Rate must sum to 10000) / Surplus (remainder drain, ≤1 per Allocator). Review allocator guards periodically — a stale guard blocks legitimate distributions.
+- **Unclaimed payments**: recipients own frozen CoinWrappers until unwrapped. The keeper owns this reminder surface: `keeper_operation` `scan` then `tasks` with `detector: "payment_unclaimed"`; nudge recipients via Messenger. `NewPaymentEvent` is deliberately NOT push-suggestion-bridged, to avoid duplicate reminders.
+- **Reward pools**: funds in (RewardFundEvent) / claims out (RewardClaimEvent); a dry pool blocks claims — watch balances before announcing campaigns.
 
-- **Personal profile** (`personal` operations): your public on-chain identity. Everything here is PERMANENTLY PUBLIC — never anchor private data. Review-first: show the current record before every mutation.
-- **Entity info**: description/info updates re-emit NewEntityEvent — counterparties' cached profiles refresh; keep descriptions accurate.
-- **Repository data**: contribution/usage policies are designed at Repository level (see wowok-provider); governance audits consumption through the event stream.
+## Domain 3 — Data governance
 
----
-
-## Monitor Loop
-
-Governance goals close the loop through three channels:
-
-- **Push**: fund-flow events (TreasuryEvent / AllocationEvent / RewardClaimEvent / RewardFundEvent) become goal-bound suggestions via SuggestionBridge.
-- **Pull**: keeper scans (payment_unclaimed, balance thresholds) repeat reminders until resolved.
-- **Audit**: after every governance write, re-query the object and confirm the post-state matches the intent.
-
----
+- **Personal profile is permanently public** — never anchor private data; show the current record before every mutation.
+- **Profile/contact description updates emit NO on-chain event** (`NewEntityEvent` fires only on entity registration). Counterparties see updates on their next object read — there is no push; tell the user this instead of promising a refresh.
+- Repository contribution/usage policy belongs to [wowok-provider](../wowok-provider/SKILL.md); governance audits consumption via the event stream.
 
-## Core Interaction Principles
+## Loop channels
 
-1. **Review-first**: always show current state + the exact delta before executing.
-2. **User-driven**: surface options, never auto-execute — withdraw and admin transfer are irreversible.
-3. **Disclose irreversibility**: say it explicitly for withdraw, admin transfer, and any personal-data write.
-4. **Audit after**: every governance write ends with a re-query confirmation.
+- **Push**: fund-flow events (Treasury / Allocation / RewardFund / RewardClaim) become goal-bound suggestions through the monitor SuggestionBridge.
+- **Pull**: keeper scans (`payment_unclaimed`, `progress_actionable`) repeat reminders until resolved; standing `auto_execute` exists only for claim-to-self.
+- **Audit**: after every governance write, re-query and confirm the post-state matches intent.
 
-## Quick Reference
+## Interaction rules
 
-- Permission: index remarks → grants (`add perm by index`/`by entity`) → audit via permission_perm + address_profile.
-- Treasury: deposit/withdraw + history audit; external_guard gates withdrawals.
-- Unclaimed payments: keeper scan owns reminders; recipients unwrap CoinWrappers.
-- Personal data: permanently public — review before every write.
+1. **Review-first**: current state + exact delta before executing.
+2. **User-driven**: never auto-execute — withdraw and admin changes are irreversible.
+3. **Disclose irreversibility** for withdraw, admin transfer, and any personal-data write.
+4. **Audit after**: end every governance write with a re-query confirmation.