Working Tree Governor

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:

1. dirty-tree summary
2. bucket classification
3. recommended include-now list
4. recommended exclude/preserve list
5. staged verification
6. 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