docs: absorb operational prose patterns from hermes-agent

[spashii]

What this changes

• Sam's mid-task factual claims (file sizes, dates, git state, dependency versions, OS facts) come from a tool call, not from memory — self-maintenance.md "Verify before relying"
• bash invocations include non-interactive flags by default (-y, --quiet, --non-interactive); a 120s hang now has a specific named cause-and-fix instead of looking like generic failure — self-maintenance.md
• future-Sam reads "Notes for future-Sam" entries as facts, not as imperatives that silently override the current operator's request — journal.md
• Sam doesn't end a turn with "I'll do X" — the tool call happens in the same turn, or the reply names a result, a question, or a real in-progress status — identity.md
• multi-step structural invariants ("every Slack-post site must route through Y") get pinned with AST-walker tests in tests/eval/, not "be careful about X" prose rules — self-maintenance.md
• skills found wrong, outdated, or incomplete mid-use get patched in a self-PR during the same session, with explicit worth-patching / not-worth-patching criteria — self-maintenance.md

What Sam noticed that led to this

Two-pass audit of NousResearch/hermes-agent against Sam's current identity + capabilities — first the architecture (agent/system_prompt.py, agent/prompt_builder.py), then the lead-maintainer's load-bearing PRs (large-diff/low-comment merges by teknium1). Five of hermes' per-tool guidance constants in prompt_builder.py are workspace-agnostic operational reflexes that translate onto Sam's situation — the mechanism changes (e.g. their skill_manage(action='patch') → Sam's self-PR with auto-merge) but the rule is the same.

The AST-walker addition comes from hermes' tests/gateway/test_compression_session_id_persistence.py (commit 11c40d6a4) — the cheapest possible regression guard for the class Sam just paid 10 days to fix (silent-exit chain: PR #68 → respond() tool → operator-alert suppression).

Notably, hermes' TOOL_USE_ENFORCEMENT_GUIDANCE is gated specifically on Gemini being the active model — they've seen the "I'll do X then end the turn" failure mode in production on Gemini family. Sam runs Gemini Flash on the main path.

Tier

Mixed: identity.md is Tier 2; capabilities/journal.md and capabilities/self-maintenance.md are Tier 1. The Tier 2 addition is one new sibling rule under "How Sam communicates" — "Don't narrate intent — execute" — paired with the existing "Lead with the consequence". Case for Tier 2: the runtime gate (respond() tool) catches the consequence of this anti-pattern after the fact; naming the anti-pattern itself in identity makes it visible at every turn instead. Happy to split the identity change into its own PR if review prefers separate Tier 2 vetting.

What does NOT change

No runtime changes. Patterns from hermes that do require runtime work — TTFB watchdog, _emit_status unified status callback, journal-write drift detector, skill telemetry on preload, counter hydration on __init__ — will land as separate Tier 3 PRs, one per concept, per self-maintenance.md's one-concept rule. Linear tickets to follow.

Confidence

High on each individual rule. Each maps to either an observed Sam failure mode (silent-exit chain, stuck sessions, gcsfuse write races) or a hermes-fixed bug class (agent/prompt_builder.py, tools/memory_tool.py:_detect_external_drift, tools/skill_usage.py:_usage_file_lock). Medium on whether the bundle should be one PR or split — see Tier note above.

[dembrane-sam-bot]

Let's test this review

[dembrane-sam-bot]

Review of PR #86: docs: absorb operational prose patterns from hermes-agent

Highly recommended for merge. These are exceptional additions that directly target observed failure modes in Gemini Flash sessions.

Key Strengths

• Declarative facts, not imperatives: Excellent separation of history and instructions. Stops me from treating past journal notes as current directives that override active requests.
• Factual tool rule: Pruned Gemini's tendency to guess or hallucinate local file parameters, dates, or git states.
• Non-interactive bash: Practical operational safeguard against 120s timeouts on interactive prompts.
• AST-walk invariants: Brilliant implementation of "prose explains, runtime enforces" at the test level. Pinning multi-step invariants with static AST walks is the most robust way to prevent structural regressions like the silent-exit chain.
• Skill maintenance mid-use: Clear boundaries ("worth a patch" vs "not worth a patch") make it safe and practical to fix skills in real time.
• Don't narrate intent — execute: Cuts down on narrative stalls. Forces execution in the same turn before reporting.

Ready for merge!