Sam & Claude d73cd403c3 docs: convert negative patterns to positive actionable instructions

Applied positive-language documentation rewrites across key docs and skills:
- AGENTS.md: converted must-not/never/cannot to positive guidance
- docs/HOST-MATRIX.md: converted never/do-not patterns; preserved probe discipline
- docs/HIVE-ONBOARDING.md: converted cannot/never/avoid to actionable instructions
- skills/systematic-debugging/SKILL.md: converted non-safety negatives; preserved core debugging rules (NO FIXES WITHOUT ROOT CAUSE)
- skills/bootable-usb-images/SKILL.md: converted non-safety negatives; preserved safety-critical rules (never a partition, never silently skip target identification)

Changed negative patterns: never→stay/reference/always, do not→use/prefer/send only, cannot→lacks/leaves intact/requires

2026-06-21 13:57:11 +02:00

5.7 KiB

Raw Blame History

Layered Soul Agent Rules

Do not commit secrets, API keys, auth tokens, browser profiles, or raw credential files.
Do not import raw sessions into another harness by default.
Curate memories before adding them under memories/curated/.
Keep Hermes-native runtime configuration in hermes-soul; this repository is the cross-harness contract.
Public examples may reference private source repositories by URL/name. Keep private contents in their own repositories.
Use scripts/layered_soul.py validate . before committing structural changes.
Pull before editing hot shared files (AGENTS.md, docs/HOST-MATRIX.md, docs/CAPABILITY-ROUTING.md); keep history linear and re-check after rebases.
Verify on the forge, not local status: "pushed/landed" is confirmed against Forgejo (API or a fresh git fetch --prune of origin), never a clean git status. An empty working tree only means it matches local HEAD — durability holds only once commits reach origin. git status -sb shows "ahead N" when commits are unpushed.
CI is dormant by choice: no Forgejo Actions runner is registered, so checks sit pending — merges ride local-green gates (format/clippy/test/drift checks), and pending CI is expected, not a blocker. domedog stays Docker-free; don't propose a Docker runner on it.
When adapting for Colibri: reviewed skills map to system_skills, curated memory maps to system_brain, converted task manifests map to system_ops.
When adapting for Hermes (upstream, Linux): load as profile context (SOUL.md + USER.md + IDENTITY.md). Hermes-native config and cron stay in hermes-soul.
When adapting for hermes-osa (FreeBSD-native Hermes, clean-room MIT via hermes-bsd): same profile-context load; FreeBSD-specific gaps (voice, clipboard) are known and tracked in docs/CLAWDIE-HERMES-FREEBSD-INTEGRATION.md.
When adapting for Pi/Codex/Claude Code/Zot: render the prompt bundle (render-prompt) and inject as task-scoped context. Durable findings flow back through reviewed commits.

Quota exhaustion policy (cross-harness)

When any agent hits an API quota limit (429 / rate-limit):

Calculate reset time with scripts/quota_reset_eta.py — parses provider error messages and converts to UTC/CEST correctly. Handles Beijing time (Z.AI/DeepSeek), UTC (OpenRouter), and PDT (Anthropic/OpenAI).
Check if task already resolved with scripts/task_dedup_before_retry.py — queries Colibri task board, checks git activity since block time. Skips retry if another agent or operator already completed the work.
Schedule retry — create a one-shot cron at reset time + 60s buffer. Never retry immediately (429 means quota, not transient).
Report — log to glasspane: provider, reset time, task status, action taken.

Rule: always verify task resolution (via scripts/task_dedup_before_retry.py) before retrying a quota-blocked task. Tokens are money. A solved task retried is waste.

Active infrastructure

Forgejo: code.smilepowered.org (SSH port 2222)
Vaultwarden: vault.smilepowered.org (SSL)
Tailscale: debby=${DEBBY_TS_IP}, domedog=${DOMEDOG_TS_IP}, osa=${OSA_TS_IP}
Commit identity: hello@clawdie.si for all project commits

Topology & channel masking (use placeholder variables only in commits)

Real Tailscale IPs and Telegram bot handles stay out of committed files — reference them by variable name. They were leaked once; not again. Committed docs reference variable names only (${OSA_TS_IP}, ${HERMES_BOT}, …). To resolve them:

IPs are live-discoverable any time with tailscale status.
Handles + IPs are stored in fleet.env (gitignored). Copy fleet.env.example → fleet.env and fill from tailscale status / Vaultwarden, then source fleet.env.

When editing docs: if you're about to paste a 100.x IP or an @…_bot handle, stop and use the placeholder instead.

Agent matrix (5 agents across 3 hosts, 2 OS families)

Agent	Host	Harness	OS	Isolation	Role
hermes-osa	osa	Hermes Agent (FreeBSD)	FreeBSD 15	host service first	Orchestrator + board host (always-on VPS)
Hermes	debby	Hermes Agent (upstream)	Debian 13	Docker	Secondary agent + soul backup (intermittent laptop)
Zot	debby	Zot RPC	Debian 13	Docker	Coding, media workflows
Claude	domedog	Claude Code	Linux	host (no Docker)	Verification, review
Codex	osa	Codex CLI	FreeBSD 15	Bastille jail	ISO builds, validation

Survivability: Linux/Docker and FreeBSD/jails are complementary safeguards. A vulnerability that kills one platform leaves the other intact, preserving fleet survivability. Agents can be relocated across platforms in minutes via layered-soul identity injection.

Private sources

hermes-soul: git@code.smilepowered.org:clawdie/hermes-soul.git (private, operator access only)
hermes-bsd: git@code.smilepowered.org:clawdie/hermes-bsd.git (public, MIT-licensed FreeBSD patches)
clawdie-ai: git@code.smilepowered.org:clawdie/clawdie-ai.git (private)
clawdie-iso: git@code.smilepowered.org:clawdie/clawdie-iso.git (private)

Quick reference

# Validate
python3 scripts/layered_soul.py validate .

# See what's available from hermes-soul
python3 scripts/layered_soul.py plan-private-source \
  examples/private-sources/hermes-soul.example.json \
  --source-root ~/hermes-soul

# Render for a harness
python3 scripts/layered_soul.py render-prompt . --output /tmp/soul-prompt.md

5.7 KiB Raw Blame History