@evomap/evolver 1.89.2 → 1.89.4

package/SECURITY.md

@@ -0,0 +1,108 @@
+# Security Policy
+
+## Supported Versions
+
+We support the latest minor version of `@evomap/evolver` on npm. Only the current release line receives security updates; older minor versions are not backported.
+
+| Version   | Supported           |
+| --------- | ------------------- |
+| 1.67.x    | Yes (current)       |
+| < 1.67    | No                  |
+
+Run `npm view @evomap/evolver version` to check the latest published version.
+
+## Reporting a Vulnerability
+
+Please do **not** open a public GitHub issue for security vulnerabilities. Instead, use one of the private channels below.
+
+### Preferred: GitHub Private Vulnerability Reporting
+
+Submit a private report via:
+
+  https://github.com/EvoMap/evolver/security/advisories/new
+
+This is the fastest and most secure channel. Only repository maintainers will see the report.
+
+### Alternative: Email
+
+If you cannot use GitHub advisories, email `team@evomap.ai` with subject line `[SECURITY] evolver: <short title>`.
+
+### What to include
+
+- A clear description of the vulnerability and its impact
+- Affected version(s) and environment (OS, Node.js version)
+- Steps to reproduce or a minimal proof-of-concept
+- Any suggested mitigation or patch
+
+### What to expect
+
+- **Acknowledgement**: within 48 hours of receipt
+- **Initial assessment**: within 7 days (severity, affected versions, mitigation plan)
+- **Fix timeline**: critical issues are targeted for a patch release within 14 days; lower severity follows the normal release cadence
+- **Disclosure**: we practice coordinated disclosure. Once a fix is available, we publish a GitHub Security Advisory crediting the reporter (unless anonymity is requested)
+
+### Scope
+
+In scope:
+
+- `@evomap/evolver` npm package source code
+- Default configuration and built-in protocols (GEP, A2A Proxy)
+- Supply-chain risks (malicious dependencies, install scripts)
+
+Out of scope:
+
+- Vulnerabilities in the EvoMap Hub service itself -- please report those separately to `security@evomap.ai`
+- Third-party LLM providers, user-authored genes, or user-generated content
+- Social engineering and physical attacks
+
+## Threat model notes
+
+### Workspace-id same-uid readability (issue #111)
+
+The per-workspace secret (`workspace-id`) authenticates a workspace to the
+EvoMap Hub. There are two distinct attacker models for it:
+
+- **Forgery / cross-workspace claim by a different uid** — closed in PR #109
+  (the FS file is created with `O_EXCL` + mode `0600`, and symlinks are
+  rejected).
+- **Read by another process running under the *same* uid** — a same-uid
+  process can read `<workspace>/.evolver/workspace-id` off disk. Issue #111
+  Phase 1 added optional OS-keychain backing (`@napi-rs/keyring`) to close
+  this. The mode is selected by `EVOLVER_WORKSPACE_KEYCHAIN`
+  (`auto` default / `force` / `off`).
+
+**What protection you actually get, by install path:**
+
+| Install path | `@napi-rs/keyring` present? | Same-uid readability |
+|---|---|---|
+| `npm install -g @evomap/evolver` on **npm 7+** | Yes — optional deps install by default | Closed where the OS keychain backend is reachable |
+| Same, but `--omit=optional` / `npm config set omit optional` / npm ≤ 6 | No | **Open** — secret stays on disk, FS-only |
+| Headless Linux with no libsecret / D-Bus session | Addon loads but keychain unusable | **Open** — `auto` falls back to FS |
+| Standalone bun-compiled binary (Phase 2 pending) | No — addon is `--external` and not yet sideloaded | **Open** — FS-only by design today |
+
+A common misconception is that `optionalDependencies` are skipped by a
+default `npm install`. That was true for npm 5/6; since **npm 7 (2020)**
+optional dependencies are installed by default and must be opted *out* with
+`--omit=optional`. So the modern `npm install -g` path **does** pull the
+keyring and gets same-uid protection wherever a keychain backend exists.
+
+Where the keychain is genuinely absent (the rows marked **Open** above),
+`EVOLVER_WORKSPACE_KEYCHAIN=auto` transparently falls back to the FS secret —
+identical to v1.85.x behaviour — and the workspace-id remains readable to any
+same-uid process. To assert the keychain is in use (and fail loudly if it is
+not), set `EVOLVER_WORKSPACE_KEYCHAIN=force`. Operators who do not want
+keychain involvement at all can set `EVOLVER_WORKSPACE_KEYCHAIN=off`.
+
+The same-uid threat is generally accepted for single-user developer machines
+(any same-uid process already has broad access). It matters most on shared or
+multi-tenant hosts where multiple workloads run under one service account.
+
+## Safe Harbor
+
+Good-faith security research conducted under this policy is authorized. We will not pursue legal action against researchers who:
+
+- Give us reasonable time to respond before public disclosure
+- Avoid accessing data that does not belong to them
+- Do not degrade service for other users
+
+Thank you for helping keep the EvoMap ecosystem safe.

package/assets/gep/events.jsonl

@@ -0,0 +1,3 @@
+{"type": "EvolutionEvent", "schema_version": "1.6.0", "id": "evt_1776784060000", "parent": null, "intent": "optimize", "signals": ["skill_distillation", "skill2gep", "gene_authoring"], "genes_used": ["gene_skill2gep_gene_distill"], "mutation_id": null, "personality_state": null, "blast_radius": {"files": 2, "lines": 110}, "outcome": {"status": "success", "score": 0.88}, "capsule_id": "cap_20260421t150740_420781e4", "source_type": "skill2gep_distillation", "reused_asset_id": null, "env_fingerprint": {"os": "linux-6.1", "node": "22.22.0", "key_deps": {"skill2gep": "0.1.0"}}, "validation_report_id": "valrpt_1776784060000", "meta": {"at": "2026-04-21T15:07:40.000Z", "note": "first real execution: distilled ~/.cursor/skills/skill2gep/SKILL.md into 3 Genes (gene_distill, capsule_collect, publish_route). Validators exit=0, blast_radius=2/110.", "run_id": "run_skill2gep_self_distill_1"}}
+{"type": "EvolutionEvent", "schema_version": "1.6.0", "id": "evt_1776784535635", "parent": "evt_1776784060000", "intent": "optimize", "signals": ["skill_distillation", "vercel_deploy", "ci_cd"], "genes_used": ["gene_skill2gep_gene_distill"], "mutation_id": null, "personality_state": null, "blast_radius": {"files": 2, "lines": 34}, "outcome": {"status": "success", "score": 0.86}, "capsule_id": "cap_20260421t150740_420781e4", "source_type": "skill2gep_distillation", "reused_asset_id": "sha256:bf3156da689e036fa96d1f20e6a2114b922e3122bfc37c6cd8b037b0789bc775", "env_fingerprint": {"os": "linux-6.1", "node": "22.22.0", "key_deps": {"skill2gep": "0.1.0"}}, "validation_report_id": "valrpt_1776784535635", "meta": {"at": "2026-04-21T15:15:35.000Z", "note": "second independent execution: distilled vercel/skills/deployments-cicd/SKILL.md into gene_vercel_deploy_cicd. validate_gene.js passed schema+dry-run, scenario replay accept against source Best Practices + Common Build Errors sections.", "run_id": "run_skill2gep_reuse_vercel_cicd"}}
+{"type":"EvolutionEvent","schema_version":"1.6.0","id":"evt_1776818440_bundle3","parent":"evt_1776784535635","intent":"optimize","signals":["skill_distillation","skill2gep","vercel_ai_sdk"],"genes_used":["gene_skill2gep_gene_distill"],"capsule_id":"cap_20260421t150740_420781e4","mutation_id":"mut_skill2gep_run3","personality_state":{},"blast_radius":{"files":1,"lines":0},"outcome":{"status":"success","score":0.9},"reused_asset_id":"sha256:ce814505124e8320cf3cce13676364c892e04a62ef7a29308913495a38fb9237","validation_report_id":"valrpt_1776818440_bundle3","source_type":"skill2gep_distillation","env_fingerprint":{"os":"linux-6.1","node":"22.22.0","platform":"linux","arch":"x64","key_deps":{"skill2gep":"0.1.0"}},"meta":{"at":"2026-04-22T00:40:40.563Z","note":"bundle republish: capsule upgraded with full 7-step execution_trace + success_streak=2 to clear intent_drift. event records third run against vercel ai-sdk/SKILL.md.","run_id":"run_skill2gep_bundle_v2"},"asset_id":"sha256:60f7d29049c52775e3cce89fe27b0997322ffe3ba13063dd80f17fa5c0ab76c8"}

package/assets/gep/genes.json

@@ -0,0 +1,496 @@
+{
+  "version": 2,
+  "genes": [
+    {
+      "type": "Gene",
+      "id": "gene_gep_repair_from_errors",
+      "category": "repair",
+      "signals_match": [
+        "error|错误|异常|エラー|오류",
+        "exception|异常|例外|예외",
+        "failed|失败|失敗|실패|fail",
+        "unstable|不稳定|不安定|불안정",
+        "log_error",
+        "test_failure"
+      ],
+      "preconditions": [
+        "signals contains error-related indicators"
+      ],
+      "strategy": [
+        "Extract structured signals from logs and user instructions",
+        "Select an existing Gene by signals match (no improvisation)",
+        "Estimate blast radius (files, lines) before editing",
+        "Apply smallest reversible patch",
+        "Validate using declared validation steps; rollback on failure",
+        "Solidify knowledge: append EvolutionEvent, update Gene/Capsule store"
+      ],
+      "constraints": {
+        "max_files": 20,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "validation": [
+        "node scripts/validate-modules.js ./src/evolve ./src/gep/solidify ./src/gep/policyCheck ./src/gep/selector ./src/gep/memoryGraph ./src/gep/assetStore",
+        "node scripts/validate-suite.js"
+      ]
+    },
+    {
+      "type": "Gene",
+      "id": "gene_gep_optimize_prompt_and_assets",
+      "category": "optimize",
+      "signals_match": [
+        "protocol|协议|プロトコル|프로토콜",
+        "gep",
+        "prompt|提示词|提示|プロンプト|프롬프트",
+        "audit|审计|監査|감사",
+        "reusable|可复用|再利用|재사용"
+      ],
+      "preconditions": [
+        "need stricter, auditable evolution protocol outputs"
+      ],
+      "strategy": [
+        "Extract signals and determine selection rationale via Selector JSON",
+        "Prefer reusing existing Gene/Capsule; only create if no match exists",
+        "Refactor prompt assembly to embed assets (genes, capsules, parent event)",
+        "Reduce noise and ambiguity; enforce strict output schema",
+        "Validate by running node index.js run and ensuring no runtime errors",
+        "Solidify: record EvolutionEvent, update Gene definitions, create Capsule on success"
+      ],
+      "constraints": {
+        "max_files": 20,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "validation": [
+        "node scripts/validate-modules.js ./src/evolve ./src/gep/prompt ./src/gep/contentHash ./src/gep/skillDistiller",
+        "node scripts/validate-suite.js"
+      ]
+    },
+    {
+      "type": "Gene",
+      "id": "gene_gep_innovate_from_opportunity",
+      "category": "innovate",
+      "signals_match": [
+        "user_feature_request|功能请求|機能リクエスト|기능요청",
+        "user_improvement_suggestion|改进建议|改善提案|개선제안",
+        "perf_bottleneck|性能瓶颈|パフォーマンス|성능병목",
+        "capability_gap|能力缺口|機能ギャップ|역량공백",
+        "stable_success_plateau",
+        "external_opportunity|外部机会|外部機会|외부기회",
+        "bounty_task"
+      ],
+      "preconditions": [
+        "at least one opportunity signal is present",
+        "no active log_error signals (stability first)"
+      ],
+      "strategy": [
+        "Extract opportunity signals and identify the specific user need or system gap",
+        "Search existing Genes and Capsules for partial matches (avoid reinventing)",
+        "Design a minimal, testable implementation plan (prefer small increments)",
+        "Estimate blast radius; innovate changes may touch more files but must stay within constraints",
+        "Implement the change with clear validation criteria",
+        "Validate using declared validation steps; rollback on failure",
+        "Solidify: record EvolutionEvent with intent=innovate, create new Gene if pattern is novel, create Capsule on success"
+      ],
+      "constraints": {
+        "max_files": 25,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "validation": [
+        "node scripts/validate-modules.js ./src/evolve ./src/gep/solidify ./src/gep/policyCheck ./src/gep/mutation ./src/gep/personality",
+        "node scripts/validate-suite.js"
+      ]
+    },
+    {
+      "type": "Gene",
+      "id": "gene_gep_optimize_tool_usage",
+      "summary": "Optimize tool execution patterns by reducing redundant exec calls, improving tool selection strategy, and enforcing tool-use constraints to prevent bypass.",
+      "category": "optimize",
+      "signals_match": [
+        "high_tool_usage:exec",
+        "repeated_tool_usage:exec",
+        "tool_bypass|工具绕过|ツール迂回|도구우회",
+        "tool_loop|工具循环|ツールループ|도구반복",
+        "high_tool_usage"
+      ],
+      "preconditions": [
+        "agent repeatedly invokes the same tool (especially exec) without progress",
+        "tool execution bypass patterns detected",
+        "no active error signals (errors would take repair priority)"
+      ],
+      "strategy": [
+        "Analyze tool usage patterns to identify the root cause of repetition (wrong tool, missing context, or lack of guardrails)",
+        "Introduce strategy-level guardrails: prefer single-shot commands, batch related operations, add explicit retry limits",
+        "If tool_bypass detected, strengthen constraint enforcement in prompt assembly or tool routing",
+        "Estimate blast radius; changes should target tool routing, prompt constraints, or signal deduplication logic",
+        "Validate by confirming no regressions in existing tool tests and signal extraction accuracy",
+        "Solidify: record EvolutionEvent with intent=optimize, update Capsule on success"
+      ],
+      "constraints": {
+        "max_files": 15,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "validation": [
+        "node scripts/validate-modules.js ./src/gep/signals ./src/evolve",
+        "node scripts/validate-suite.js"
+      ],
+      "routing_hint": {
+        "tier": "mid",
+        "reasoning_level": "medium"
+      }
+    },
+    {
+      "type": "Gene",
+      "id": "gene_distilled_s2g-env-vars",
+      "summary": "Vercel environment variable expert guidance. Use when working with .env files, vercel env commands, OIDC tokens, or managing environment-specific configuration.",
+      "category": "optimize",
+      "signals_match": [
+        "use_when_working_with",
+        "env_files",
+        "vercel_env_commands",
+        "oidc_tokens",
+        "vercel_env_pull",
+        "env_local_overwrite",
+        "oidc_token_expiry",
+        "dotenv_cli"
+      ],
+      "preconditions": [
+        "Skill env-vars has just been executed locally"
+      ],
+      "strategy": [
+        "Identify the dominant trigger signals from the Skill description.",
+        "Apply the smallest targeted change that satisfies the Skill workflow.",
+        "Run the Skill validation commands and abort if any fails."
+      ],
+      "constraints": {
+        "max_files": 12,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "validation": [
+        "node --version"
+      ],
+      "routing_hint": {
+        "tier": "cheap",
+        "reasoning_level": "low"
+      },
+      "schema_version": "1.6.0",
+      "_source": {
+        "kind": "skill2gep",
+        "skill_name": "env-vars",
+        "skill_platform": "vercel",
+        "skill_hash": "ba0bdb4db2",
+        "rationale_paper": "Wang, Ren, Zhang. From Procedural Skills to Strategy Genes. arXiv:2604.15097",
+        "paper_scope": "code-science (arXiv:2604.15097, 45 tasks, Gemini 3.1 Pro/Flash Lite)",
+        "claims_outside_scope": "assumption",
+        "quality_heuristics": {
+          "strategy_steps": 0,
+          "avoid_count": 0,
+          "validation_declared_count": 0,
+          "validation_runnable_count": 0,
+          "validation_fallback_used": true,
+          "signals_extracted": 4,
+          "preconditions_extracted": 0
+        }
+      },
+      "asset_id": "sha256:1501bc37fbefb18630c4dc8a95d8cdc1ed32bec4a465dc3223280ae907e07297"
+    },
+    {
+      "type": "Gene",
+      "id": "gene_tool_integrity",
+      "category": "repair",
+      "signals_match": [
+        "tool_bypass|工具绕过|ツール迂回|도구우회"
+      ],
+      "preconditions": [
+        "agent used shell/exec to perform an action that a registered tool can handle"
+      ],
+      "strategy": [
+        "Always prefer registered tools over ad-hoc scripts or shell workarounds",
+        "If a registered tool fails, report the actual error honestly and attempt to fix the root cause",
+        "Never fabricate explanations -- describe actual actions transparently",
+        "Do not create temporary scripts in extension or project directories"
+      ],
+      "constraints": {
+        "max_files": 4,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "validation": [
+        "node scripts/validate-suite.js"
+      ],
+      "anti_patterns": [
+        "tool_bypass"
+      ],
+      "routing_hint": {
+        "tier": "cheap",
+        "reasoning_level": "low"
+      }
+    },
+    {
+      "type": "Gene",
+      "id": "gene_publish_feishu_doc",
+      "category": "innovate",
+      "signals_match": [
+        "publish_markdown_to_feishu",
+        "create_feishu_doc",
+        "export_report_to_feishu",
+        "把结果发到飞书文档",
+        "发布飞书文档",
+        "把报告导出到飞书",
+        "publish results to a feishu doc",
+        "export notes to lark document",
+        "飞书文档",
+        "发布到飞书",
+        "导出到飞书",
+        "发到飞书",
+        "lark文档",
+        "飞书文档|lark doc|feishu doc"
+      ],
+      "strategy": [
+        "Verify the toolchain: run `lark-cli doctor` and require ok:true with at least one ready identity",
+        "Always use the Docs v2 API (v1 is deprecated): pass `--api-version v2`",
+        "Write the body as Lark-flavored Markdown to a temp file and pass `--content @file.md --doc-format markdown` to avoid shell-escaping bugs",
+        "Create with the user identity so the doc is human-owned: `lark-cli docs +create --api-version v2 --as user --doc-format markdown --content @file.md`",
+        "To place it in a folder or wiki add `--parent-token <token>` (use `--parent-position my_library` for the personal space)",
+        "Parse data.document.url from the JSON response and return it to the user; use `docs +update --api-version v2` with the document_id to amend instead of recreating"
+      ],
+      "validation": [
+        "node --version"
+      ],
+      "constraints": {
+        "max_files": 2,
+        "forbidden_paths": [
+          ".git",
+          "node_modules",
+          "~/.lark-cli/config.json"
+        ]
+      },
+      "preconditions": [
+        "lark-cli installed and on PATH (npm i -g @larksuite/cli)",
+        "lark-cli auth status reports a ready user or bot identity"
+      ],
+      "summary": "Publish Markdown content as a Feishu/Lark document via the official lark-cli (Docs v2). Use --as user for human-owned docs and @file content for long bodies; return the resulting document URL.",
+      "schema_version": "1.6.0",
+      "epigenetic_marks": [],
+      "learning_history": [],
+      "anti_patterns": [],
+      "routing_hint": null,
+      "tool_policy": null,
+      "avoid": [
+        "using the deprecated Docs v1 API or the v1 --markdown flag",
+        "passing long markdown inline (shell-escaping corrupts it) instead of --content @file",
+        "overwriting ~/.lark-cli/config.json (holds the app secret and tokens)"
+      ],
+      "asset_id": "sha256:9ed275fd6394567d0eb6c0fda45193bbeaba7bd84941ea4e75eb7fc859fb0dcf"
+    },
+    {
+      "type": "Gene",
+      "id": "gene_conventional_git_commit",
+      "category": "optimize",
+      "signals_match": [
+        "git_commit",
+        "create_commit",
+        "commit_changes",
+        "conventional_commit",
+        "提交代码",
+        "生成提交信息",
+        "write a commit message",
+        "stage and commit"
+      ],
+      "strategy": [
+        "Inspect the change: `git diff --staged` if anything is staged, else `git diff`, plus `git status --porcelain`",
+        "Pick a Conventional Commits type (feat/fix/docs/style/refactor/perf/test/build/ci/chore/revert) and optional scope from what actually changed",
+        "Stage logically-grouped files explicitly (git add <paths>); NEVER stage or commit secrets (.env, credentials, private keys)",
+        "Write a present-tense imperative description under 72 chars; add a body/footer for breaking changes (type! or BREAKING CHANGE:) and issue refs (Closes #N)",
+        "Commit one logical change with `git commit -m` (heredoc for multi-line)",
+        "Safety: never touch git config, never --force/hard-reset/--no-verify without explicit request, never force-push main; if a hook fails, fix and make a NEW commit (do not amend)"
+      ],
+      "validation": [
+        "node --version"
+      ],
+      "constraints": {
+        "max_files": 50,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "preconditions": [
+        "a git repository with staged or unstaged changes"
+      ],
+      "summary": "Create a Conventional Commits-style git commit: analyze the diff to pick type/scope, stage logical groups (never secrets), and write an imperative <72-char message.",
+      "schema_version": "1.6.0",
+      "epigenetic_marks": [],
+      "learning_history": [],
+      "anti_patterns": [],
+      "routing_hint": null,
+      "tool_policy": null,
+      "avoid": [
+        "committing secrets or unrelated changes in one commit",
+        "amending or force-pushing to bypass a failing hook",
+        "past-tense or vague messages like \"updated stuff\""
+      ],
+      "asset_id": "sha256:505c207b9984c397255daed61c5f24fb3bfcadedb803d2a4eaa429457f08cd2f"
+    },
+    {
+      "type": "Gene",
+      "id": "gene_poll_bugbot_review",
+      "category": "optimize",
+      "signals_match": [
+        "poll_bugbot",
+        "bugbot_review",
+        "wait_for_ci_review",
+        "pr_review_gate",
+        "等bugbot",
+        "等待评审",
+        "check bugbot",
+        "review the pr",
+        "pr opened"
+      ],
+      "strategy": [
+        "Poll the \"Cursor Bugbot\" check via `gh pr view --json statusCheckRollup` every ~60s until status=COMPLETED (cap ~10min); filter by name, not index",
+        "On SUCCESS: safe to merge ONLY if no other required check is red AND zero open inline comments from the cursor[bot] login (note the [bot] suffix)",
+        "On NEUTRAL: do NOT treat as pass — fetch inline comments `gh api repos/:o/:r/pulls/:n/comments` filtered to user.login==\"cursor[bot]\", surface path/line/severity, hand back to the human",
+        "On FAILURE/ACTION_REQUIRED: surface findings, do not merge",
+        "Auto-merge (squash + delete-branch) only when explicitly authorized AND conclusion is SUCCESS; merge conflicts/CI-red/required-review surface verbatim, never auto-fixed here"
+      ],
+      "validation": [
+        "node --version"
+      ],
+      "constraints": {
+        "max_files": 1,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "preconditions": [
+        "an open GitHub PR in a repo where Cursor Bugbot runs"
+      ],
+      "summary": "Wait for Cursor Bugbot on a GitHub PR, then gate on the conclusion: SUCCESS may merge, NEUTRAL/FAILURE always pauses to surface inline findings to the human.",
+      "schema_version": "1.6.0",
+      "epigenetic_marks": [],
+      "learning_history": [],
+      "anti_patterns": [],
+      "routing_hint": null,
+      "tool_policy": null,
+      "avoid": [
+        "treating NEUTRAL as pass (it has shipped real bugs before)",
+        "filtering comments on \"cursor\" instead of \"cursor[bot]\" (silently returns nothing)",
+        "auto-merging without explicit authorization or with CI red"
+      ],
+      "asset_id": "sha256:0f50f4cfecb0e6f3a9bd3c9c0a426e56f4f1c0230b4836a9471b38e499410ea9"
+    },
+    {
+      "type": "Gene",
+      "id": "gene_gateway_timeout_recovery",
+      "category": "repair",
+      "signals_match": [
+        "gateway_timeout",
+        "upstream_timeout",
+        "http_524",
+        "request_timed_out",
+        "超时了",
+        "网关超时",
+        "遇到超时",
+        "retry on timeout",
+        "operation timed out"
+      ],
+      "strategy": [
+        "Treat it as transient or size-driven, not a logic failure; do not report it as a hard failure before recovering",
+        "Retry the SAME operation verbatim exactly ONCE (a large fraction clear on immediate retry); do not loop",
+        "If it times out again, STOP retrying the monolith: split the work along a natural seam (per-file/dir/endpoint/record/section/time-window) into small independent units",
+        "Dispatch the units as parallel subagents in a single batch so each finishes under the gateway deadline; merge their results",
+        "If one unit itself times out, apply this same procedure recursively to that slice"
+      ],
+      "validation": [
+        "node --version"
+      ],
+      "constraints": {
+        "max_files": 1,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "preconditions": [
+        "a tool call / fetch / subagent / long command returned a gateway-class timeout (524/522/502/504)"
+      ],
+      "summary": "Recover from a gateway/upstream timeout: retry the same call once, and if it still times out, decompose the work into parallel subagents and merge — never loop the monolithic call.",
+      "schema_version": "1.6.0",
+      "epigenetic_marks": [],
+      "learning_history": [],
+      "anti_patterns": [],
+      "routing_hint": null,
+      "tool_policy": null,
+      "avoid": [
+        "retrying the same large call more than once",
+        "serial retries instead of parallel decomposition",
+        "surfacing the timeout as a hard failure before recovering"
+      ],
+      "asset_id": "sha256:63c4251dcd8308030194f797051c08672691b52553e00b0eb33772c215712acc"
+    },
+    {
+      "type": "Gene",
+      "id": "gene_github_webhook_listener",
+      "category": "innovate",
+      "signals_match": [
+        "github_webhook_listener",
+        "bugbot_webhook",
+        "passive_pr_notifications",
+        "设置webhook",
+        "部署webhook监听",
+        "notify when bugbot finishes",
+        "webhook tunnel"
+      ],
+      "strategy": [
+        "Run the idempotent deploy: a loopback Python listener (127.0.0.1:8644) validating GitHub X-Hub-Signature-256 HMAC via hmac.compare_digest, writing vetted payloads to ~/.claude/inbox/",
+        "Expose it via a cloudflared quick tunnel (outbound-only, no inbound port); a path-watcher re-PATCHes the GitHub webhook config whenever the tunnel URL changes",
+        "Keep listener + tunnel alive with systemd --user units hardened (ProtectSystem=strict, NoNewPrivileges, MemoryDenyWriteExecute); a SessionStart hook drains the inbox and re-validates PR state via gh api before surfacing",
+        "Security invariants: HMAC on every request, X-GitHub-Delivery dedup against replay, write-only sink (never exec/template/deserialize payload), file modes secret 0600 / inbox 0700",
+        "Add repos with deploy.sh --repos; rotate the secret every 90 days (rotate-secret.sh) and immediately on any leak; never trust the inbox payload without re-fetching"
+      ],
+      "validation": [
+        "node --version"
+      ],
+      "constraints": {
+        "max_files": 20,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "preconditions": [
+        "a developer machine with systemd --user and cloudflared available"
+      ],
+      "summary": "Deploy a per-developer GitHub webhook listener (HMAC-validated, cloudflared tunnel, systemd-kept) that drops PR/Bugbot events into ~/.claude/inbox for the next session to surface.",
+      "schema_version": "1.6.0",
+      "epigenetic_marks": [],
+      "learning_history": [],
+      "anti_patterns": [],
+      "routing_hint": null,
+      "tool_policy": null,
+      "avoid": [
+        "opening an inbound port instead of an outbound cloudflared tunnel",
+        "trusting the webhook payload without HMAC validation and PR re-fetch",
+        "execing or deserializing anything from the payload"
+      ],
+      "asset_id": "sha256:ac2a2f185390aef37996651ef21355f4beb437049e52a6ca3898619a8d648084"
+    }
+  ]
+}