web3skill 0.1.0

package/dist/skills/web3-audit-reporting/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: web3-audit-reporting
+description: Produce high-signal Web3 audit deliverables with scope, trust boundaries, evidence-backed findings, severity calibration, remediation, and retest conclusions. Use when the user wants a smart contract audit report, finding writeup, severity review, contest submission, fix validation, or consolidated security deliverable.
+---
+
+# Web3 Audit Reporting
+
+Use this skill for audit-grade output, not casual review notes.
+
+## Mode Selection
+
+- Full report or consolidated review:
+  - read `references/REPORT_TEMPLATE.md`
+- Single finding or contest submission:
+  - read `references/FINDING_TEMPLATE.md`
+- Fix validation or retest:
+  - read `references/RETEST_TEMPLATE.md`
+- Severity dispute or calibration:
+  - read `references/SEVERITY_RUBRIC.md`
+
+## Non-Negotiable Gates
+
+- Do not promote a suspicion into a finding until you can state:
+  - attacker
+  - preconditions
+  - vulnerable entry point and code path
+  - broken invariant or trust assumption
+  - realistic impact on users, funds, control, or liveness
+- Every finding must cite affected files, functions, and line references when possible.
+- Separate confirmed findings from dismissed candidates and open questions.
+- If exploitation requires a malicious privileged role, classify it as a trust or centralization issue unless the user explicitly asked for admin-abuse review.
+- If severity is unclear, lower confidence before inflating severity.
+
+## Delivery Workflow
+
+1. Lock the review context first:
+   - target
+   - commit or snapshot
+   - chain or deployment context
+   - in-scope and out-of-scope components
+2. Build the protocol model before writing findings:
+   - assets at risk
+   - roles and upgrade paths
+   - external dependencies
+   - core invariants
+   - critical user flows
+3. Run a falsification pass on every candidate:
+   - search for guards, bounds, config assumptions, opposing code paths, and documented intent
+   - discard anything that fails under realistic conditions
+4. Consolidate by root cause:
+   - deduplicate overlapping tool output or parallel notes
+   - keep the highest-confidence version
+   - do not count the same bug multiple times unless the impacts are materially different
+5. Write findings in descending severity while keeping confidence explicit.
+6. End with remediation status, retest status, and unresolved risks.
+
+## Writing Rules
+
+- Lead with exploit path and user impact, not generic best-practice language.
+- Explain why the issue is exploitable under the stated assumptions.
+- State what was actually verified:
+  - manual reasoning
+  - test or PoC
+  - static analysis
+  - onchain evidence
+- State what was not verified:
+  - missing deployment data
+  - unrun tests
+  - assumed config or oracle behavior
+- When no issue is confirmed, say so directly and list residual risks or coverage gaps.
+
+## Escalation
+
+- Read `references/SEVERITY_RUBRIC.md` before assigning severity in any nontrivial case.
+- Read `references/FINDING_TEMPLATE.md` before writing any individual finding.
+- Read `references/REPORT_TEMPLATE.md` before producing a full audit report or merged review.
+- Read `references/RETEST_TEMPLATE.md` when validating a claimed fix or protocol upgrade.

package/dist/skills/web3-audit-reporting/references/FINDING_TEMPLATE.md

@@ -0,0 +1,54 @@
+# Finding Template
+
+## [H-1] Loss of Funds via Broken Accounting in `Feature`
+
+### Snapshot
+
+- Severity:
+- Confidence:
+- Status: confirmed / likely / dismissed / needs retest
+- Category:
+- Source: manual / tool / chain / mixed
+- Affected files:
+- Affected functions:
+
+### User and Protocol Impact
+
+- Broken invariant or trust assumption:
+- Attacker capability:
+- Preconditions:
+- Realistic impact:
+- Why this matters now:
+
+### Technical Path
+
+1. Entry point:
+2. Relevant state or accounting assumption:
+3. Manipulation or external-call step:
+4. Missing check, stale state, or unsafe transition:
+5. Resulting loss, lock, control change, or liveness failure:
+
+### Evidence
+
+- Code references:
+- Tool or trace evidence:
+- Test, PoC, simulation, or calldata evidence:
+- Chain or deployment evidence:
+
+### Falsification Checks
+
+- What was checked to disprove the issue:
+- Why those checks did not save the system:
+- Remaining uncertainty:
+
+### Remediation
+
+- Primary fix:
+- Defense in depth:
+- Verification to rerun:
+
+### Retest Notes
+
+- Claimed fix:
+- Retest status:
+- Residual risk:

package/dist/skills/web3-audit-reporting/references/REPORT_TEMPLATE.md

@@ -0,0 +1,58 @@
+# Web3 Security Review Report
+
+## Review Context
+
+- Target:
+- Commit, tag, or snapshot:
+- Review type: full audit / focused review / diff review / contest triage / post-fix retest
+- Review date:
+- Reviewer:
+- Chains or environments considered:
+- In scope:
+- Out of scope:
+
+## Protocol Model
+
+- Protocol purpose:
+- Assets at risk:
+- Roles and privileged actors:
+- Upgradeability, pause, or emergency powers:
+- External dependencies:
+- Core invariants:
+- Critical user flows:
+
+## Methodology
+
+- Manual review:
+- Static analysis:
+- Dynamic testing, fuzzing, or invariants:
+- Onchain or config validation:
+- Candidate issues dismissed during triage:
+
+## Findings Overview
+
+| ID | Severity | Confidence | Status | Title | Affected area |
+| --- | --- | --- | --- | --- | --- |
+| H-1 | High | Medium | Confirmed | Example title | Core vault accounting |
+
+If no issue is confirmed, say so explicitly here and list the residual risks or validation gaps.
+
+## Detailed Findings
+
+Use `FINDING_TEMPLATE.md` for each confirmed issue.
+
+## Remediation and Retest Summary
+
+| ID | Claimed fix | Retest status | Notes |
+| --- | --- | --- | --- |
+| H-1 | Update accounting before transfer | Partially fixed | Cross-function path still open |
+
+## Residual Risks and Open Questions
+
+- 
+
+## Appendix
+
+- Commands and tools run
+- Assumptions and missing data
+- Addresses, deployments, or chain context

package/dist/skills/web3-audit-reporting/references/RETEST_TEMPLATE.md

@@ -0,0 +1,35 @@
+# Retest Template
+
+## Retest Context
+
+- Finding ID or title:
+- Claimed fix commit or patch:
+- Retest date:
+- Retest status:
+
+## Intended Delta
+
+- Files changed:
+- Root cause supposedly removed:
+- New trust assumptions introduced:
+
+## Validation Performed
+
+- Build or compile:
+- Targeted unit tests:
+- Adversarial or PoC replay:
+- Invariant or fuzz checks:
+- Static analysis rerun:
+- Deployment or config validation:
+
+## Outcome
+
+- Fixed behavior observed:
+- Remaining weakness:
+- Regression risk:
+- What was not verified:
+
+## Decision
+
+- fixed / partially fixed / not fixed / unable to verify
+- Follow-up required:

package/dist/skills/web3-audit-reporting/references/SEVERITY_RUBRIC.md

@@ -0,0 +1,75 @@
+# Severity Rubric
+
+Severity follows exploitability and blast radius, not code aesthetics.
+
+## Reportability Gate
+
+A security finding is reportable only if you can explain:
+
+- attacker
+- preconditions
+- vulnerable path
+- broken invariant or trust assumption
+- concrete impact
+
+If one of these is missing, keep it as a candidate or note, not a confirmed finding.
+
+## Default Privilege Assumption
+
+Assume owner, admin, governance, and other privileged roles act honestly unless the user explicitly asks for centralization or malicious-admin review.
+
+- Honest-admin assumption violated:
+  - usually a trust-model note, not an exploitable vulnerability
+- Unprivileged path or privilege gain caused by code:
+  - reportable security issue
+
+## Severity Bands
+
+### Critical
+
+Realistic path to direct protocol-wide drain, permanent insolvency, irreversible control takeover, or widespread permanent fund lock with minimal preconditions.
+
+### High
+
+Serious fund loss, unfair liquidation, privilege escalation, or system-wide freeze under realistic but nontrivial conditions.
+
+### Medium
+
+Bounded financial loss, meaningful griefing or DoS, accounting drift, broken settlement, or localized control issues with narrower blast radius or stronger preconditions.
+
+### Low
+
+Edge-case user harm, limited operational failure, defense-in-depth gap with plausible but weak impact, or bugs that require several restrictive assumptions.
+
+### Informational
+
+Best-practice, maintainability, observability, or low-confidence concerns without direct exploitable impact.
+
+## Confidence
+
+- High:
+  - reproduced, traced end-to-end, or explicit code path with little ambiguity
+- Medium:
+  - strong technical case, but no full repro or no deployment confirmation
+- Low:
+  - suspicious pattern needing more evidence
+
+Low confidence should rarely be presented as a core finding.
+
+## Calibration Checks
+
+- Downgrade if the exploit depends on unrealistic liquidity, unavailable permissions, or unsupported integrations.
+- Downgrade if the blast radius is one actor or one edge path rather than a core protocol flow.
+- Upgrade only when you can show concrete economic or control impact.
+- Do not merge severity and confidence. A bug can be high severity and medium confidence.
+
+## Special Cases
+
+- Admin-only dangerous knobs:
+  - usually trust or centralization notes
+- Missing slippage or deadline in user-facing swaps:
+  - reportable only if users are materially exposed
+- Precision loss:
+  - severity depends on extractable value, not the mere presence of rounding
+- Reentrancy, oracle, and callback issues:
+  - require an exploit path, not just a pattern match

package/dist/skills/web3-fuzzing-and-invariants/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: web3-fuzzing-and-invariants
+description: Fuzzing and invariant orchestration layer for protocol reviews and smart contract testing. Use when deriving invariants, writing harnesses, evaluating property-based tests, or interpreting fuzz failures.
+---
+
+# Web3 Fuzzing And Invariants
+
+Use this skill when the task is to derive invariants, set up fuzzing, or interpret failing cases in a security context.
+
+## Required Components
+
+- `web3-repo-heuristics`
+- `web3-audit-reporting`
+
+## Required Profile Adapters
+
+- `property-based-testing`
+- `harness-writing`
+- `coverage-analysis`
+- `state-invariant-detection`
+
+Use [references/ADAPTER_CONSUMPTION_MAP.md](references/ADAPTER_CONSUMPTION_MAP.md)
+to normalize fuzzing and invariant adapter output into stable evidence blocks.
+Use [references/READINESS_AND_FAILURES.md](references/READINESS_AND_FAILURES.md)
+and [references/OUTPUT_TEMPLATE.md](references/OUTPUT_TEMPLATE.md) to keep fuzz
+campaign status and failure interpretation stable.
+Use [scripts/render_fuzz_summary.py](scripts/render_fuzz_summary.py) when
+downstream skills need a normalized fuzz/invariant summary.
+
+## Workflow
+
+1. Use `state-invariant-detection` to extract candidate invariants from protocol behavior.
+2. Use `property-based-testing` to shape properties and failure expectations.
+3. Use `harness-writing` to guide or review fuzz harness structure.
+4. Use `coverage-analysis` to judge whether the fuzz campaign is meaningfully exploring the surface.
+5. Convert only security-relevant, reproducible failures into findings via `web3-audit-reporting`.
+
+## Invariant Classes
+
+- accounting / conservation
+- access control / authorization
+- state transition ordering
+- oracle / pricing assumptions
+- upgrade / initialization safety
+- integration safety for external tokens or protocols
+
+## Reusable Output Contract
+
+Always emit both:
+
+1. A short fuzz/invariant progress summary
+2. A normalized `fuzz_summary` block
+
+The normalized block must preserve:
+
+- campaign status
+- invariant set
+- harness status
+- failing-case count
+- exploit relevance
+- residual coverage gaps and next steps
+- exact evidence source per observed failure or gap
+
+## Guardrails
+
+- Do not confuse a weak harness with a secure protocol.
+- A failing property is only a finding after root cause and exploit relevance are understood.
+- If the repo lacks runnable fuzz infrastructure, say whether the blocker is tooling, build, or missing test hooks.

package/dist/skills/web3-fuzzing-and-invariants/references/ADAPTER_CONSUMPTION_MAP.md

@@ -0,0 +1,14 @@
+# Fuzzing Adapter Consumption Map
+
+- `state-invariant-detection` -> candidate invariants
+- `property-based-testing` -> property definitions and failure expectations
+- `harness-writing` -> harness quality and instrumentation
+- `coverage-analysis` -> exploration quality and residual blind spots
+
+Normalize into:
+
+- invariant set
+- harness status
+- failing cases
+- exploit relevance
+- residual coverage gap

package/dist/skills/web3-fuzzing-and-invariants/references/OUTPUT_TEMPLATE.md

@@ -0,0 +1,40 @@
+# Web3 Fuzzing Output Template
+
+Always emit:
+
+1. A short human-readable fuzzing summary
+2. A normalized block
+
+```yaml
+fuzz_summary:
+  version: 1
+  campaign_status: partial
+  scope: test/invariants
+  harness_status: weak
+  invariant_set:
+    - totalAssets tracks deposits minus withdrawals
+    - only governance can change fee parameters
+  failing_case_count: 2
+  exploit_relevance: medium
+  coverage_gaps:
+    - liquidation branch not reachable in current harness
+  next_steps:
+    - improve state setup for liquidation path
+  evidence:
+    - adapter: state-invariant-detection
+      detail: accounting invariant extracted from vault flows
+    - adapter: coverage-analysis
+      detail: liquidation branch coverage remains zero
+```
+
+## Required Fields
+
+- `campaign_status`: `ready | partial | blocked`
+- `scope`
+- `harness_status`
+- `invariant_set`
+- `failing_case_count`
+- `exploit_relevance`
+- `coverage_gaps`
+- `next_steps`
+- `evidence`

package/dist/skills/web3-fuzzing-and-invariants/references/READINESS_AND_FAILURES.md

@@ -0,0 +1,25 @@
+# Fuzzing Readiness And Failure Semantics
+
+Normalize fuzzing status into:
+
+- `ready`
+  - harness exists, campaign is runnable, and observed failures are interpretable
+- `partial`
+  - some harnessing or coverage exists, but exploration or instrumentation is incomplete
+- `blocked`
+  - campaign cannot run or results are too weak to interpret
+
+## Harness Status
+
+- `strong`
+  - critical flows and state setup are covered
+- `weak`
+  - campaign runs but misses meaningful state setup or assertions
+- `missing`
+  - no viable harness exists
+
+## Failure Interpretation
+
+- A failing property is not a finding by itself.
+- Root cause and exploit relevance determine whether a failure is audit-relevant.
+- Coverage gaps belong in `coverage_gaps`, not in confirmed failures.

package/dist/skills/web3-fuzzing-and-invariants/scripts/render_fuzz_summary.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""Render a stable Web3 fuzzing summary block."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Render a Web3 fuzzing summary block.")
+    parser.add_argument("--scope", required=True)
+    parser.add_argument(
+        "--campaign-status", choices=("ready", "partial", "blocked"), default="partial"
+    )
+    parser.add_argument(
+        "--harness-status", choices=("strong", "weak", "missing"), default="weak"
+    )
+    parser.add_argument("--invariant", action="append", default=[])
+    parser.add_argument("--failing-case-count", type=int, default=0)
+    parser.add_argument(
+        "--exploit-relevance", choices=("high", "medium", "low", "unknown"), default="unknown"
+    )
+    parser.add_argument("--coverage-gap", action="append", default=[])
+    parser.add_argument("--next-step", action="append", default=[])
+    parser.add_argument("--evidence", action="append", default=[])
+    return parser
+
+
+def parse_evidence(entries: list[str]) -> list[dict[str, str]]:
+    parsed = []
+    for entry in entries:
+        adapter, sep, detail = entry.partition(":")
+        if sep:
+            parsed.append({"adapter": adapter.strip(), "detail": detail.strip()})
+        else:
+            parsed.append({"adapter": "unknown", "detail": entry})
+    return parsed
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    payload = {
+        "fuzz_summary": {
+            "version": 1,
+            "campaign_status": args.campaign_status,
+            "scope": args.scope,
+            "harness_status": args.harness_status,
+            "invariant_set": args.invariant,
+            "failing_case_count": args.failing_case_count,
+            "exploit_relevance": args.exploit_relevance,
+            "coverage_gaps": args.coverage_gap,
+            "next_steps": args.next_step,
+            "evidence": parse_evidence(args.evidence),
+        }
+    }
+    json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())