Working-tree-governor

Use when a repo is dirty and you need to commit safely without dragging runtime noise, logs, cache, state files, or generated artifacts into history.

This skill exists for the common Hermes failure mode where git status becomes unreadable because code, tests, logs, runtime state, forensics, cached binaries, and generated outputs are all mixed together.

The goal is not cleanliness theater. The goal is to preserve signal and produce small, reviewable commits.

When to trigger

Load this skill when any of these are true:

the user asks to commit while the repo is dirty
git status --short shows mixed code plus logs/state/cache/output noise
more than ~25 changed or untracked files
more than ~8 source or test files are modified
the next action is risky: restart, deploy, cutover, refactor, or live-sensitive change
runtime-critical files are dirty in a tree already full of noise

Treat these as high-risk triggers:

more than 100 changed/untracked files
live runtime files dirty and HEAD stale
planned restart/deploy while mixed dirt is still present
tracked state/log/output files continuously mutating and obscuring code changes

Core principle

Never use git add . in this situation. Never default to stash for this situation. Default to selective staging. If confidence is low, ask the operator before commit.

Discovery workflow

Start read-only.

Run:

git status --short
git diff --name-only
git diff --cached --name-only
git rev-parse HEAD
git log -1 --format='%H %ad %s' --date=iso

Optional when useful:

git diff --stat
git diff -- <path>

Then bucket every changed path.

Buckets

Bucket A — core code and tests

Examples:

src/**/*.py
tests/**/*.py
service scripts
core config templates
startup scripts
bridge/runtime code

Default action: include_now

Bucket B — docs and plans

Examples:

docs/**
selected *.md
intentionally authored design notes

Default action: usually needs_operator_decision unless clearly part of the requested commit

Bucket C — runtime state

Examples:

shared/risk/*.json
shared/reports/strategy_pnl.json
shared/risk/open_positions.json
hermes_state.json

Default action: preserve_but_exclude

Bucket D — generated outputs and artifacts

Examples:

results/**
backtest outputs
parquet / duckdb
generated summaries

Default action: preserve_but_exclude

Bucket E — logs

Examples:

*.log
*.jsonl
streamer.log*
monitor logs
cron logs

Default action: ignore_for_now or preserve_but_exclude

Bucket F — caches and binaries

Examples:

__pycache__/
*.pyc
.metaapi/*.bin

Default action: ignore_for_now

Bucket G — forensics and snapshots

Examples:

shared/forensics/**
*.bak-*
incident snapshots

Default action: preserve_but_exclude

Bucket H — unknown

Anything not confidently classifiable.

Default action: needs_operator_decision

Heuristics

High-confidence exclude

Exclude by default when path matches patterns like:

**/__pycache__/**
**/*.pyc
shared/hermes-acp/*.log
shared/hermes-acp/*_log.jsonl
shared/reports/*.jsonl
shared/risk/*.json
results/*.json
memory/**/*.md
src/.metaapi/*.bin
shared/forensics/**
*.bak
rotated logs / archives

High-confidence include

Include by default when path matches patterns like:

src/**/*.py
tests/**/*.py
skill files
fixtures under tests/fixtures/**

Important exception

Do not exclude real code just because it lives beside noisy runtime files. For example, shared/hermes-acp/*.py may be real source code and must be inspected, not auto-excluded.

Commit-governor flow

1. Summarize the tree

Report:

total dirty file count
bucket counts
runtime-critical files dirty
likely risk level: low / moderate / high / critical

2. Infer requested commit scope

Use the user’s requested commit intent to infer the include set. Examples:

execution-truth work → shared/hermes-acp/execution_truth*.py, matching tests, matching fixtures
streamer fix → exact src/hermes/streamer.py plus targeted tests

Do not include unrelated source changes automatically just because they are code.

3. Stage selectively

Stage only the inferred relevant files. Never stage all dirty files.

Use:

git add <explicit paths>

4. Verify staged scope before commit

Always run:

git diff --cached --name-only
git diff --cached --stat
git status --short

Verify explicitly:

no logs staged
no runtime state staged
no cache/binaries staged
no unrelated subsystem staged
staged paths match the requested commit intent

If suspicious files appear, unstage them or stop.

5. Conventional commit message

Prefer these prefixes:

feat:
fix:
refactor:
test:
docs:
chore:

If the user’s message lacks a valid prefix, suggest a corrected version before commit.

6. Operator approval gate

Do not auto-commit if any of these are true:

ambiguous file group present
multiple unrelated subsystems staged
runtime-sensitive file included unexpectedly
a Bucket H file would be committed
the staged set is larger than expected for the request

In those cases, ask a short scope question and wait.

7. Commit and post-commit verification

After commit, run:

git show --stat --oneline HEAD
git diff --cached --name-only
git status --short

Report:

commit hash
files included
notable dirty files intentionally left out
whether runtime noise remains uncommitted

Risk policy

Low risk

Small tree, mostly one category, no runtime-critical dirt. Proceed normally but still summarize buckets.

Moderate risk

Mixed categories, some core code dirty, risky action coming. Recommend selective baseline before continuing.

High risk

Large mixed tree, core runtime dirty, noise obscures real work. Switch to hygiene-first mode before more feature work.

Critical risk

Huge mixed tree plus stale HEAD plus runtime-critical dirt plus pending restart/deploy. Strongly recommend immediate selective preservation before any risky next step.

Edge cases

Real code in noisy directories

Example:

shared/hermes-acp/execution_truth_slice.py This is real code. Inspect it. Do not auto-exclude it because of the directory.

Fixtures that look like logs

Example:

tests/fixtures/execution_truth_streamer_2026_04_10_sample.log This is a committed test fixture, not runtime noise.

Runtime-sensitive source files

Example:

src/hermes/streamer.py These require stricter operator confirmation before commit.

Already-staged junk

If bad paths are already staged, verify and unstage before commit instead of proceeding.

Fail-safe rule

If confidence is not high, do not commit. Show:

candidate include list
suspicious/ambiguous list
recommended commit message
one short operator question

The fail-safe is simple: when uncertain, ask before commit.

Output style

When using this skill, report in this order:

dirty-tree summary
bucket classification
recommended include-now list
recommended exclude/preserve list
staged verification
commit recommendation or operator question

What success looks like

The skill is successful when Hermes consistently does this:

detects dirty tree risk early
separates runtime noise from real changes
stages only the requested source/test/config files
verifies staged scope before commit
uses conventional commit messages
avoids dragging runtime junk into history
asks the operator whenever scope is not obvious