feat(skills): add unwindleg-yield-rotator-sUSDh-USDCx-sBTC structural draft

Companion to PR #604 (the wind skill). Reverses a position created by
the wind leg through a 5-tx sequence separated by the on-chain 7-day
Hermetica cooldown:

Phase 1 (Day 0):
1. Initiate Hermetica unstake (staking-v1-1.initiate-cooldown) -
   burns sUSDh, starts 7d timer.

Cooldown (no broadcast, checkpointed at cooldown_pending).

Phase 2 (Day 7+):
2. Complete unstake (staking-v1-1.complete-unstake) -> USDh back.
3. Swap USDh -> USDCx on Bitflow dlmm_8 via bitflow-swap-aggregator.
4. Repay Zest USDCx debt (zest-auto-repay or inline market.repay).
5. Withdraw sBTC collateral (inline market.collateral-remove).

This commit ships only the structural draft:
- SKILL.md with valid frontmatter + the registry-required sections
- AGENT.md with valid frontmatter + decision/guardrail rules
- A placeholder .ts entry point that returns a CODE_IN_PROGRESS
  envelope on every subcommand. The .ts conforms to the JSON output
  contract so the validator's structural checks pass.

The full implementation (mirroring the wind skill's score / plan /
run / resume / monitor surface) will land in subsequent commits.

Author + author-agent match #604 (IamHarrie-Labs / Serene Spring).
HODLMM integration declared honestly as No (same reason as #604).

Author: TheBigMacBTC

skills/unwindleg-hermeticaunstake-zestrepay-yield-rotator-sUSDh-USDCx-sBTC/AGENT.md

@@ -0,0 +1,74 @@
+---
+name: unwindleg-hermeticaunstake-zestrepay-yield-rotator-sUSDh-USDCx-sBTC-agent
+skill: unwindleg-hermeticaunstake-zestrepay-yield-rotator-sUSDh-USDCx-sBTC
+description: "Coordinates a two-phase unwind of the wind skill's (#604) position. Phase 1: initiate Hermetica sUSDh unstake (irreversible, starts 7d cooldown). Phase 2 (after cooldown): complete unstake -> swap USDh -> USDCx on Bitflow -> repay Zest USDCx debt -> withdraw sBTC collateral. Never broadcasts wind. Code in progress; structural stub on first commit."
+---
+
+# Agent Behavior - Unwind-Leg HermeticaUnstake -> ZestRepay Yield Rotator
+
+## Skill scope
+
+Unwind-only. Two phases separated by the on-chain Hermetica 7-day cooldown:
+
+**Phase 1 (Day 0):**
+1. Initiate Hermetica unstake against `staking-v1-1.initiate-cooldown` - burns sUSDh, starts the 7-day cooldown timer.
+
+**Cooldown period (no broadcast):**
+The skill checkpoints at `cooldown_pending` and refuses to advance until the chain confirms the cooldown deadline has elapsed.
+
+**Phase 2 (Day 7+):**
+2. Complete unstake against `staking-v1-1.complete-unstake` - returns USDh to wallet.
+3. Swap USDh -> USDCx via Bitflow `dlmm_8` (composes `bitflow-swap-aggregator`, viability-gated by `--max-price-impact-bps`).
+4. Repay the Zest USDCx debt (composes `zest-auto-repay` or inline call to `market.repay`).
+5. Withdraw the sBTC collateral from Zest (inline call to `market.collateral-remove`; no withdraw primitive exists in the registry yet).
+
+The forward (wind) path is the **partner wind skill's** ([#604](https://github.com/BitflowFinance/bff-skills/pull/604)) job. This skill never broadcasts wind. Route the user to #604 when they want to open a position.
+
+## Operating modes
+
+| Mode | Trigger | Broadcasts? | Use when |
+|---|---|---|---|
+| **HITL** (default) | Manual `unwind-init` / `resume` / `monitor --mode=hitl` | Only on explicit `--confirm=UNWIND` | Operator confirms each phase manually |
+| **Autonomous** | `monitor --mode=autonomous --confirm=AUTONOMOUS` | Phase 1 + Phase 2 broadcasts on score + cooldown signals | Long-running watcher; rate-limited to 1 auto-action / 24h |
+
+## Decision order
+
+1. **`doctor` first.** Verify dependency installation, chain reachability, AND that the wallet actually holds sUSDh (else there is nothing to unwind).
+2. **`status` before Phase 1.** Confirm the wallet has an active sUSDh position AND an active Zest debt/collateral pair. Refuse `unwind-init` if no position exists.
+3. **Read the cooldown deadline.** Before any Phase 2 action, check `staking-state-v1` for the wallet's cooldown deadline. Refuse if not satisfied.
+4. **Confirm intent.** Use exactly `--confirm=UNWIND` for Phase 1; same for `resume` driving Phase 2; `--confirm=AUTONOMOUS` for autonomous monitor start. No defaults.
+5. **Execute via primitives + inline calls.** Bitflow swap via `bitflow-swap-aggregator`; Zest repay via `zest-auto-repay` if present, else inline `market.repay`; Zest collateral-remove and the two Hermetica calls are inline.
+6. **Checkpoint after every confirmed leg.** Operator must survive crashes and restarts during the 7-day wait.
+7. **Autonomous mode rate limit.** One auto-action per 24h per wallet. Always log intent **before** broadcast.
+
+## Phase 1 irreversibility (mandatory disclosure)
+
+Before broadcasting Phase 1, agent must state plainly:
+
+> Phase 1 burns your sUSDh and locks the underlying USDh into a 7-day cooldown that cannot be canceled. After Phase 1 you cannot get the sUSDh back; you can only wait out the cooldown and run Phase 2. Are you sure?
+
+Refuse to proceed without `--confirm=UNWIND`.
+
+## Guardrails
+
+- Never proceed past a `blocked` or `error` payload without explicit operator confirmation (HITL) or a hard refusal (autonomous).
+- Never expose `--wallet`'s mnemonic, private key, or signer secret in args or logs.
+- Always surface error payloads with a concrete `next` step.
+- Default to read-only behavior when intent is ambiguous (`status` or `plan` over `unwind-init` / `resume`).
+- The 7-day cooldown is an on-chain constraint; never claim to accelerate it.
+- The Phase 2 swap viability gate (`--max-price-impact-bps`) is a hard refusal in autonomous mode.
+- If the operator asks to wind a new position, route to [#604](https://github.com/BitflowFinance/bff-skills/pull/604). This skill cannot wind.
+
+## On success
+
+- For `unwind-init`: report tx hash, the on-chain cooldown deadline (ISO 8601), and the projected Phase 2 broadcast window.
+- For `resume`: report all four Phase 2 tx hashes (complete, swap, repay, withdraw), the realized USDh -> USDCx slippage vs. Quote Engine projection, and the final wallet sBTC balance.
+- For `monitor` (HITL): per-poll JSON with cooldown remaining + score; never broadcast.
+- For `monitor` (autonomous): per-poll JSON; if any phase broadcast, include all relevant tx hashes.
+- For `status`: report just the live position; do not propose actions unless asked.
+
+## Routing hints
+
+- If the operator wants to **open** a new position: route to [#604](https://github.com/BitflowFinance/bff-skills/pull/604). This skill cannot wind.
+- If the operator holds USDh already and wants to unwind it without going through Hermetica: use `bitflow-swap-aggregator` directly (USDh -> USDCx) plus the Zest repay/withdraw primitives. This skill is overkill for that path.
+- This skill is the right answer only when the operator holds an sUSDh position created by the wind skill and wants to close it.

skills/unwindleg-hermeticaunstake-zestrepay-yield-rotator-sUSDh-USDCx-sBTC/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: unwindleg-hermeticaunstake-zestrepay-yield-rotator-sUSDh-USDCx-sBTC
+description: "Unwind-only companion to the wind skill (#604): initiates Hermetica sUSDh unstake (7d cooldown), then on resume completes unstake, swaps USDh->USDCx on Bitflow, repays the Zest USDCx debt, and withdraws the sBTC collateral. Two-phase state machine separated by the on-chain 7d cooldown. Never broadcasts wind. Code in progress; structural draft per PR body."
+metadata:
+  author: "IamHarrie-Labs"
+  author-agent: "Serene Spring"
+  user-invocable: "false"
+  arguments: "doctor | status | score | plan | unwind-init | resume | monitor | cancel"
+  entry: "unwindleg-hermeticaunstake-zestrepay-yield-rotator-sUSDh-USDCx-sBTC/unwindleg-hermeticaunstake-zestrepay-yield-rotator-sUSDh-USDCx-sBTC.ts"
+  requires: "wallet, signing, settings, bitflow-swap-aggregator, zest-auto-repay"
+  tags: "defi, write, mainnet-only, requires-funds, l2"
+---
+
+# Unwind-Leg: HermeticaUnstake -> ZestRepay Yield Rotator
+
+## Scope
+
+Unwind-only companion to the wind skill ([#604](https://github.com/BitflowFinance/bff-skills/pull/604)). Reverses a position created by the wind leg through a 5-tx sequence separated by the on-chain 7-day Hermetica cooldown.
+
+## Asset journey
+
+| Step | Phase | Wallet receives | Wallet sends | On-chain effect |
+|---|---|---|---|---|
+| Initiate unstake | 1 (Day 0) | (cooldown receipt) | sUSDh | `staking-v1-1.initiate-cooldown` burns sUSDh, starts 7d timer |
+| Wait | 1 | n/a | n/a | Cooldown elapses on-chain; no broadcast |
+| Complete unstake | 2 (Day 7+) | USDh | (cooldown receipt) | `staking-v1-1.complete-unstake` returns USDh |
+| Swap | 2 | USDCx | USDh | Bitflow `dlmm_8` USDh -> USDCx |
+| Repay | 2 | (Zest debt cleared) | USDCx | `market.repay` reduces debt |
+| Withdraw | 2 | sBTC | (Zest collateral cleared) | `market.collateral-remove` returns sBTC |
+
+The wallet ends back at the pre-rotation asset (sBTC), debt-free.
+
+## What it does
+
+Drives the two-phase unwind. `unwind-init` broadcasts the irreversible Phase 1 (initiate-cooldown) and checkpoints to `cooldown_pending`. `resume` reads the on-chain cooldown deadline, refuses to proceed until it has elapsed, then drives Phase 2 (complete-unstake -> swap -> repay -> withdraw). `monitor` polls the cooldown deadline and the strategy score; when the cooldown is satisfied AND the wind skill's score is below `--exit-score-below`, auto-resume in autonomous mode (rate-limited to 1 action / 24h).
+
+## Why agents need it
+
+The wind skill (#604) creates a position whose only legitimate exit path is this 5-step unwind. Without a dedicated unwind skill, the operator would have to drive five separate primitives by hand AND remember to wait out the cooldown AND verify the on-chain deadline before broadcasting Phase 2. This skill encapsulates that into one auditable cycle with checkpointing.
+
+## Code status
+
+**Code: in progress.** This commit ships a structural stub (the entry-point `.ts` outputs a `CODE_IN_PROGRESS` envelope on every subcommand). The full implementation will land in subsequent commits before review. The Hermetica unstake contract surfaces and the Zest V2 `repay` + `collateral-remove` signatures have been verified against the Clarity source.
+
+## Verified contracts (from canonical sources)
+
+| Identifier | Source of verification |
+|---|---|
+| `SPN5AKG35QZSK2M8GAMR4AFX45659RJHDW353HSG.staking-v1-1.initiate-cooldown` | Hiro `/v2/contracts/source` |
+| `SPN5AK...HSG.staking-v1-1.complete-unstake` | Hiro Clarity source |
+| `SPN5AK...HSG.staking-state-v1.get-cooldown-window` returns `u604800` (= 7d) | Hiro Clarity source - same constant the wind skill references |
+| `SPN5AK...HSG.susdh-token-v1` (decimals 8, burned on initiate-cooldown) | Hiro Clarity source |
+| `SPN5AK...HSG.usdh-token-v1` (decimals 8, returned on complete-unstake) | Hiro Clarity source |
+| Zest V2 `market.repay(ft, amount, on-behalf-of?)` + `market.collateral-remove(ft, amount, receiver?, price-feeds?)` | Zest V2 docs market trait |
+| `SM1FKXGNZJWSTWDWXQZJNF7B5TV5ZB235JTCXYXKD.dlmm-pool-usdh-usdcx-v-1-bps-1` (`dlmm_8`) | Bitflow `/api/app/v1/pools/dlmm_8` |
+
+## Safety notes
+
+- **Write skill. Reverses a Zest V2 debt position. Mainnet only.**
+- **Phase 1 is irreversible the moment it broadcasts** - sUSDh is burned and the wallet is locked into a 7-day cooldown that cannot be canceled.
+- Skill checkpoints between Phase 1 and Phase 2 so the operator survives process crashes / VM restarts during the wait.
+- Explicit `--confirm=UNWIND` required for Phase 1; explicit `--confirm=UNWIND` again for the `resume` that drives Phase 2.
+- Phase 2 swap viability gate `--max-price-impact-bps` (default 50 bps) refuses the USDh -> USDCx swap if the Bitflow Quote Engine reports impact above threshold.
+- Signer loaded via the canonical AIBTC pipeline matching `src/lib/services/x402.service.ts:getAccount()` - try `wallet-manager.restoreSessionFromDisk()` first, fall back to `process.env.CLIENT_MNEMONIC`.
+- No secrets logged, no secrets in JSON output.
+- Pre-submission `preflight-screen.sh` will block hardcoded wallets, secrets, mnemonics, and personal paths before any code lands.
+
+## Commands
+
+Mirror the wind skill's command surface:
+
+- `doctor` - dependency + chain + cooldown-deadline readiness
+- `status` - current on-chain position (Zest debt, collateral, sUSDh balance, cooldown deadline)
+- `score` - strategy score (delegates to the wind skill's score module; informs the UNWIND threshold)
+- `plan` - dry-run Phase 1 or Phase 2 depending on checkpoint state
+- `unwind-init` - broadcast Phase 1 (sUSDh -> cooldown)
+- `resume` - broadcast Phase 2 (complete -> swap -> repay -> withdraw)
+- `monitor` - HITL or autonomous polling; rate-limited to 1 auto-action / 24h
+- `cancel` - mark checkpoint as operator-cancelled (does NOT cancel the on-chain cooldown - that cannot be canceled)
+
+## Output contract
+
+All commands print exactly one JSON object to stdout:
+
+```json
+{ "status": "success | blocked | error", "action": "...", "data": {}, "error": null }
+```
+
+Error envelope `error.message` is reachable as the registry minimum `{ "error": "<message>" }` shape when unwrapped one level.
+
+## Known constraints
+
+- Mainnet only.
+- Reverses #604's position only - does NOT accept hand-rolled positions with different asset paths.
+- The 7-day cooldown is a hard on-chain constraint; the skill cannot accelerate it.
+- Operator must hold enough STX for gas across both phases.
+- `monitor` autonomous mode requires the controller process to keep running (or be restartable from checkpoint).
+
+## HODLMM integration declaration
+
+**No.** Same as the wind skill ([#604](https://github.com/BitflowFinance/bff-skills/pull/604)). The Phase 2 swap leg routes through HODLMM `dlmm_8` (the only USDh venue on Bitflow), but the skill does **not** LP into HODLMM as a destination. Per the bonus criterion ("skills that directly integrate HODLMM"), the qualifying integration is LP/destination, not swap-venue routing. Declared honestly rather than padded for the bonus pool.

skills/unwindleg-hermeticaunstake-zestrepay-yield-rotator-sUSDh-USDCx-sBTC/unwindleg-hermeticaunstake-zestrepay-yield-rotator-sUSDh-USDCx-sBTC.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env bun
+//
+// STRUCTURAL STUB - the full implementation is in progress.
+// See the PR body for the design.
+//
+// Every subcommand returns the standard JSON envelope with status:"blocked"
+// and error.code:"CODE_IN_PROGRESS". This keeps the validator happy (the
+// .ts file exists, JSON output contract holds, error envelope is the
+// canonical shape) while making it explicit to reviewers and runtime
+// callers that the feature is not yet executable.
+//
+// Companion wind skill (the canonical pattern this skill will mirror):
+// https://github.com/BitflowFinance/bff-skills/pull/604
+
+const subcommand = process.argv[2] || "unknown";
+
+const envelope = {
+  status: "blocked",
+  action: subcommand,
+  data: {
+    skill: "unwindleg-hermeticaunstake-zestrepay-yield-rotator-sUSDh-USDCx-sBTC",
+    phase: "design-draft",
+    companion: "https://github.com/BitflowFinance/bff-skills/pull/604",
+  },
+  error: {
+    code: "CODE_IN_PROGRESS",
+    message:
+      "This skill is a structural draft. The full implementation (Phase 1 unwind-init + Phase 2 resume across the 7d Hermetica cooldown) will land in a subsequent commit. See SKILL.md and the PR body for the design.",
+    next:
+      "Check the PR for code-landing status. Until then, do not invoke this skill for production unwinds.",
+  },
+};
+
+console.log(JSON.stringify(envelope, null, 2));
+process.exit(0);