From e98e80984a5adf69928d4bce9d53c3f34d5d1aab Mon Sep 17 00:00:00 2001
From: johba <johba@harb-dev-box>
Date: Tue, 7 Apr 2026 11:40:31 +0000
Subject: [PATCH] feat: add harb-specific triage formula (#16)

Extends the disinto triage template with harb stack lifecycle,
contract investigation hints, API endpoints, and common root causes.
Used by the triage agent for deep investigation of reproduced bugs.
---
 formulas/triage-harb.toml | 87 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 formulas/triage-harb.toml

diff --git a/formulas/triage-harb.toml b/formulas/triage-harb.toml
new file mode 100644
index 0000000..45c7954
--- /dev/null
+++ b/formulas/triage-harb.toml
@@ -0,0 +1,87 @@
+# formulas/triage-harb.toml — Harb-specific triage formula
+#
+# Extends the disinto triage template (formulas/triage.toml) with
+# harb stack lifecycle, data flow, and API endpoints.
+#
+# Triggered by: bug-report + in-triage on johba/harb Forgejo issues.
+
+name            = "triage-harb"
+description     = "Deep root cause analysis for harb — Kraiken staking protocol"
+version         = 1
+extends         = "triage"
+
+stack_script    = "./scripts/dev.sh restart --full"
+tools           = ["playwright"]
+
+[project]
+data_flow       = "chain (Anvil) → contracts (Kraiken/Stake/LM) → events → ponder indexer → PostgreSQL → GraphQL → Vue composables → UI"
+
+api_endpoints   = """
+Anvil RPC:       http://localhost:8545
+Ponder GraphQL:  http://localhost:42069/graphql
+Webapp:          http://localhost:5173/app/
+TxnBot:          http://localhost:43069/status
+Caddy proxy:     http://localhost:8081/app/
+Otterscan:       http://localhost:5100
+"""
+
+stack_lock      = "full"
+
+[project.contracts]
+# Addresses are in tmp/containers/contracts.env after bootstrap.
+# Source them with: export $(cat tmp/containers/contracts.env | xargs)
+env_file        = "tmp/containers/contracts.env"
+key_contracts   = ["Kraiken", "Stake", "LiquidityManager"]
+
+[project.stack]
+# Full lifecycle via scripts/dev.sh
+start           = "./scripts/dev.sh start"
+stop            = "./scripts/dev.sh stop"
+restart_full    = "./scripts/dev.sh restart --full"
+restart_light   = "./scripts/dev.sh restart --light"
+health          = "./scripts/dev.sh health"
+
+# Bootstrap creates contracts and seeds state.
+# After restart --full, wait for all services to be healthy before proceeding.
+# Expected healthy services: anvil, postgres, ponder, webapp, landing, txn-bot, caddy, umami, otterscan
+bootstrap_wait  = 120
+
+[project.investigation_hints]
+# Common patterns for harb bugs
+description     = """
+When investigating harb bugs:
+
+1. Contract state: use cast to read on-chain state
+     export $(cat tmp/containers/contracts.env | xargs)
+     cast call $KRAIKEN "totalSupply()(uint256)" --rpc-url http://localhost:8545
+     cast call $STAKE "getEarnings(uint256)(uint256)" <positionId> --rpc-url http://localhost:8545
+     cast call $LIQUIDITY_MANAGER "positions(uint8)(uint128,int24,int24)" 0 --rpc-url http://localhost:8545
+
+2. Ponder indexed data: query GraphQL
+     curl -sf http://localhost:42069/graphql -H 'Content-Type: application/json' \
+       -d '{"query": "{ stats(id: \\"0x01\\") { holderCount mintedLastDay recentersLastDay lastEthReserve } }"}'
+
+3. Ponder config: check if all addresses are correct
+     cat services/ponder/.env.local | grep -E 'ADDRESS|POOL'
+
+4. UI data: use Playwright MCP to navigate and observe
+     Navigate to http://localhost:5173/app/ (password: test123)
+
+5. Logs: check container logs for errors
+     docker compose logs ponder --tail 50
+     docker compose logs webapp --tail 50
+     docker compose logs anvil --tail 20
+
+6. Common root causes in harb:
+   - Missing or wrong contract addresses in ponder .env.local
+   - AppArmor blocking inside LXD (need security_opt: apparmor=unconfined)
+   - viem v2 returns arrays not named objects for multi-output calls
+   - Ring buffer threshold too high for freshly bootstrapped local chains
+   - Submodules not initialized (onchain/lib/ empty)
+   - kraiken-lib not built (landing/webapp fail to start)
+"""
+
+[project.login]
+# Webapp has a password gate
+url             = "http://localhost:5173/app/"
+password        = "test123"