b32d316023
- SCHEMA.md: full specification for index.json and YAML knowledge files - knowledge/global/pitfalls.yaml: 8 cross-repo pitfalls - knowledge/global/tool-quirks.yaml: 7 environment quirk facts - knowledge/repos/hermes-agent.yaml: 8 per-repo pitfalls (cron, paths, SSH) - knowledge/repos/the-nexus.yaml: 6 per-repo pitfalls (merge, server, deploy) - scripts/validate_knowledge.py: schema validator (29 facts, all passing) - knowledge/index.json: populated with 29 seed facts from real fleet data Design decisions: - YAML for humans, index.json for machines - ID format: domain:category:sequence for dedup and linking - 5 categories: fact, pitfall, pattern, tool-quirk, question - Confidence 0.0-1.0 with defined ranges - Related facts by ID for graph traversal - Tags for searchability - Source count + dates for decay/expiry Acceptance criteria: - [x] Directory structure created - [x] Schema documented (SCHEMA.md) - [x] index.json with real facts (29 total) - [x] Example knowledge files for 2 repos (hermes-agent, the-nexus) - [x] Validation script passes
81 lines
2.2 KiB
YAML
81 lines
2.2 KiB
YAML
---
|
|
domain: hermes-agent
|
|
category: pitfall
|
|
version: 1
|
|
last_updated: "2026-04-13"
|
|
---
|
|
|
|
# Pitfalls (hermes-agent)
|
|
|
|
## Cron & Deployment
|
|
|
|
- id: hermes-agent:pitfall:001
|
|
fact: "deploy-crons.py leaves jobs in mixed model format - some have provider/model, some just model"
|
|
confidence: 0.95
|
|
tags: [cron, deploy, model, config]
|
|
source_count: 5
|
|
first_seen: "2026-04-08"
|
|
last_confirmed: "2026-04-13"
|
|
related: [hermes-agent:pitfall:002, hermes-agent:pitfall:003]
|
|
|
|
- id: hermes-agent:pitfall:002
|
|
fact: "deploy-crons.py --deploy doesn't set legacy skill field from skills list"
|
|
confidence: 0.9
|
|
tags: [cron, deploy, skills]
|
|
source_count: 3
|
|
first_seen: "2026-04-09"
|
|
last_confirmed: "2026-04-13"
|
|
related: [hermes-agent:pitfall:001]
|
|
|
|
- id: hermes-agent:pitfall:003
|
|
fact: "Cron jobs with blank fallback_model fields trigger spurious gateway warnings"
|
|
confidence: 0.9
|
|
tags: [cron, model, fallback]
|
|
source_count: 4
|
|
first_seen: "2026-04-07"
|
|
last_confirmed: "2026-04-12"
|
|
related: [hermes-agent:pitfall:001]
|
|
|
|
- id: hermes-agent:pitfall:004
|
|
fact: "model-watchdog.py checks first provider line, not model.provider - causes false drift alarms"
|
|
confidence: 0.9
|
|
tags: [watchdog, model, config]
|
|
source_count: 3
|
|
first_seen: "2026-04-08"
|
|
last_confirmed: "2026-04-13"
|
|
|
|
## Path & Environment
|
|
|
|
- id: hermes-agent:pitfall:005
|
|
fact: "10+ files read HERMES_HOME directly instead of get_hermes_home() - breaks on custom paths"
|
|
confidence: 0.85
|
|
tags: [paths, env, hermes-home]
|
|
source_count: 6
|
|
first_seen: "2026-04-06"
|
|
last_confirmed: "2026-04-12"
|
|
related: [global:pitfall:002]
|
|
|
|
- id: hermes-agent:pitfall:006
|
|
fact: "get_hermes_home() doesn't expand tilde when HERMES_HOME=~/... is set"
|
|
confidence: 0.8
|
|
tags: [paths, env, bug]
|
|
source_count: 2
|
|
first_seen: "2026-04-05"
|
|
|
|
## SSH & Dispatch
|
|
|
|
- id: hermes-agent:pitfall:007
|
|
fact: "vps-agent-dispatch reports OK while remote hermes binary path is broken"
|
|
confidence: 0.9
|
|
tags: [ssh, dispatch, vps]
|
|
source_count: 4
|
|
first_seen: "2026-04-07"
|
|
last_confirmed: "2026-04-11"
|
|
|
|
- id: hermes-agent:pitfall:008
|
|
fact: "nightwatch-health-monitor SSH check fails on cloud-model-only deployments"
|
|
confidence: 0.85
|
|
tags: [ssh, health, cloud]
|
|
source_count: 2
|
|
first_seen: "2026-04-10"
|