Merge branch 'master' into feat/ice-pallet

Author: enthusiastmartin

.claude/skills/hydration_cl0wdit

@@ -0,0 +1 @@
+../../ai_skills/hydration_cl0wdit

.codex/skills/hydration_cl0wdit

@@ -0,0 +1 @@
+../../ai_skills/hydration_cl0wdit

AGENTS.md

@@ -0,0 +1,30 @@
+# AGENTS.md - hydration-node
+
+This is the Codex entrypoint for the repository.
+
+Follow the project guidance in `CLAUDE.md`; it is the shared repo instruction
+file for build, test, style, PR, and domain conventions.
+
+## Shared AI skills
+
+Repo-local AI skills live in `ai_skills/` so they can be used by multiple coding
+agents.
+
+When the user invokes a skill by name, or the task clearly matches a skill
+description, read the corresponding `ai_skills/<skill-name>/SKILL.md` file and
+follow its instructions. Resolve any relative paths in a skill from that skill's
+directory.
+
+If a skill references tool names from another agent environment, use the closest
+available Codex equivalent:
+- `Read` -> file reads such as `sed`, `rg`, or editor context
+- `Glob` -> `rg --files` or `find`
+- `Grep` -> `rg`
+- `Bash` -> shell commands
+- `WebFetch` -> web access when available and permitted
+- `Agent` -> Codex sub-agents only when the user has explicitly asked for
+  delegated or parallel agent work
+
+Available shared skills:
+- `hydration_cl0wdit` - security audit workflow for Substrate runtime and pallet
+  code.

CLAUDE.md

@@ -7,6 +7,20 @@ For Hydration protocol-level context (architecture, products, tokenomics, Omnipo
 
 It lists available reference documents and their raw GitHub URLs.
 
+## Shared AI skills
+
+Repo-local AI skills live in `ai_skills/` so they can be used by multiple coding
+agents, not only Claude.
+
+When the user invokes a skill by name, or the task clearly matches a skill
+description, load the corresponding `ai_skills/<skill-name>/SKILL.md` file and
+follow its instructions. Resolve any relative paths in a skill from that skill's
+directory.
+
+Available shared skills:
+- `hydration_cl0wdit` - security audit workflow for Substrate runtime and pallet
+  code.
+
 ## Project overview
 
 Substrate-based parachain (Polkadot ecosystem) implementing DeFi protocols — DEX (Omnipool, Stableswap, XYK, LBP), DCA, OTC, bonds, staking, governance, and EVM compatibility.
@@ -133,6 +147,68 @@ Types: `feat`, `fix`, `refactor`, `perf`, `test`, `docs`, `style`, `ci`, `build`
 
 **Branches:** `fix/description` or `feat/description`
 
+## Code comments and docs
+
+Default to **no comment**. Only write one when the *why* is non-obvious — a hidden
+invariant, a surprising decision, a workaround. If removing the comment wouldn't
+confuse a future reader who can see the code, don't write it.
+
+**Never restate what the code already says.** Well-named identifiers and types are
+the documentation. Comments that paraphrase the next line are noise.
+
+### Module / file headers
+One paragraph max. State what lives here; don't enumerate every item or describe
+the flow step-by-step.
+
+### Struct / enum field docs
+Skip the obvious (`pub unstaking: Balance`, `pub voters_count: u32`). Document a
+field only when its semantics are surprising — e.g. it stacks instead of replacing,
+must match an external balance, doubles as an idempotency signal.
+
+### Error variants
+One line each, or none if the name already tells the story. Don't write a
+paragraph explaining the policy that produces the error — that belongs at the
+check site.
+
+### Extrinsic docs
+Follow the Description / Parameters / Emits structure from the "Extrinsic
+documentation" section above, but keep the **Description to 1–2 lines plus at
+most one short paragraph** for genuinely load-bearing context. In particular:
+
+- Do not enumerate `Error` variants in the Description — the `#[pallet::error]`
+  enum is the source of truth.
+- Do not list internal implementation steps ("locks X, then mints Y, then calls
+  Z"). The code shows that.
+- Keep the *why* of any non-obvious constraint (e.g. "refuses while stHDX is in
+  circulation — outstanding aTokens would be stranded").
+
+### Trait method docs
+One line. If the trait-level doc already explains the contract, leave method
+docs out entirely.
+
+### Inline comments inside function bodies
+Reserve for:
+- Non-obvious invariants the next line relies on.
+- Why a defensive branch exists / why an error is intentionally swallowed.
+- Why an unusual construct (`drain_prefix(...).count()` to actually drain,
+  `set_lock` vs `extend_lock`, pre-decrement before an external call) is correct.
+
+Skip:
+- Narrating control flow ("// new record: increment voter count" above
+  `voters_count += 1`).
+- Explaining what a well-named helper does at its call site.
+- Restating the assertion in the next `ensure!`.
+
+### What to keep
+Comments that warn a future reader about something they would otherwise miss:
+- "Must match `LockableAToken.sol`'s `freeBalance` check"
+- "Saturating math — hooks must never block voting"
+- "Pool presence ⇔ allocation has run" (load-bearing idempotency signal)
+- "stHDX invariants — verify on AAVE config change: (1)…(2)…"
+
+If in doubt, delete the comment and see if the code still reads. If it does,
+leave it out.
+
 ## Versioning
 
 - **SemVer** on all crates — bump `Cargo.toml` version on changes

Cargo.lock

@@ -8,6 +8,19 @@ allowed-tools: Read, Glob, Grep, WebFetch, Bash, Agent
 
 You are the orchestrator of a parallelized security audit of a Substrate runtime and/or its pallets.
 
+## Codex compatibility
+
+This skill is shared across agent environments. If you are running in Codex, map the Claude-oriented tool names as follows:
+
+- `Read` -> `sed`, `rg`, or other file-read commands.
+- `Glob` -> `rg --files` or `find`.
+- `Grep` -> `rg`.
+- `Bash` -> `exec_command`.
+- `WebFetch` -> the web tool, or `curl` only when shell network access is available.
+- `Agent` -> Codex sub-agents, following the active Codex environment policy for agent spawning. If sub-agents are unavailable or disallowed in the current environment, run a reduced local review or ask the user how to proceed.
+
+The banner and four-turn orchestration apply only when the user requests an audit run. They do not apply when the user asks to inspect, update, or explain this skill.
+
 ## Mode Selection
 
 **Exclude pattern:** skip directories `tests/`, `benchmarking/`, `mock/` and files matching `*test*.rs`, `*mock*.rs`, `*bench*.rs`.
@@ -18,7 +31,7 @@ You are the orchestrator of a parallelized security audit of a Substrate runtime
 **Flags:**
 
 - `--pr <ref>`: Audit a specific pull request. `<ref>` can be a PR number or a full GitHub PR URL. Do NOT use `gh` — fetch PR data via `WebFetch` against the GitHub API (`https://api.github.com/repos/{owner}/{repo}/pulls/{number}/files`). Parse the response for changed `.rs` files.
-- `--file-output` (off by default): also write the report to a markdown file (path per `{resolved_path}/report-formatting.md`). Never write a report file unless explicitly passed.
+- `--file-output` (off by default): also write the report to a markdown file at the path specified by `{resolved_path}/report-formatting.md`. Never write a report file unless explicitly passed.
 
 ## Orchestration
 
@@ -29,7 +42,7 @@ a. Discover in-scope `.rs` files per mode selection:
    - **With `--pr`:** Use `WebFetch` to call `https://api.github.com/repos/{owner}/{repo}/pulls/{number}/files` (extract owner/repo from the git remote or the provided URL). Parse the JSON response for changed `.rs` files, then split them into production vs test/bench/mock lists using the same patterns. Do NOT use `gh`.
 b. Glob for `**/references/attack-vectors/substrate-attack-vectors.md` — extract the `references/` directory (two levels up) as `{resolved_path}`
 c. Read the local `VERSION` file from the same directory as this skill
-d. Bash `curl -sf https://raw.githubusercontent.com/galacticcouncil/hydration-node/main/.claude/skills/hydration_cl0wdit/VERSION`
+d. Fetch `https://raw.githubusercontent.com/galacticcouncil/hydration-node/main/ai_skills/hydration_cl0wdit/VERSION` (`Bash curl -sf` in Claude; web tool in Codex when shell network is restricted)
 e. Bash `mktemp -d /tmp/audit-XXXXXX` → store as `{bundle_dir}`
 
 If the remote VERSION fetch succeeds and differs from local, print `⚠ hydration_cl0wdit v{local} is outdated — a newer version is available in the repo`. If it fails, skip silently.
@@ -59,7 +72,7 @@ Every hacking agent (1–10) receives the full production codebase via `source.m
 
 Print line counts for every bundle and `source.md`. Do NOT inline file content into agent prompts.
 
-**Turn 3 — Spawn.** In one message, spawn all 11 agents as parallel foreground Agent calls. Prompt template (substitute real values):
+**Turn 3 — Spawn.** In one message, spawn all 11 agents as parallel audit workers (Claude: foreground Agent calls; Codex: sub-agents). Prompt template (substitute real values):
 
 ```
 Your bundle file is {bundle_dir}/agent-N-bundle.md (XXXX lines).