hermes-write-gates

name	hermes-write-gates
title	Hermes write-approval gates and pending skills queue
description	Class-level workflow for handling Hermes skill/memory write-approval safety gates and safely clearing/processing pending writes.
version	1.0.0
author	Hermes
license	MIT

Hermes write-approval gates and pending skills queue

Scope

Use this when a request concerns:

• turning skills.write_approval (and related) on/off,
• processing pending skill/memory writes,
• clearing pending writes in bulk,
• reviewing/approving/rejecting a batch of queued skill mutations.

This is the default guardrail workflow for all sessions: keep safety gates on by default, then disable only when the user explicitly asks.

Why this exists

Hermes can queue write mutations to skills/memory as pending/skills/*.json until approval. This is good by default because it prevents accidental, low-signal file edits.

Pre-reqs

• know your Hermes home (usually HERMES_HOME, often /srv/codex-klava/data/hermes in this stack)
• user intent is explicit (never remove gates or clear queues on assumption)

Common keys in config.yaml

• memory.write_approval
• skills.write_approval
• approvals.mode

All three live in:

• .../config.yaml under the memory:, skills: and top-level approvals: sections.

approvals.mode controls command-level approval prompts (destructive command confirmation); values should be checked after writes because this Hermes build persists CLI booleans as plain YAML (false may reflect off).

Approval modes (practical)

Setting	Effect
manual (default)	keep command approval prompts
smart	auxiliary model auto-approves low-risk commands
off / false	skip command approval prompts

Fast path: disable both gates (explicit user request)

Use this as a deliberate action, then verify.

1) Disable approvals

hermes config set skills.write_approval false
hermes config set memory.write_approval false
# optional if the user also wants command prompts auto-bypass:
hermes config set approvals.mode off

2) Verify

Confirm all intended values are now in state (skills.write_approval, memory.write_approval, and approvals.mode if set).

3) Inspect pending queue

ls "$HERMES_HOME/pending/skills"

If the gate is disabled, you should usually also consume the queued items promptly (approve/reject/delete).

4) Clear pending queue safely (if user asked for bulk removal)

Always back up first (reversible, keeps auditability):

tmpdir=$(mktemp -d "$HERMES_HOME/.pending-skill-backup-$(date +%s)")
mv "$HERMES_HOME/pending/skills/"*.json "$tmpdir"/

5) Verify empty

ls "$HERMES_HOME/pending/skills"

Approved/manual workflow when gates are on

When the gates are still on and user says “approve/reject”:

1. On messaging surfaces (Telegram, chat, TUI): use:
   • /skills diff <id> for exact diff inspection
   • /skills approve <id>
   • /skills reject <id>
2. On CLI, there is no /skills pending surface yet. Use:
   • ls "$HERMES_HOME/pending/skills" (or equivalent ~/.hermes/pending/skills for that session)
   • inspect JSON payloads directly with cat if needed
3. Also check migration backup locations before concluding there are no queued writes:
   • ls "$HERMES_HOME/.pending-skill-backup-*" for moved payloads from prior sessions
   • find "$HERMES_HOME" -path '*/.pending-skill-backup-*/*.json' -maxdepth 4
4. Repeat until resolved.

Duplicate-create collisions (important)

When the queue contains multiple create actions for the same skill name:

• Inspect each payload/diff first.
• Keep only the desired design;
• reject/resolve conflicting duplicates before approvals continue, so you avoid non-deterministic final content.

Queue-state mismatch warning

If pending/skills has 0 files but there are files in backup directories:

• Treat this as a relocated queue, not as empty scope.
• Decide explicit policy:
  1. keep in backup for deferred review,
  2. resume by moving back to pending/skills, or
  3. reject/review and archive intentionally.
• Always report to user which IDs remain and why.

Safe handling patterns

• Temporarily disable only if needed for immediate batch ops.
• Backup queue files first.
• Remove/re-hydrate only after explicit confirmation.
• Report what was removed and where backup is stored.

Use-case B — user wants to keep gate on but stop backlog from growing

• Keep ...write_approval=true.
• Process one-by-one with /skills diff and approve/reject.
• This preserves audit trace.

Verification checklist

• Intended approval flags are in desired state.
• Pending queue directory is at expected final state.
• If a queue was bulk-cleared, backup directory exists and path is recorded.
• For messaging-session IDs that fail to locate JSON, check backup directories (for example .pending-skill-backup-*) before deciding the request is stale.
• User was informed whether items were approved/rejected/archived.
• Conflicting queued actions (especially duplicate create) were resolved intentionally before continuing.

Troubleshooting references

• references/pending-skill-gate-operations.md
• references/pending-skill-queue-tips.md

Pitfalls

• Don’t clear pending writes from assumptions; ask for confirmation unless the user already explicitly requested bulk removal.
• Gate toggles affect future writes, not historical state.
• If only skills.write_approval is toggled, memory writes may still remain gated by memory.write_approval.
• Keep scope clear: this skill is about approvals and pending write hygiene, not live server execution or broader Git/DB mutation.

Related reference

• references/pending-skill-gate-operations.md