Skill: huangrichao2020/hermes-agent-health-check (version 1.1.2)

--- name: hermes-agent-health-check description: Audit a NousResearch/hermes-agent checkout or fork for Hermes-specific runtime-contract drift, command-surface splits, memory/skill/gateway health, and agent architecture risks. Uses the hermescheck Python library (hermescheck.report.v1) for structured reports with severity-ranked findings and code-first fix plans. origin: https://github.com/huangrichao2020/hermescheck --- # Hermes Agent Health Check Audit the architecture and health of a Hermes Agent checkout, fork, or deployment support repo. Hermes Agent has a connected runtime: agent loop, command registry, CLI, TUI, gateway, skills, memory, cron, tools, plugins, and terminal environments. `hermescheck` helps keep those surfaces aligned. ## When to Use - You are preparing a Hermes Agent PR and want a repeatable architecture review - A Hermes fork works in CLI but not gateway, TUI, skills, cron, or plugins - A new slash command risks drifting across surfaces - A tool or environment change needs clearer capability boundaries - Memory, session search, or skill behavior regressed after a refactor - Startup paths or background jobs became hard to reason about ## Quick Start ```bash pip install hermescheck hermescheck /path/to/hermes-agent ``` Produces `audit_results.json` and `audit_report.md`. ## The 12-Layer Stack | # | Layer | What Goes Wrong | |---|-------|----------------| | 1 | System prompt | Conflicting instructions, instruction bloat | | 2 | Session history | Stale context from previous turns | | 3 | Long-term memory | Pollution across sessions | | 4 | Distillation | Compressed artifacts re-entering as pseudo-facts | | 5 | Active recall | Redundant re-summary layers wasting context | | 6 | Tool selection | Wrong tool routing, model skips required tools | | 7 | Tool execution | Hallucinated execution — claims to call but doesn't | | 8 | Tool interpretation | Misread or ignored tool output | | 9 | Answer shaping | Format corruption in final response | | 10 | Platform rendering | UI/API/CLI mutates valid answers | | 11 | Hidden repair loops | Silent fallback/retry agents running second LLM pass | | 12 | Persistence | Expired state or cached artifacts reused as live evidence | ## Audit Scanners | # | Scanner | Severity | What It Catches | |---|---------|----------|-----------------| | 1 | Hardcoded Secrets | critical | API keys, tokens, credentials in source code | | 2 | Tool Enforcement Gap | high | "Must use tool X" in prompt but no code validation | | 3 | Hidden LLM Calls | high | Secret second-pass LLM calls in fallback/repair loops | | 4 | Unrestricted Code Execution | critical | exec(), eval(), subprocess(shell=True) without sandbox | | 5 | Static Bug Inference | high | Code-level bug patterns inferred without runtime execution | | 6 | Token Usage Budget | high | Large default context windows, full-history prompts, missing thrift controls | | 7 | Memory Lifecycle Governance | medium | Memory without types, lifecycle, retrieval budgets, decay, or evidence pointers | | 8 | RAG Pipeline Governance | medium | Retrieval without chunk, top-k, rerank, ingestion, or context budget controls | | 9 | Self-Evolution Capability | high | Learning loops without external signals, source reading, constraint fit, safe landing, or verification | | 10 | Loop Safety Budget | high | Tool/agent loops without max-iteration, retry budget, stuck-job, or duplicate-call controls | | 11 | Plugin / Remote Tool Boundary | high | Executable plugins and MCP/OpenAPI tools without sandbox, schema, allowlist, or approval boundaries | | 12 | Output Pipeline Mutation | medium | Response transformation corrupting correct answers | | 13 | Missing Observability | medium | No tracing, logging, cost tracking, or audit trail | ## Severity Model | Level | Meaning | |-------|---------| | `critical` | Agent can confidently produce wrong operational behavior | | `high` | Agent frequently degrades correctness or stability | | `medium` | Correctness usually survives but output is fragile or wasteful | | `low` | Mostly cosmetic or maintainability issues | ## Fix Strategy Default fix order (code-first, not prompt-first): 1. **Code-gate tool requirements** — enforce in code, not just prompt text 2. **Remove or narrow hidden repair agents** — make fallback explicit with contracts 3. **Reduce context duplication** — same info through prompt + history + memory + distillation 4. **Tighten memory admission** — user corrections > agent assertions 5. **Tighten distillation triggers** — don't compress what shouldn't be compressed 6. **Reduce rendering mutation** — pass-through, don't transform 7. **Convert to typed JSON envelopes** — structured internal flow, not freeform prose ## Report Schema Reports follow a formal JSON Schema (see `references/report-schema.json`) with: - `overall_health`: critical_risk | high_risk | medium_risk | low_risk - `findings`: array of severity-ranked issues with evidence refs - `maturity_score`: positive signal ledger, penalty ledger, score formula, and expected recovery directions - `ordered_fix_plan`: prioritized fix steps with rationale ## Anti-Patterns to Avoid - ❌ Saying "the model is weak" without falsifying the wrapper first - ❌ Saying "memory is bad" without showing the contamination path - ❌ Letting a clean current state erase a dirty historical incident - ❌ Treating markdown prose as a trustworthy internal protocol - ❌ Accepting "must use tool" in prompt text when code never enforces it ## Related - GitHub: https://github.com/huangrichao2020/hermescheck

path: README.md
content: <p align="center">
  <a href="#quick-start">
    <img src="./assets/readme/hermescheck-readme-banner.png" alt="HermesCheck - Hermes Agent-focused architecture and runtime health checks" width="100%">
  </a>
</p>

# hermescheck

Hermes Agent-focused architecture and runtime health checks.

`hermescheck` is a community companion tool for
[NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent). It
scans a Hermes Agent checkout or fork and produces a structured report about
runtime contracts, command-surface drift, memory and skill architecture,
gateway readiness, scheduled jobs, tool boundaries, observability, and common
agent-system failure modes.

This project is not an official Nous Research project. It is built for the
Hermes Agent community and derived from the general-purpose
[`agchk`](https://github.com/huangrichao2020/agchk) scanner, then narrowed for
Hermes-specific review workflows.

Long-term commitment: `hermescheck` is designed to stay in deep alignment with
Hermes Agent. It will be maintained release by release, updating checks,
documentation, and regression coverage so every Hermes release can ship with a
clear community health-check path for forks and deployments. It will also help
Hermes Agent reach, support, and earn practical adoption among Chinese
developer communities.

<p align="center">
  <a href="https://github.com/huangrichao2020/hermescheck/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/huangrichao2020/hermescheck/ci.yml?branch=main&label=CI&style=flat-square"></a>
  <a href="https://pypi.org/project/hermescheck/"><img alt="PyPI" src="https://img.shields.io/pypi/v/hermescheck?style=flat-square"></a>
  <a href="./LICENSE"><img alt="License" src="https://img.shields.io/github/license/huangrichao2020/hermescheck?style=flat-square"></a>
  <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
  <a href="#contributors"><img alt="All Contributors" src="https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square"></a>
  <!-- ALL-CONTRIBUTORS-BADGE:END -->
</p>

## Why It Exists

Hermes Agent is more than a chat CLI. It is a persistent agent runtime with a
conversation loop, tool registry, skills, memory, session search, messaging
gateway, scheduled automations, terminal backends, plugins, and training
surfaces. That power is exactly why Hermes forks and deployments can drift in
ways ordinary linters do not catch.

`hermescheck` asks Hermes-shaped questions:

- Does this checkout still contain the core Hermes runtime surfaces?
- Are slash commands derived from the central registry instead of diverging per surface?
- Do CLI, TUI, gateway, skills, cron, and SessionDB still line up?
- Can interrupted runs resume from transcript plus durable environment state?
- Are tool/syscall boundaries explicit enough for high-agency operation?
- Is memory becoming a durable subsystem rather than context stuffing?
- Are startup paths, plugins, and background jobs becoming hard to reason about?
- Can findings be exported to Markdown, JSON, and SARIF for repeatable review?

## Full-Score Agent Architecture

In `hermescheck` terms, a full-score Hermes-aligned agent is not just a model
with tools. It is a stateful agent operating system: every user-facing surface
shares one command contract, every tool crosses an explicit capability boundary,
memory is paged and recoverable, and each release can be checked through a
repeatable evidence pipeline.

<p align="center">
  <img src="./assets/readme/hermescheck-full-score-agent-architecture.png" alt="HermesCheck full-score agent architecture: command contract, stateful recovery, memory and skill OS, tool syscall boundary, scheduler, and release guardrail" width="100%">
</p>

The architecture should provide these capabilities:

- one canonical command surface across CLI, TUI, gateway, help, autocomplete, and menus
- stateful recovery from transcript plus real environment state
- external LLM CLI workers through Task JSON, natural-language prompt handoff, stdout/stderr/exit-code capture, and process controls
- explicit tool/syscall capabilities before high-agency execution
- memory that supports facts, skills, semantic anchors, paging, and page-fault recovery
- scheduler controls for long-running jobs, cron, gateway events, and user-visible tasks
- observability that turns every release check into reusable evidence

## Quick Start

```bash
pip install hermescheck
```

Scan a Hermes Agent checkout:

```bash
git clone https://github.com/NousResearch/hermes-agent.git
hermescheck ./hermes-agent
```

Write machine-readable, human-readable, and GitHub code-scanning outputs:

```bash
hermescheck ./hermes-agent \
  --profile personal \
  -o audit_results.json \
  -r audit_report.md \
  --sarif hermescheck.sarif.json
```

Run as a module from a local clone:

```bash
python -m hermescheck ./path/to/hermes-agent --quiet
```

## Example Report Snapshot

`hermescheck` is designed to produce a first-screen summary that maintainers
can understand immediately, then drill into through Markdown, JSON, or SARIF.

Chinese:

```text
结果摘要:
- Overall Health: unstable
- Architecture Era: 内燃气时代 (75/100)
- 总问题数: 108
- HIGH: 5
- MEDIUM: 88
- LOW: 15

最主要的 5 个高优先级问题:
1. Internal orchestration sprawl detected
   - 编排/规划/路由/恢复/调度层过多，主循环职责不够单一
2. Memory freshness / generation confusion detected
   - 记忆面过多，存在“哪个是最新 authoritative memory”的歧义
3. Role-play handoff orchestration detected
   - 角色化/部门化 handoff 偏多，容易造成上下文漂移
4. Startup surface sprawl detected
   - 启动入口和 wrapper 较多，启动链路不够收敛
5. Runtime surface sprawl detected
   - runtime 面太多 (agent_stack / ops / queue / storage / ui / web_api)，理解和维护成本高
```

English:

```text
Report summary:
- Overall Health: unstable
- Architecture Era: Combustion Age (75/100)
- Total Issues: 108
- HIGH: 5
- MEDIUM: 88
- LOW: 15

Top 5 high-priority issues:
1. Internal orchestration sprawl detected
   - Too many planning, routing, recovery, and scheduling layers; main-loop ownership is not clear enough.
2. Memory freshness / generation confusion detected
   - Too many memory surfaces; unclear which one is the latest authoritative memory.
3. Role-play handoff orchestration detected
   - Too many department-style handoffs; context can drift between roles.
4. Startup surface sprawl detected
   - Too many entrypoints and wrappers; the startup chain is not convergent enough.
5. Runtime surface sprawl detected
   - Runtime spans too many surfaces (agent_stack / ops / queue / storage / ui / web_api), raising comprehension and maintenance cost.
```

## Hermes-Specific Checks

### Runtime Contract

`hermescheck` first detects whether the target looks like a Hermes Agent
checkout. If it does, it verifies the presence of core runtime surfaces:

| Surface | Expected path |
| --- | --- |
| Agent loop | `run_agent.py` |
| Tool orchestration | `model_tools.py`, `toolsets.py`, `tools/registry.py` |
| CLI | `cli.py`, `hermes_cli/commands.py` |
| Session memory | `hermes_state.py` |
| Profile-aware paths and logs | `hermes_constants.py`, `hermes_logging.py` |
| Skills | `skills/`, `optional-skills/`, `agent/skill_commands.py` |
| Gateway | `gateway/run.py`, `gateway/platforms/` |
| Scheduling | `cron/scheduler.py` |
| Execution environments | `tools/environments/` |
| Plugins and tests | `plugins/`, `tests/` |

If a fork or packaging step drops one of these surfaces, the report makes the
drift visible before the missing piece becomes a runtime surprise.

### Slash Command Contract

Hermes shares slash commands across the classic CLI, TUI, messaging gateway,
help text, autocomplete, and platform menus. `hermescheck` looks for the shared
`COMMAND_REGISTRY`, `GATEWAY_KNOWN_COMMANDS`, `resolve_command`, and
`gateway_help_lines` helpers so command changes do not silently split by
surface.

### General Agent Architecture Signals

The Hermes-specific scanner runs alongside inherited architecture checks:

- internal orchestration sprawl
- completion-closure gaps
- static bug inference from code patterns
- token usage budget risks, including large default context windows and full-history prompt assembly
- memory freshness confusion
- memory lifecycle governance and CJK-safe retrieval paths
- RAG retrieval governance and context-budget controls
- self-evolution capability: external signals, source reading, pattern extraction, constraint adaptation, safe landing, and verification closure
- impression/pointer memory gaps
- role-play handoff chains
- agent-OS architecture gaps, including Stateful Agent recovery
- loop-safety budgets, daemon lifecycle controls, capability policies, plugin sandboxing, remote tool boundaries, and pipeline middleware integrity
- LLM CLI worker contract gaps for Qwen/Codex/Claude-style process delegation, including raw-JSON stdin handoff
- duplicated skills and SOPs
- startup and runtime surface sprawl
- hidden LLM calls
- tool-enforcement gaps
- output pipeline mutation
- code execution risks
- missing observability
- excessive agency controls in enterprise mode

## Profiles

`hermescheck` keeps two practical profiles:

| Profile | Intended use | Behavior |
| --- | --- | --- |
| `personal` | Local Hermes forks, experiments, solo operator setups | Prioritizes internal drag, closure, memory shape, and runtime clarity |
| `enterprise` | Team-owned or production Hermes deployments | Keeps stricter checks for secrets, code execution, approvals, and observability |

Examples:

```bash
hermescheck ./hermes-agent --profile personal
hermescheck ./hermes-agent --profile enterprise --fail-on high
```

## Report Shape

Every scan produces:

- `schema_version`: stable JSON schema identifier
- `scan_metadata`: timestamp, duration, scanner count, profile
- `executive_verdict`: health, primary failure mode, urgent fix
- `scope`: entry points, channels, model stack, audited layers
- `maturity_score`: architecture-era score, formula, positive signal ledger, penalty ledger, score caps, and share line
- `evidence_pack`: compact evidence references
- `findings`: severity-ranked issues with fixes
- `ordered_fix_plan`: practical next steps

Generate Markdown from a previous JSON report:

```bash
hermescheck report audit_results.json -o audit_report.md
```

Validate a report:

```bash
hermescheck validate audit_results.json
```

## Use With Hermes PRs

For contributors preparing a Hermes Agent PR:

```bash
hermescheck ./hermes-agent --profile personal -o audit_results.json -r audit_report.md
```

Then use the report to answer:

- Did the change touch the agent loop, command registry, gateway, skills, cron, or SessionDB?
- Did any interface work in CLI but not gateway, or vice versa?
- Did a new tool path get a capability boundary, test, and observable failure mode?
- Did a memory or skill change preserve recall, search, and closure behavior?
- Can an interrupted run verify environment state before repeating tool work?
- Can the PR description cite a concrete validation command?

The goal is not to block Hermes experimentation. The goal is to make drift
visible early so community tools, forks, and upstream contributions stay easy to
review.

## Development

```bash
git clone https://github.com/huangrichao2020/hermescheck.git
cd hermescheck
python -m pip install -e ".[dev]"
pytest -q
ruff check hermescheck tests
ruff format --check hermescheck tests
```

The CI pipeline runs lint, repository hygiene checks, tests across supported
Python versions, a self-scan, and package build validation.

## Contributing

Useful contributions include:

- sharper Hermes-specific contract checks
- false-positive reductions from real Hermes forks
- report examples from public-safe scans
- SARIF or CI integration improvements
- docs that make Hermes review workflows easier to repeat

See:

- [Contribution examples](./docs/examples/contribution-examples.md)
- [Release process](./docs/governance/release-process.md)
- [Agent prompt](./docs/AGENT_PROMPT.md)

## Contributors

Thanks goes to these people for code, docs, ideas, tests, reviews, examples, and
real-world self-scan lessons.

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
  <tbody>
    <tr>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/huangrichao2020"><img src="https://avatars.githubusercontent.com/u/72842645?v=4?s=100" width="100px;" alt="Huang richao"/><br /><sub><b>Huang richao</b></sub></a><br /><a href="https://github.com/huangrichao2020/hermescheck/commits?author=huangrichao2020" title="Code">Code</a> <a href="https://github.com/huangrichao2020/hermescheck/commits?author=huangrichao2020" title="Documentation">Docs</a> <a href="#ideas-huangrichao2020" title="Ideas, Planning, & Feedback">Ideas</a> <a href="#maintenance-huangrichao2020" title="Maintenance">Maintenance</a></td>
    </tr>
  </tbody>
</table>

<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->

<!-- ALL-CONTRIBUTORS-LIST:END -->

## License

MIT. See [LICENSE](./LICENSE).


path: references/code-patterns.md
content: # Code-Level Anti-Patterns

Concrete grep-searchable patterns to find agent wrapper failures in source code.

These patterns are auto-generated from the [hermescheck](https://github.com/huangrichao2020/hermescheck) Python scanners.
Each section lists the regex patterns used by that scanner.

## Usage

```bash
pip install hermescheck
hermescheck /path/to/your/agent/project
```

Or run individual grep scans manually:

## Bug Inference

**Scanner file**: `hermescheck/scanners/bug_inference.py`

**Default severity**: `high`

**Regex patterns**:

- `^(?:fix|patch|repair|hotfix|tmp|temp)\d*\.py$`
- `\b(?:content\.replace|\.replace\s*\(|write_text\s*\(|open\s*\([^)]*['\`
- `renameSync|copyFileSync)\b`
- `['\`
- `\bimport\s*\(\s*([^)]{1,180})\)`
- `\b(?:pathToFileURL|fileURLToPath|import\.meta\.resolve)\b`
- `(?:path|file|filename|entry|script|bundle|resolved|absolute|join|resolve)`
- `\bsetTimeout\s*\(`
- `\bsetTimeout\s*\(.*,\s*[0-9_]+(?:\s*[),;])`
- `(?:delay|timeout|interval|ttl|duration|ms|seconds|minutes|nextRun|wait)`
- `\b(?:Math\.min|Math\.max|clamp|MAX_TIMEOUT|MAX_DELAY|setTimeout cap|timerDelay|safeDelay)\b`
- `(?:heartbeat|cron|schedul|deadline|until|nextRun|expire|expiry|refreshAt|-\s*now|hours?|days?)`
- `(?:debounce|animation|transition|tooltip|scroll|render|search)`
- `: `
- `[A-Z0-9_]+`
- `(?:PATH|FILE|ENTRY|SCRIPT|BUNDLE)`
- `: `
- `: `

## Capability Policy

**Scanner file**: `hermescheck/scanners/capability_policy.py`

**Default severity**: `high`

**Regex patterns**:

- `\b(?:agent|assistant|tool_call|tool use|function_call|planner|scheduler|autonomous|daemon|`
- `always[-_ ]?on|human[-_ ]?in[-_ ]?the[-_ ]?loop)\b`
- `(?:subprocess\.(?:run|Popen)|os\.system|shell\s*=\s*True|\bexec\s*\(|\beval\s*\(|`
- `write_text\(|write_bytes\(|\.unlink\(|os\.remove\(|shutil\.rmtree\(|`
- `requests\.(?:get|post|put|delete)|httpx\.(?:get|post|put|delete)|\bfetch\s*\(|axios\.`
- `|git\s+push|npm\s+publish|pip\s+install|docker\s+|kubectl\s+|browser_control|playwright|selenium)`
- `\b(?:blocklist|denylist|blacklist|forbidden|blocked_commands|dangerous_commands)\b`
- `\b(?:allowlist|whitelist|auto[-_ ]?approved|safe_commands|allowed_commands|allowed_paths|permitted_paths)\b`
- `\b(?:needs[_ -]?approval|require[_ -]?approval|request[_ -]?approval|confirm|consent|human[_ -]?approval|`
- `ask[_ -]?to[_ -]?continue|manual_review)\b`
- `\b(?:read[_ -]?scope|write[_ -]?scope|path[_ -]?scope|temp[_ -]?scope|workspace[_ -]?scope|`
- `permission matrix|capability table|capabilities|sandbox)\b`
- `\b(?:def\s+[_a-zA-Z0-9]*(?:invoke|dispatch|execute|run)[_a-zA-Z0-9]*(?:tool|function|command)|`
- `async\s+def\s+[_a-zA-Z0-9]*(?:invoke|dispatch|execute|run)[_a-zA-Z0-9]*(?:tool|function|command)|`
- `(?:invoke|dispatch|execute|run)[_a-zA-Z0-9]*(?:tool|function|command)\s*\(|`
- `tool_call\s*\(|function_call\s*\(|subprocess\.(?:run|Popen)|os\.system\s*\()\b`
- `\b(?:check[_ -]?permission|PermissionEngine|permission_engine|is_allowed|is_blocked|deny|denied|`
- `require[_ -]?approval|needs[_ -]?approval|allowed_commands|blocked_commands|blocklist|allowlist|`
- `capability[_ -]?check|policy\.check)\b`
- `: `
- `: `

## Code Execution

**Scanner file**: `hermescheck/scanners/code_execution.py`

**Default severity**: `medium`

**Regex patterns**:

- `(?<!\.)\bexec\s*\(`
- `(?<!\.)\beval\s*\(`
- `(?<!\.)\bcompile\s*\(`
- `\bos\.system\s*\(`
- `\bnew\s+Function\s*\(`
- `subprocess\..*shell\s*=\s*True`
- `(?:sandbox|docker|container|seccomp|chroot|\bvm\b|`
- `subprocess.*timeout|resource\.setrlimit|jail|`
- `nsjail|firejail|gvisor|kata)`
- `: `

## Completion Closure

**Scanner file**: `hermescheck/scanners/completion_closure.py`

**Default severity**: `medium`

**Regex patterns**:

- `\b(?:create file|write file|save file|mkdir|touch|open\(.*[\`
- `\b(?:update index|index update|registry|manifest|catalog|toc|table of contents)\b|(?:更新索引|索引更新|目录|清单|注册表)`
- `\b(?:impression card|memory card|summary card|cue card|concept card)\b|(?:印象卡片|记忆卡片|概念卡片)`
- `\b(?:anchor mapping|semantic anchor|topic_anchor|anchor map|concept anchor)\b|(?:锚点映射|语义锚点|主题锚点)`
- `: re.compile(
        r`
- `\b(?:acceptance|acceptance criteria|done criteria|verify|validation|self[-_ ]?test|reusable|can find|next time)\b|(?:验收|验收标准|完成标准|验证|可复用|下次.*找到)`
- `\b(?:done|completed|task complete|finished|success)\b|(?:完成|已完成|任务完成|成功)`
- `, `
- `: `
- `: `

## Daemon Lifecycle

**Scanner file**: `hermescheck/scanners/daemon_lifecycle.py`

**Default severity**: `medium`

**Regex patterns**:

- `\b(?:daemon|gateway|watchdog|run_forever|always[-_ ]?on|service|systemd|launchagent|pm2|supervisor|`
- `detached|pid[_ -]?file|background worker|heartbeat)\b`
- `\b(?:restart|reload|replace|respawn|crash|backoff|SIGTERM|SIGKILL|kill\s+-|terminate)\b`
- `\b(?:active[_ -]?(?:agents|runs|jobs|tasks|sessions)|running[_ -]?(?:jobs|tasks|sessions)|`
- `job[_ -]?queue|task[_ -]?queue|inflight|in[-_ ]?flight|pending[_ -]?jobs|session[_ -]?state)\b`
- `\b(?:drain|graceful[_ -]?(?:shutdown|restart|stop)|quiesce|wait[_ -]?for[_ -]?(?:idle|jobs)|`
- `stop[_ -]?accepting|pre[_ -]?restart|restart[_ -]?barrier|safe[_ -]?restart)\b`
- `\b(?:checkpoint|resume|recover|replay|journal|side[-_ ]?effect[_ -]?log|operation[_ -]?log|`
- `idempotent|session[_ -]?replay|state[_ -]?restore|crash[_ -]?recovery)\b`
- `\b(?:connected|health[_ -]?check|status|ready|readiness|websocket|gateway[_ -]?state|post[_ -]?restart)\b`
- `: `

## Excessive Agency

**Scanner file**: `hermescheck/scanners/excessive_agency.py`

**Default severity**: `medium`

**Regex patterns**:

- `(?:subprocess\.run|subprocess\.Popen|os\.system|shell\s*=\s*True|`
- `\bexec\s*\(|\beval\s*\(|browser_control|playwright|selenium|`
- `requests\.(?:get|post|put|delete)|httpx\.(?:get|post|put|delete)|`
- `\bfetch\s*\(|axios\.(?:get|post|put|delete)|write_text\(|write_bytes\(|`
- `\.unlink\(|os\.remove\(|shutil\.rmtree\()`
- `(?:approve|approval|confirm|consent|require_approval|request_approval|`
- `user_confirm|human_in_the_loop|manual_review)`
- `(?:sandbox|docker|container|isolat|gvisor|nsjail|seccomp|read_only|`
- `readonly|resource\.setrlimit|timeout\s*=|network_disabled)`
- `(?:allowlist|whitelist|ALLOWED_|SAFE_COMMANDS|allowed_commands|`
- `allowed_paths|permitted_commands|permitted_paths)`
- `: `

## Hermes Contract

**Scanner file**: `hermescheck/scanners/hermes_contract.py`

**Default severity**: `high`

**Regex patterns**:

- `,
    `
- `: `
- `: `

## Hidden Llm

**Scanner file**: `hermescheck/scanners/hidden_llm.py`

**Default severity**: `high`

**Regex patterns**:

- `(?:chat(?:\.completions)?\.create|messages\.create|completions\.create|llm\.invoke|`
- `openai\.chat|anthropic\.messages|vertexai\.predict|`
- `bedrock.*invoke|model\.generate|completion\.create)\s*\(`
- `(?:fallback|repair|second.*pass|re-prompt|retry.*llm|judge.*llm|reflect.*llm)`
- `(?:agent.*loop|main.*loop|orchestrat|chain.*run|agent.*run|`
- `agent_executor|react.*loop|tool.*loop|cycle.*run)`
- `(?:provider|adapter|client_factory|model_backend|llm_gateway|client|gateway)`
- `(?:class\s+\w*Provider|def\s+\w*provider)`
- `: `
- `: `

## Impression Memory

**Scanner file**: `hermescheck/scanners/impression_memory.py`

**Default severity**: `medium`

**Regex patterns**:

- `\b(?:fact|facts|preference|preferences|profile|user profile|entity|entities|attribute|metadata)\b|(?:事实|偏好|画像|实体)`
- `\b(?:skill|skills|procedure|procedural|workflow|runbook|sop|playbook|capability)\b|(?:技能|流程|经验|操作手册)`
- `\b(?:session|conversation|dialogue|transcript|history|episode|event|memory chunk|chunk)\b|(?:会话|对话|片段|事件)`
- `\b(?:impression|impressions|associative|association|cue|gist|landmark|mental map|concept map|`
- `semantic hint|route hint|memory impression|impression chunk)\b|(?:印象|联想|概念路标|路标|线索|语义提示|大概知道)`
- `\b(?:pointer_ref|pointer_type|vector_id|file_path|skill_id|semantic_hash|semantic anchor|`
- `topic_anchor|page table|page entry|page fault|swap in|swap-in|activation_level|in_mind|subconscious|`
- `forgotten|retrieval pointer)\b|(?:语义锚点|页表|页表项|缺页|换入|激活层级|潜意识|遗忘)`
- `(?:impression|memory|page[_ -]?table|page[_ -]?fault|semantic[_ -]?hash|topic[_ -]?anchor|`
- `pointer[_ -]?(?:ref|type)|vector_id|activation_level|印象|记忆|页表|缺页|语义锚点)`
- `: [],
    }
    files = [target] if target.is_file() else sorted(target.rglob(`
- `].append(path_ref)

        try:
            lines = fp.read_text(encoding=`
- `].append(ref)
    return refs


def _evidence(refs: dict[str, list[str]]) -> list[str]:
    evidence_refs: list[str] = []
    seen: set[str] = set()
    for key in (`
- `):
        for ref in refs[key][:4]:
            if ref not in seen:
                evidence_refs.append(ref)
                seen.add(ref)
    return evidence_refs[:10]


def scan_impression_memory(target: Path) -> List[Dict[str, Any]]:
    refs = _collect_refs(target)
    has_memory_system = len(refs[`
- `]) >= 2

    if not has_memory_system or not has_skill_system:
        return []

    findings: List[Dict[str, Any]] = []
    if not has_impressions:
        findings.append(
            {
                `
- `: `
- `: `

## Internal Orchestration

**Scanner file**: `hermescheck/scanners/internal_orchestration.py`

**Default severity**: `medium`

**Regex patterns**:

- `(?:^|[^a-z])plan(?:ner|ning|_task|_step)?`
- `(?:route|router|dispatch|selector|handoff)`
- `(?:subagent|worker|delegate|swarm|team|multi[_ -]?agent)`
- `(?:schedule|scheduler|cron|heartbeat|timer)`
- `(?:retry|fallback|repair|reflect|judge|critic)`
- `: `

## Loop Safety

**Scanner file**: `hermescheck/scanners/loop_safety.py`

**Default severity**: `high`

**Regex patterns**:

- `\b(?:agent[_ -]?loop|main[_ -]?loop|react[_ -]?loop|tool[_ -]?loop|while\s+True|for\s*\(\s*;;|`
- `while\s*\(\s*true\s*\)|loop_detector|run_forever|always[-_ ]?on|daemon)\b`
- `\b(?:tool_call|toolCall|tool_use|function_call|execute[_ -]?shell|shell command|subprocess|`
- `delegate_task|retry|fallback|provider fallback)\b`
- `\b(?:cron|scheduler|heartbeat|interval|setInterval|schedule\.|task[_ -]?queue|job[_ -]?queue|`
- `worker[_ -]?queue|workerQueue|background[_ -]?task|backgroundTask|daemon|watchdog)\b`
- `\b(?:max[_ -]?(?:steps|turns|iterations|loops|retries)|iteration[_ -]?limit|tool[_ -]?call[_ -]?limit|`
- `loop[_ -]?detector|repetition[_ -]?detector|same[_ -]?args|args[_ -]?hash|dedupe|circuit[_ -]?breaker|`
- `timeout|deadline|retry[_ -]?budget|backoff|ask[_ -]?to[_ -]?continue|confirm[_ -]?continue|`
- `cancel|cancellation|abort|stop[_ -]?signal)\b`
- `\b(?:def\s+[_a-zA-Z0-9]*(?:invoke|dispatch|execute|run)[_a-zA-Z0-9]*(?:tool|function|command)|`
- `async\s+def\s+[_a-zA-Z0-9]*(?:invoke|dispatch|execute|run)[_a-zA-Z0-9]*(?:tool|function|command)|`
- `(?:invoke|dispatch|execute|run)[_a-zA-Z0-9]*(?:tool|function|command)\s*\(|`
- `tool_call\s*\(|function_call\s*\(|subprocess\.(?:run|Popen)|os\.system\s*\()\b`
- `\b(?:loop[_ -]?detector|repetition[_ -]?detector|record[_ -]?tool|record\s*\(|same[_ -]?args|`
- `args[_ -]?hash|max[_ -]?(?:steps|turns|iterations|loops|retries)|retry[_ -]?budget|timeout|deadline|`
- `circuit[_ -]?breaker|ask[_ -]?to[_ -]?continue)\b`
- `: [],
        `
- `].append(f`
- `: `
- `: `
- `] and refs[`
- `: `
- `, `

## Memory Freshness

**Scanner file**: `hermescheck/scanners/memory_freshness.py`

**Default severity**: `medium`

**Regex patterns**:

- `(?:memory|checkpoint|archive|summary|history|session|state|snapshot|insight)`
- `(?:^|[-_ ])(?:old|new|latest|final|draft|copy|backup|bak|v\d+)(?:$|[-_ ])`
- `[^a-z0-9]+`
- `: `

## Memory Lifecycle

**Scanner file**: `hermescheck/scanners/memory_lifecycle.py`

**Default severity**: `high`

**Regex patterns**:

- `\b(?:memory|memories|remember|recall|profile|preference|facts?|episode|reflection|vector store|`
- `embedding|sqlite|fts5|semantic search|second brain|history|summary)\b|(?:记忆|回忆|偏好|事实|反思)`
- `\b(?:identity|preference|goal|project|habit|decision|constraint|relationship|episode|reflection|`
- `memory[_ -]?type|fact[_ -]?type)\b`
- `\b(?:top[_ -]?k|limit|char(?:acter)?[_ -]?limit|token[_ -]?budget|context[_ -]?budget|retrieval[_ -]?budget|`
- `max[_ -]?(?:tokens|chars|memories)|fts5|full[-_ ]?text search)\b`
- `\b(?:confidence|conflict|contradiction|merge|dedupe|duplicate|overlap|similarity|newer wins|`
- `resolve[_ -]?conflict|coalesce|canonical)\b`
- `\b(?:active|durable|ttl|decay|retention|reinforce|reinforcement|prune|dismiss|dismissed|stale|`
- `expire|expiration|aging|archive)\b`
- `\b(?:pointer|anchor|source_ref|evidence_ref|semantic_hash|topic_anchor|page fault|page table|swap in)\b`
- `)}
    files = list(iter_source_files(target))
    for fp in files:
        if not fp.is_file() or _should_skip(fp) or fp.suffix not in SCAN_EXTENSIONS:
            continue
        try:
            lines = fp.read_text(encoding=`
- `].append(ref)
    return refs


def _evidence(refs: dict[str, list[str]], *keys: str, limit: int = 9) -> list[str]:
    out: list[str] = []
    seen: set[str] = set()
    for key in keys:
        for ref in refs.get(key, []):
            if ref not in seen:
                out.append(ref)
                seen.add(ref)
            if len(out) >= limit:
                return out
    return out


def scan_memory_lifecycle(target: Path) -> List[Dict[str, Any]]:
    refs = _collect_refs(target)
    if len(refs[`
- `],
    }
    present = {name: values for name, values in governance.items() if values}
    if len(present) >= 3:
        return []

    governance_summary = `
- `: `
- `),
            `

## Memory Patterns

**Scanner file**: `hermescheck/scanners/memory_patterns.py`

**Default severity**: `medium`

**Regex patterns**:

- `(?:memory.*admit|long.?term.*update|persist.*memory|save.*to.*memory|`
- `memory.*store|write.*memory|commit.*memory|memory.*insert)`
- `(?:add.*memory|upsert.*vector|append.*context|history.*append|`
- `messages.*append|memory.*push|context.*grow|buffer.*append|`
- `memory.*add|vector.*insert|embeddings.*store)`
- `(?:max_|limit|ttl|expire|k=|top_|threshold|trim|truncate|`
- `max_|_max|capacity|bounded|evict|prune|retention|window_size)`
- `: `

## Memory Retrieval I18N

**Scanner file**: `hermescheck/scanners/memory_retrieval_i18n.py`

**Default severity**: `high`

**Regex patterns**:

- `\b(?:fts5|full[-_ ]?text search|MATCH|unicode61|sqlite[_ -]?fts|[A-Za-z0-9_]+_fts)\b`
- `\bunicode61\b`
- `\b(?:cjk|chinese|japanese|korean|multilingual|i18n|unicode|locale|non[-_ ]?english)\b|`
- `(?:中文|汉字|漢字|日文|韩文|韓文|多语言|多語言)`
- `\b(?:ngram|bi[-_ ]?gram|tri[-_ ]?gram|jieba|janome|mecab|kuromoji|sentencepiece|`
- `custom[_ -]?tokenizer|tokenize_for_fts|fts_match_query|like[_ -]?fallback|fallback[_ -]?like|`
- `embedding[_ -]?fallback|semantic[_ -]?fallback|vector[_ -]?fallback|reindex|rebuild[_ -]?index)\b`
- `(?:中文回复|后端|用户偏好|多语言|cjk|unicode61|ngram|trigram|fts.*中文|中文.*fts|`
- `japanese|korean|non[-_ ]?english)`
- `: `
- `: `

## Observability

**Scanner file**: `hermescheck/scanners/observability.py`

**Default severity**: `medium`

**Regex patterns**:

- `(?:langsmith|langfuse|opentelemetry|arize|phoenix|`
- `callback.*handler|tracer|telemetry|observ|`
- `cost.*track|token.*count|latency.*track|`
- `span.*create|trace.*start|metric.*record|`
- `promptlayer|helicone|braintrust|smith\.ai|`
- `langsmith\.run|langfuse\.track|otel\.|open telemetry)`
- `: `

## Os Architecture

**Scanner file**: `hermescheck/scanners/os_architecture.py`

**Default severity**: `high`

**Regex patterns**:

- `\b(?:harness|orchestrator|scheduler|kernel|agent loop|react loop|main loop)\b`
- `\b(?:context|memory|summary|compact|compression|rag|vector|embedding|history)\b`
- `\b(?:page table|page fault|paging|swap(?: in| out)?|lru|hot data|cold data|heat score|ttl|recency|pin(?:ned)?)\b`
- `\b(?:tool use|tool call|tool_call|function calling|function_call|execute[_ -]?shell(?:_command)?|shell command|subprocess|system call|syscall)\b`
- `\b(?:syscall table|capability|capabilities|cap_[a-z0-9_]+|permission matrix|seccomp)\b`
- `: re.compile(
        r`
- `\b(?:time slice|timeslice|deadline|budget|priority|preempt|context switch|yield|cancel|cancellation|backpressure)\b`
- `\b(?:knowledge|skills?|rag|vector[_ -]?store|vectordb|embedding|docs?|notes?|github|resources?)\b`
- `\b(?:vfs|virtual file|mount|mount point|resource path|semantic fs)\b`
- `\b(?:context replay|conversation replay|transcript replay|session replay|chat history|`
- `stored conversation|conversation history|runstate|run state|previous_response_id|conversation id)\b|`
- `(?:上下文回放|录像带|聊天记录|会话历史|读档)`
- `\b(?:environment state|environment is the state|filesystem state|file system state|workspace state|`
- `working tree|server state|durable filesystem|durable workspace|persistent workspace|on-disk state)\b|`
- `(?:环境即状态|环境状态|现场|服务器文件|硬盘|物理生效)`
- `\b(?:side[-_ ]?effect log|action log|operation log|audit log|journal|write[-_ ]?ahead|`
- `commit log|trajectory|tool result|command output|execution record)\b|`
- `(?:副作用记录|动作日志|操作日志|执行记录|工具结果|命令输出)`
- `\b(?:idempotent recovery|idempotent resume|retry[-_ ]?safe|resumable run|resume after interruption|`
- `interrupted run|wake[-_ ]?up instruction|system interrupt|recovery checkpoint|durable execution)\b|`
- `(?:幂等恢复|幂等续接|自动续接|唤醒指令|中断恢复|恢复检查点)`
- `: re.compile(
        r`
- `qwen|codex|claude|gemini|opencode)\b.{0,80}\b(?:cli|command|subprocess|worker|spawn|process|pool)\b|`
- `\b(?:subprocess\.run|subprocess\.Popen|create_subprocess_exec)\b.{0,120}\b(?:qwen|codex|claude|gemini|opencode)\b|`
- `(?:外部\s*LLM|代码\s*CLI|CLI\s*进程池|命令行\s*worker|拉起\s*qwen|拉起\s*codex|拉起\s*claude)`
- `\b(?:task json|task file|task envelope|work order|handoff file|job spec|delegation spec|`
- `structured task|task manifest)\b|(?:任务\s*JSON|任务文件|任务信封|工作单|交接文件|结构化任务)`
- `\b(?:natural language prompt|natural-language prompt|prompt text|worker prompt|stdin prompt|`
- `to_prompt|task file path|read this task file|do not send raw json|not raw json|no raw json)\b|`
- `(?:自然语言\s*Prompt|自然语言提示|worker\s*提示词|stdin\s*提示词|不要裸(?:扔|传)\s*JSON|不能裸(?:扔|传)\s*JSON)`
- `\b(?:stdout|stderr|exit code|returncode|capture_output|completedprocess|standard output|`
- `process output|worker result)\b|(?:标准输出|标准错误|退出码|返回码|捕获输出|worker\s*结果)`
- `\b(?:process pool|worker pool|timeout|deadline|concurrency|semaphore|queue|cancel|cancellation|`
- `asyncio\.create_subprocess_exec|subprocess\.run\(.{0,80}timeout)\b|(?:进程池|worker\s*池|超时|并发|取消|队列)`
- `: `
- `: `
- `) >= 5 and signals.count(`
- `: `
- `,
                `
- `, `
- `: `
- `: `
- `) >= 2 and (
        signals.count(`
- `: `
- `,
                    `

## Output Pipeline

**Scanner file**: `hermescheck/scanners/output_pipeline.py`

**Default severity**: `medium`

**Regex patterns**:

- `(?:mutate.*response|rewrite.*output|transform.*answer|shape.*response|`
- `post.?process.*llm|stream.*chunk|yield.*token|format.*response|`
- `response.*filter|output.*sanitize|strip.*tag|clean.*response|`
- `response.*hook|after.*llm|post.*llm)`
- `(?:buffer|assemble|reconstruct|join|concat|merge.*stream|`
- `chunk.*buffer|response.*build|output.*assemble|token.*stream)`
- `: `

## Path Filters

**Scanner file**: `hermescheck/scanners/path_filters.py`

**Default severity**: `medium`

**Regex patterns**:

- `,
}

HASHED_BUNDLE_RE = re.compile(
    r`
- `-[a-z0-9_-]{6,}(?:-[a-z0-9_-]{4,})*(?: \d+)?\.(?:js|cjs|mjs)$`
- `^[a-z0-9_.-]+-[a-z0-9_-]{8,}(?: \d+)?\.(?:js|cjs|mjs|css|map)$`
- `.*\.min\.(?:js|cjs|mjs)$`

## Pipeline Middleware Integrity

**Scanner file**: `hermescheck/scanners/pipeline_middleware_integrity.py`

**Default severity**: `high`

**Regex patterns**:

- `\b(?:pipeline|pipelines|middleware|filter|filters|inbound|outbound|pre[_ -]?process|post[_ -]?process|`
- `before[_ -]?(?:llm|model)|after[_ -]?(?:llm|model)|request[_ -]?filter|response[_ -]?filter)\b`
- `\b(?:sanitize|redact|mask|moderation|translate|rewrite|inject[_ -]?prompt|transform[_ -]?(?:message|response)|`
- `strip|replace|content[_ -]?filter|pii|sensitive)\b`
- `\b(?:priority|order|sequence|sort|chain|before|after|stage|rank|position)\b`
- `\b(?:raw[_ -]?(?:message|response|request)|transformed[_ -]?(?:message|response|request)|audit[_ -]?log|`
- `trace|span|diff|before[_ -]?after|log[_ -]?mutation|original[_ -]?content)\b`
- `\b(?:fail[_ -]?(?:open|closed)|on[_ -]?error|try\s*:|except|catch|fallback|skip[_ -]?filter|`
- `filter[_ -]?error|raise|timeout)\b`
- `, `
- `].append(ref)
            if AUDIT_RE.search(line):
                refs[`
- `: `
- `]:
        findings.append(
            {
                `
- `: `
- `),
                `
- `: `

## Plugin Execution Policy

**Scanner file**: `hermescheck/scanners/plugin_execution_policy.py`

**Default severity**: `critical`

**Regex patterns**:

- `\b(?:plugin|plugins|function|functions|pipe|valves|user[_ -]?valves|extension|extensions|`
- `load[_ -]?plugin|plugin[_ -]?loader|dynamic[_ -]?tool|custom[_ -]?tool)\b`
- `\b(?:exec\s*\(|eval\s*\(|compile\s*\(|importlib|__import__|load_module|module_from_spec|`
- `exec_module|dynamic[_ -]?import)\b`
- `\b(?:pip\s+install|uv\s+pip\s+install|subprocess\.(?:run|Popen).*pip|requirements|dependencies|`
- `install[_ -]?requirements|frontmatter)\b`
- `\b(?:sandbox|allowlist|denylist|blocklist|permission|capability|scope|isolat(?:e|ion)|`
- `container|venv|virtualenv|timeout|resource[_ -]?limit|read[_ -]?scope|write[_ -]?scope)\b`
- `\b(?:hash|sha256|pinned|pin|lockfile|allowlisted[_ -]?packages|allowed[_ -]?packages|`
- `package[_ -]?allowlist|constraints\.txt|requirements\.lock)\b`
- `\b(?:admin[_ -]?only|user[_ -]?plugin|tenant|owner|role|rbac|oauth|auth|trusted|untrusted|`
- `review|approval|enable[_ -]?plugin|disable[_ -]?plugin)\b`
- `: `
- `: `

## Rag Pipeline Governance

**Scanner file**: `hermescheck/scanners/rag_pipeline_governance.py`

**Default severity**: `high`

**Regex patterns**:

- `\b(?:rag|retrieval[_ -]?augmented|knowledge[_ -]?base|vector[_ -]?(?:store|db|search)|`
- `embedding|embeddings|document[_ -]?(?:loader|upload|ingest)|chroma|qdrant|milvus|faiss|`
- `bm25|hybrid[_ -]?search|rerank|reranker)\b`
- `\b(?:chunk[_ -]?(?:size|overlap)|text[_ -]?splitter|recursivecharactertextsplitter|split[_ -]?documents|`
- `token[_ -]?splitter|document[_ -]?chunk)\b`
- `\b(?:top[_ -]?k|limit|score[_ -]?threshold|max[_ -]?(?:tokens|chars|context|documents)|`
- `context[_ -]?budget|retrieval[_ -]?budget|similarity[_ -]?threshold|rerank[_ -]?top[_ -]?k)\b`
- `\b(?:full[_ -]?context|rag[_ -]?full[_ -]?context|bypass[_ -]?embedding|bypass[_ -]?retrieval|`
- `skip[_ -]?retrieval|raw[_ -]?document|entire[_ -]?document)\b`
- `\b(?:ingest[_ -]?status|embedding[_ -]?status|async[_ -]?embedding|retry|backoff|dedupe|`
- `content[_ -]?hash|document[_ -]?(?:id|version)|index[_ -]?version|reindex|failed[_ -]?documents)\b`
- `: `
- `: `

## Role Play Orchestration

**Scanner file**: `hermescheck/scanners/role_play_orchestration.py`

**Default severity**: `medium`

**Regex patterns**:

- `: re.compile(
        r`
- `: re.compile(r`
- `: re.compile(
        r`
- `: re.compile(
        r`
- `: re.compile(r`
- `(?:\b\w+\s+agent\b|\bagent\s+(?:role|team|crew|department)\b|(?:智能体|代理)\s*(?:角色|团队|部门))`
- `(?:agent|subagent|multi[_ -]?agent|swarm|crew|tool\s+role|handoff|pipeline|chain|智能体|代理|多智能体|交接|接棒|流水线)`
- `(?:handoff|hand[-_ ]?off|pass(?:es|ed)?\s+to|relay|pipeline|chain|next\s+agent|transfer\s+to|`
- `接棒|交接|移交|传给|下一个\s*(?:agent|智能体|代理)|流水线|串行|部门)`
- `(?:tool|script|command|function|workflow|工具|脚本|命令|函数|流程).{0,32}(?:agent|智能体|代理)`
- `: `

## Runtime Complexity

**Scanner file**: `hermescheck/scanners/runtime_complexity.py`

**Default severity**: `medium`

**Regex patterns**:

- `\b(fastapi|flask|express|django|router|api router)\b`
- `\b(streamlit|react|next|vue|svelte|electron|pywebview|tauri)\b`
- `\b(celery|rq|bullmq|rabbitmq|kafka|worker queue)\b`
- `\b(docker|kubernetes|pm2|supervisor|launchd|systemd|nginx|gunicorn)\b`
- `\b(redis|postgres|mysql|mongodb|sqlite|vector store|milvus|pinecone)\b`
- `\b(langchain|autogen|crewai|mcp|swarm|agent loop|tool calling)\b`
- `: `

## Secrets

**Scanner file**: `hermescheck/scanners/secrets.py`

**Default severity**: `critical`

**Regex patterns**:

- `sk-[a-zA-Z0-9]{20,}`
- `ghp_[a-zA-Z0-9]{36}`
- `glpat-[a-zA-Z0-9]{20,}`
- `AKIA[0-9A-Z]{16}`
- `(?i)(?:api[_-]?key|apikey|secret[_-]?key|token)\s*[=:]\s*['\`
- `(?:example|your_|placeholder|xxx|test)`
- `(?:`
- `sk-(?:123|abc|test|fake|dummy|example|x{4,})[a-z0-9_-]*|`
- `dapi(?:123|abc|test|fake|dummy|example)[a-z0-9_-]*|`
- `akia(?:0{8,}|1{8,}|6{8,}|test|fake|dummy|example)[a-z0-9_-]*|`
- `gAAAAABinvalid[a-z0-9_-]*|`
- `(?:1234567890|abcdef){2,}`
- `)`
- `(?:algolia|docsearch|search).*api[_-]?key|api[_-]?key.*(?:algolia|docsearch|search)|`
- `(?:next_public|vite_|public_|publishable)`
- `: `

## Self Evolution Capability

**Scanner file**: `hermescheck/scanners/self_evolution_capability.py`

**Default severity**: `high`

**Regex patterns**:

- `\b(?:agent|agent[_ -]?loop|orchestrator|subagent|tool[_ -]?call|function[_ -]?call|memory|`
- `scheduler|rag|mcp|plugin|skill|llm)\b|(?:智能体|工具调用|记忆|技能)`
- `\b(?:external[_ -]?signal|signal[_ -]?(?:intake|screening)|upstream|reference[_ -]?project|`
- `competitor|benchmark|issue|pull request|pr|release note|production log|user feedback|github trend)\b|`
- `(?:外部信号|信号筛选|热门项目|用户反馈|线上日志|上游项目)`
- `\b(?:source[_ -]?reading|read[_ -]?source|code archaeology|architecture review|directory tree|`
- `entrypoint|main loop|core class|adr|design doc|decision record|boundary analysis)\b|`
- `(?:解剖学习|读源码|目录结构|主入口|核心类|设计决策|边界分析)`
- `\b(?:pattern[_ -]?extraction|extract(?:ed)? pattern|design pattern|reusable pattern|generalize|`
- `generalization|not copy|not copied|not a code copy|anti[_ -]?copy)\b|`
- `(?:提取模式|设计模式|举一反三|不是照搬|不照搬|不是代码副本)`
- `\b(?:constraint[_ -]?adapt(?:ation)?|fit constraints|local constraints|zero heavy dependencies|`
- `no heavy dependenc(?:y|ies)|lightweight|2gb ram|bounded resource|integrate with existing)\b|`
- `(?:约束适配|本地约束|零重型依赖|轻量|2GB|融入已有)`
- `\b(?:small[_ -]?step|minimal implementation|independent module|isolated module|try/except|`
- `fail[_ -]?soft|non[_ -]?intrusive|feature flag|rollback|bounded change)\b|`
- `(?:小步落地|最小实现|独立模块|不侵入|可回滚|失败不影响)`
- `\b(?:verification[_ -]?loop|validation loop|eval|regression test|smoke test|acceptance|`
- `self[_ -]?test|test passed|post[_ -]?change review|retro|lesson learned)\b|`
- `(?:验证闭环|回归测试|烟测|验收|复盘|教训)`
- `: `
- `: `
- `: `

## Skill Duplication

**Scanner file**: `hermescheck/scanners/skill_duplication.py`

**Default severity**: `medium`

**Regex patterns**:

- `(?:skill|sop|runbook|playbook|guide|checklist|instruction)`
- `(?:^|[-_ ])(?:old|new|latest|final|draft|copy|backup|bak|v\d+)(?:$|[-_ ])`
- `[^a-z0-9]+`
- `: `

## Startup Complexity

**Scanner file**: `hermescheck/scanners/startup_complexity.py`

**Default severity**: `medium`

**Regex patterns**:

- `(?:launch|start|run|serve|bootstrap|entrypoint|daemon|supervisord|pm2|launchd|docker-compose|compose|procfile|app)\b`
- `(?:subprocess\.run|subprocess\.Popen|os\.system|exec\s+|python\s+-m|node\s+|bash\s+|sh\s+|launchctl|pm2|supervisor)`
- `: `

## Token Usage

**Scanner file**: `hermescheck/scanners/token_usage.py`

**Default severity**: `high`

**Regex patterns**:

- `\b(?:agent|agent loop|orchestrator|subagent|tool_call|llm|chat|model)\b|智能体`
- `\b(?:max[_ -]?context[_ -]?tokens|max[_ -]?(?:context|tokens)|context[_ -]?(?:window|length|tokens|limit)|`
- `token[_ -]?(?:budget|limit)|input[_ -]?tokens)\b`
- `(?<![\w.])([0-9][0-9_,.]*)\s*([kKmM万]?)(?:\s*(?:tokens?|context))?`
- `\b(?:full[_ -]?(?:history|context|transcript)|all[_ -]?(?:messages|history|memory|context)|`
- `entire[_ -]?(?:history|conversation|repo|repository|workspace|context)|conversation[_ -]?history|`
- `session[_ -]?history|chat[_ -]?history|transcript|load[_ -]?all|read[_ -]?all|include[_ -]?all)\b`
- `\b(?:rglob\s*\(\s*['\`
- `readFileSync\s*\(|readFile\s*\(|load_all_files|read_repository|scan_workspace)\b`
- `\b(?:prompt|messages|context|system[_ -]?prompt|chat|completion|llm|model|createChatCompletion|responses\.create)\b`
- `\b(?:token[_ -]?budget|max[_ -]?(?:tokens|chars|messages|context)|char(?:acter)?[_ -]?limit|`
- `truncate|trim|prune|top[_ -]?k|retrieval[_ -]?budget|summary|summarize|compact|compression|`
- `page[_ -]?table|paging|lru|cache|content[_ -]?hash|skill|sop|workflow|layered[_ -]?memory|`
- `right knowledge|relevant knowledge|less noise)\b|(?:分层记忆|省\s*token|极致省\s*Token|技能|经验固化)`
- `(?:<\s*30k|不到\s*30k|30k context|fraction of the 200k|200k.?1m|layered memory|`
- `\bL[0-4]\b|crystalliz(?:e|es|ing)|skill tree|direct recall|right knowledge|less noise|`
- `minimal toolset|9 atomic tools|~100[- ]line agent loop|token efficient|极致省\s*Token|分层记忆|`
- `固化为\s*Skill|下次同类任务直接调用|关键信息始终在场)`
- `: `
- `: `
- `: `

## Tool Enforcement

**Scanner file**: `hermescheck/scanners/tool_enforcement.py`

**Default severity**: `high`

**Regex patterns**:

- `(?:must use tool|required call|always use|tool is required|`
- `required to call|you must call|mandatory tool use)`
- `(?:tool_call|toolCall|tool_use|function_call|tool_choice|use_tool)`
- `(?:assert |if not |raise |\.validate|\.check|verify|guard|enforce|sanity_check)`
- `: `
- `: `

## Tool Server Boundary

**Scanner file**: `hermescheck/scanners/tool_server_boundary.py`

**Default severity**: `high`

**Regex patterns**:

- `\b(?:mcp|model[_ -]?context[_ -]?protocol|openapi|swagger|tool[_ -]?server|remote[_ -]?tool|`
- `external[_ -]?tool|tool[_ -]?server[_ -]?connections|openapi\.json|/mcp)\b`
- `\b(?:openapi\.json|swagger\.json|requests\.(?:get|post)|httpx\.(?:get|post)|fetch\s*\(|axios\.|`
- `load[_ -]?spec|tool[_ -]?manifest|server[_ -]?url|base[_ -]?url)\b`
- `\b(?:allowlist|denylist|blocklist|trusted[_ -]?servers|allowed[_ -]?(?:servers|tools|hosts)|`
- `permission|capability|approval|scope|auth|oauth|api[_ -]?key|bearer|timeout|retry[_ -]?budget|`
- `rate[_ -]?limit|schema[_ -]?validation|jsonschema)\b`
- `\b(?:sha256|hash|fingerprint|pinned[_ -]?(?:spec|schema|version)|version[_ -]?pin|etag|`
- `schema[_ -]?version|lockfile)\b`
- `\b(?:write[_ -]?file|delete[_ -]?file|shell|terminal|subprocess|exec|browser|playwright|selenium|`
- `git\s+push|npm\s+publish|docker|kubectl|database|sql|filesystem|network)\b`
- `: `
- `: `
- `: `


path: references/playbooks.md
content: # Playbooks

Use one of these as the primary audit mode. Each playbook maps to one or more hermescheck scanners.

## wrapper-regression

Use when: the base model works fine but the wrapped agent is worse.
Scanner: `scan_hidden_llm_calls`, `scan_output_pipeline`
Focus: system prompt conflicts, duplicated context, hidden formatting layers.

## memory-contamination

Use when: old topics bleed into new conversations.
Scanner: `scan_memory_patterns`
Focus: same-session artifact reentry, stale session reuse, weak memory admission.

## tool-discipline

Use when: the agent skips required tools or hallucinates execution.
Scanner: `scan_tool_enforcement`
Focus: code-enforced vs prompt-enforced tool requirements, skip paths.

## rendering-transport

Use when: internal answer is correct but delivery is broken.
Scanner: `scan_output_pipeline`
Focus: transport payload assumptions, platform-layer mutations.

## hidden-agent-layers

Use when: silent repair/retry/summarize loops run without contracts.
Scanner: `scan_hidden_llm_calls`
Focus: hidden repair agents, second-pass LLM calls, maintenance-worker synthesis.

## code-execution-safety

Use when: the agent uses exec/eval/shell without sandboxing.
Scanner: `scan_code_execution`
Focus: resource limits, input validation, isolation.

## memory-growth-hazard

Use when: memory/context grows without limits.
Scanner: `scan_memory_patterns`
Focus: size limits, TTL, retention policies.

## observability-gap

Use when: there is no tracing or debugging capability.
Scanner: `scan_observability`
Focus: add logging, cost metrics, session replay.


path: references/report-schema.json
content: {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/huangrichao2020/hermescheck/schemas/report-v1.json",
  "title": "hermescheck — Audit Report Schema v1",
  "description": "JSON Schema for validating agent audit reports generated by hermescheck.",
  "type": "object",
  "required": ["schema_version", "executive_verdict", "scope", "maturity_score", "evidence_pack", "findings", "conflict_map", "ordered_fix_plan"],
  "additionalProperties": false,
  "properties": {
    "schema_version": {
      "type": "string",
      "const": "hermescheck.report.v1"
    },
    "scan_metadata": {
      "type": "object",
      "required": ["profile", "scan_timestamp", "scan_duration_seconds", "scanner_count"],
      "additionalProperties": false,
      "properties": {
        "profile": { "type": "string", "minLength": 1 },
        "scan_timestamp": { "type": "string", "minLength": 1 },
        "scan_duration_seconds": { "type": "number", "minimum": 0 },
        "scanner_count": { "type": "integer", "minimum": 1 }
      }
    },
    "executive_verdict": {
      "type": "object",
      "required": ["overall_health", "primary_failure_mode", "most_urgent_fix"],
      "additionalProperties": false,
      "properties": {
        "overall_health": {
          "type": "string",
          "enum": ["critical", "high_risk", "unstable", "acceptable", "strong"],
          "description": "Overall system health verdict"
        },
        "primary_failure_mode": {
          "type": "string",
          "minLength": 1,
          "description": "The dominant failure pattern observed"
        },
        "most_urgent_fix": {
          "type": "string",
          "minLength": 1,
          "description": "The single most urgent action required"
        }
      }
    },
    "severity_summary": {
      "type": "object",
      "required": ["critical", "high", "medium", "low"],
      "additionalProperties": false,
      "properties": {
        "critical": { "type": "integer", "minimum": 0 },
        "high": { "type": "integer", "minimum": 0 },
        "medium": { "type": "integer", "minimum": 0 },
        "low": { "type": "integer", "minimum": 0 }
      }
    },
    "maturity_score": {
      "type": "object",
      "required": [
        "score",
        "raw_points",
        "capped_raw_points",
        "pre_penalty_score",
        "penalty",
        "uncapped_penalty",
        "penalty_cap",
        "era_key",
        "era_name",
        "era_description",
        "share_line",
        "score_formula",
        "signal_points",
        "penalty_breakdown",
        "score_caps",
        "methodology_gate",
        "self_evolution_gate",
        "strengths",
        "next_milestones",
        "evidence_refs"
      ],
      "additionalProperties": false,
      "properties": {
        "score": { "type": "integer", "minimum": 0, "maximum": 100 },
        "raw_points": { "type": "integer", "minimum": 0 },
        "capped_raw_points": { "type": "integer", "minimum": 0, "maximum": 100 },
        "pre_penalty_score": { "type": "integer", "minimum": 0, "maximum": 100 },
        "penalty": { "type": "integer", "minimum": 0 },
        "uncapped_penalty": { "type": "integer", "minimum": 0 },
        "penalty_cap": { "type": "integer", "minimum": 0 },
        "era_key": {
          "type": "string",
          "enum": [
            "stone_age",
            "bronze_age",
            "iron_age",
            "steam_age",
            "combustion_age",
            "new_energy_age",
            "ai_age"
          ]
        },
        "era_name": {
          "type": "string",
          "enum": ["石器时代", "青铜时代", "铁器时代", "蒸汽机时代", "内燃气时代", "新能源时代", "人工智能时代"]
        },
        "era_description": { "type": "string", "minLength": 1 },
        "share_line": { "type": "string", "minLength": 1 },
        "score_formula": { "type": "string", "minLength": 1 },
        "signal_points": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["key", "label", "points", "evidence_refs"],
            "additionalProperties": false,
            "properties": {
              "key": { "type": "string", "minLength": 1 },
              "label": { "type": "string", "minLength": 1 },
              "points": { "type": "integer", "minimum": 0 },
              "evidence_refs": {
                "type": "array",
                "items": { "type": "string" }
              }
            }
          }
        },
        "penalty_breakdown": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "title",
              "severity",
              "source_layer",
              "title_penalty",
              "severity_penalty",
              "total_penalty",
              "evidence_refs",
              "recommended_fix"
            ],
            "additionalProperties": false,
            "properties": {
              "title": { "type": "string", "minLength": 1 },
              "severity": { "type": "string", "enum": ["critical", "high", "medium", "low"] },
              "source_layer": { "type": "string", "minLength": 1 },
              "title_penalty": { "type": "integer", "minimum": 0 },
              "severity_penalty": { "type": "integer", "minimum": 0 },
              "total_penalty": { "type": "integer", "minimum": 0 },
              "evidence_refs": {
                "type": "array",
                "items": { "type": "string" }
              },
              "recommended_fix": { "type": "string" }
            }
          }
        },
        "score_caps": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["gate", "before", "after", "reason"],
            "additionalProperties": false,
            "properties": {
              "gate": { "type": "string", "minLength": 1 },
              "before": { "type": "integer", "minimum": 0 },
              "after": { "type": "integer", "minimum": 0 },
              "reason": { "type": "string", "minLength": 1 }
            }
          }
        },
        "methodology_gate": {
          "type": "object",
          "required": ["detected", "cap_applied", "note"],
          "additionalProperties": false,
          "properties": {
            "detected": { "type": "boolean" },
            "cap_applied": { "type": "boolean" },
            "note": { "type": "string", "minLength": 1 }
          }
        },
        "self_evolution_gate": {
          "type": "object",
          "required": ["detected", "cap_applied", "note"],
          "additionalProperties": false,
          "properties": {
            "detected": { "type": "boolean" },
            "cap_applied": { "type": "boolean" },
            "note": { "type": "string", "minLength": 1 }
          }
        },
        "strengths": {
          "type": "array",
          "items": { "type": "string" }
        },
        "next_milestones": {
          "type": "array",
          "items": { "type": "string" }
        },
        "evidence_refs": {
          "type": "array",
          "items": { "type": "string" }
        }
      }
    },
    "scope": {
      "type": "object",
      "required": ["target_name", "entrypoints", "channels", "model_stack", "time_window", "layers_to_audit"],
      "additionalProperties": false,
      "properties": {
        "target_name": { "type": "string", "minLength": 1 },
        "entrypoints": {
          "type": "array",
          "items": { "type": "string" },
          "minItems": 1
        },
        "channels": {
          "type": "array",
          "items": { "type": "string" }
        },
        "model_stack": {
          "type": "array",
          "items": { "type": "string" },
          "minItems": 1
        },
        "time_window": { "type": "string", "minLength": 1 },
        "layers_to_audit": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "system_prompt",
              "session_history",
              "long_term_memory",
              "distillation",
              "active_recall",
              "completion_closure",
              "tool_selection",
              "tool_execution",
              "tool_interpretation",
              "answer_shaping",
              "platform_rendering",
              "token_usage",
              "fallback_loops",
              "persistence",
              "impression_memory",
              "hermes_runtime_contract",
              "hermes_command_registry",
              "os_memory",
              "os_scheduler",
              "os_syscall",
              "os_vfs",
              "stateful_recovery",
              "llm_cli_workers",
              "knowledge_retrieval",
              "plugin_execution",
              "remote_tools",
              "pipeline_middleware",
              "runtime_bug_inference",
              "self_evolution"
            ]
          },
          "minItems": 1
        }
      }
    },
    "evidence_pack": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["kind", "source", "location", "summary", "time_scope"],
        "additionalProperties": false,
        "properties": {
          "kind": {
            "type": "string",
            "enum": ["code", "log", "db", "config", "screenshot", "test"]
          },
          "source": { "type": "string", "minLength": 1 },
          "location": { "type": "string", "minLength": 1 },
          "summary": { "type": "string", "minLength": 1 },
          "time_scope": {
            "type": "string",
            "enum": ["current_state", "historical_state", "both"]
          }
        }
      },
      "minItems": 1
    },
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["severity", "title", "symptom", "user_impact", "source_layer", "mechanism", "root_cause", "evidence_refs", "confidence", "fix_type", "recommended_fix"],
        "additionalProperties": false,
        "properties": {
          "severity": {
            "type": "string",
            "enum": ["critical", "high", "medium", "low"]
          },
          "title": { "type": "string", "minLength": 1 },
          "symptom": { "type": "string", "minLength": 1 },
          "user_impact": { "type": "string", "minLength": 1 },
          "source_layer": { "type": "string", "minLength": 1 },
          "mechanism": { "type": "string", "minLength": 1 },
          "root_cause": { "type": "string", "minLength": 1 },
          "evidence_refs": {
            "type": "array",
            "items": { "type": "string" },
            "minItems": 1
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Confidence in the finding (0.0 to 1.0)"
          },
          "fix_type": {
            "type": "string",
            "enum": [
              "code_change",
              "add_integration",
              "code_gate",
              "prompt_removal",
              "prompt_tightening",
              "state_cleanup",
              "architecture_change",
              "test_change",
              "configuration_change"
            ]
          },
          "recommended_fix": { "type": "string", "minLength": 1 }
        }
      }
    },
    "conflict_map": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["from_layer", "to_layer", "conflict_type", "note"],
        "additionalProperties": false,
        "properties": {
          "from_layer": { "type": "string", "minLength": 1 },
          "to_layer": { "type": "string", "minLength": 1 },
          "conflict_type": {
            "type": "string",
            "enum": ["stale_state", "duplication", "contradiction", "amplification", "silent_override"]
          },
          "note": { "type": "string", "minLength": 1 }
        }
      }
    },
    "ordered_fix_plan": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["order", "goal", "why_now", "expected_effect"],
        "additionalProperties": false,
        "properties": {
          "order": { "type": "integer", "minimum": 1 },
          "goal": { "type": "string", "minLength": 1 },
          "why_now": { "type": "string", "minLength": 1 },
          "expected_effect": { "type": "string", "minLength": 1 }
        }
      }
    },
    "target_self_review": {
      "type": "object",
      "required": [
        "source",
        "methodology_version",
        "agent_name",
        "summary",
        "claims",
        "risks",
        "false_positive_notes",
        "improvement_plan"
      ],
      "additionalProperties": true,
      "properties": {
        "source": { "type": "string", "minLength": 1 },
        "methodology_version": { "type": "string", "minLength": 1 },
        "agent_name": { "type": "string", "minLength": 1 },
        "summary": { "type": "string", "minLength": 1 },
        "claims": { "$ref": "#/$defs/self_review_items" },
        "risks": { "$ref": "#/$defs/self_review_items" },
        "false_positive_notes": { "$ref": "#/$defs/self_review_items" },
        "improvement_plan": { "$ref": "#/$defs/self_review_items" },
        "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
      }
    }
  },
  "$defs": {
    "self_review_items": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["title", "evidence", "recommendation"],
        "additionalProperties": false,
        "properties": {
          "title": { "type": "string", "minLength": 1 },
          "evidence": { "type": "string" },
          "recommendation": { "type": "string" }
        }
      }
    }
  }
}


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)