Summary

An automated documentation audit noticed several places where the docs/specs appear to describe behavior that may no longer match the current implementation, as well as a few implementation details that seem undocumented or hardcoded. A number of these may simply reflect design docs becoming stale as the code evolved, so we wanted to report them in one place for review.

Note: This issue was generated automatically by LyingDocs, a documentation-code misalignment detection tool. The analysis may contain errors or misinterpretations — please feel free to close or correct this issue if any finding does not apply or if we have misunderstood the codebase.

Finding Categories

The findings below are classified into one or more of the following categories:

Category	Meaning
LogicMismatch	The code behaves differently from what the documentation describes
PhantomSpec	The documentation describes a feature or behavior that does not appear to exist in the code
ShadowLogic	The code contains significant behavior that is not documented at all
HardcodedDrift	A value or parameter described as configurable in the docs is hardcoded in the implementation

Findings

ACP streaming behavior appears different from setup docs

• Category: LogicMismatch
• Documentation reference: acp-setup.md:198-201
• Code reference: acp_adapter/server.py:394

The ACP setup docs say ACP streams responses incrementally, but it appears that the ACP server currently wires thinking/tool progress callbacks and returns assistant text only as a final response. We noticed that AIAgent seems to support streaming text via stream_delta_callback / interim_assistant_callback, but ACP does not appear to connect those paths. If intentional, the docs may need to clarify what is streamed versus what is only emitted at completion.

ACP log level env var may be documented but not honored

• Category: LogicMismatch
• Documentation reference: acp-setup.md:216-220
• Code reference: acp_adapter/entry.py:23

The docs suggest HERMES_LOG_LEVEL=DEBUG hermes acp enables verbose ACP logging. From the audited entrypoint, it seems logging is hardcoded to INFO and does not consult HERMES_LOG_LEVEL. It may be worth clarifying whether env-based log verbosity is still supported.

Documented HERMES_MODEL override may no longer exist

• Category: PhantomSpec
• Documentation reference: acp-setup.md:158-166
• Code reference: cli.py:1644

The setup docs say users can change the model through the HERMES_MODEL environment variable. We could not find support for that override in the current code, and it appears config.yaml is treated as authoritative. If that env var was removed, the docs may need updating.

Pricing plan may understate existing cost-status support

• Category: LogicMismatch
• Documentation reference: plans/2026-03-16-pricing-accuracy-architecture-design.md:29-30
• Code reference: agent/usage_pricing.py:15

The plan states that the current system has no distinction between live estimates and reconciled billed cost. However, it appears the code already defines CostStatus values such as actual, estimated, included, and unknown, and persists related status/source fields. It seems the missing piece may be actual reconciliation flow rather than the status model itself.

Pricing plan's description of current token storage may be stale

• Category: LogicMismatch
• Documentation reference: plans/2026-03-16-pricing-accuracy-architecture-design.md:25-30
• Code reference: run_agent.py:1356

The plan describes the current system as storing only prompt/completion token totals. In the current code, it appears there are already more detailed token buckets such as input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, and reasoning_tokens, along with billing metadata.

Pricing plan's CLI current-state section appears outdated

• Category: LogicMismatch
• Documentation reference: plans/2026-03-16-pricing-accuracy-architecture-design.md:460-468
• Code reference: cli.py:6314

The plan says cli.py currently computes session cost directly from prompt/completion totals. The audited /usage flow appears to build a CanonicalUsage from input/output/cache buckets and render a CostResult with status and source metadata instead.

Reconciliation architecture appears only partially implemented

• Category: PhantomSpec
• Documentation reference: plans/2026-03-16-pricing-accuracy-architecture-design.md:374-383
• Code reference: run_agent.py:8549

The design discusses authoritative post-hoc provider reconciliation, but we could not find the runtime flow that writes actual_cost_usd, sets status to actual, or stores reconciliation IDs in the audited path. It seems possible that the code contains schema/types anticipating this future state, while the live reconciliation behavior described in the plan is not yet implemented.

Honcho integration spec may describe an older initialization model

• Category: LogicMismatch
• Documentation reference: honcho-integration-spec.md:19-22
• Code reference: run_agent.py:1148

The Honcho spec describes Honcho as being initialized directly in AIAgent.__init__ without a plugin boundary. In the current implementation, it appears AIAgent initializes a generic memory manager and loads Honcho through the memory-provider plugin system (plugins.memory.honcho).

Honcho spec references method names that may not exist

• Category: PhantomSpec
• Documentation reference: honcho-integration-spec.md:25-34
• Code reference: agent/memory_manager.py:167

The spec names _honcho_prefetch() and _honcho_fire_prefetch() as Hermes methods. We could not find those methods in the current code; the implementation appears to use provider-agnostic methods such as prefetch_all() and queue_prefetch_all() instead.

Honcho per-peer memory mode schema may be undocumented in code

• Category: PhantomSpec
• Documentation reference: honcho-integration-spec.md:173-205
• Code reference: plugins/memory/honcho/client.py:187

The spec documents config keys like memoryMode, userMemoryMode, and agentMemoryMode with precedence rules. These keys do not appear to be implemented in current Honcho config parsing, which seems to use different settings such as recallMode, writeFrequency, dialecticReasoningLevel, sessionStrategy, sessionPeerPrefix, and sessions.

Honcho session strategy docs may not match resolver behavior

• Category: LogicMismatch
• Documentation reference: honcho-integration-spec.md:271-307
• Code reference: plugins/memory/honcho/client.py:420

The spec describes session naming strategies as per-directory, global, manual map, and title-based, with a particular fallback order. The current code appears to support additional strategies such as per-session and per-repo, and the fallback behavior seems to differ as well. We also were not sure whether title-based naming is fully wired from AIAgent initialization, so this one may especially benefit from maintainer clarification.

Honcho CLI command names and mode values appear to have drifted

• Category: LogicMismatch
• Documentation reference: honcho-integration-spec.md:262-267
• Code reference: plugins/memory/honcho/cli.py:1242

The spec documents commands as bare honcho ... and says mode accepts hybrid|honcho|local. The current CLI surface appears to be hermes honcho ..., with setup delegating to hermes memory setup, and mode choices of hybrid|context|tools.

Honcho prompt injection described in spec may not be implemented

• Category: PhantomSpec
• Documentation reference: honcho-integration-spec.md:310-330
• Code reference: plugins/memory/honcho/__init__.py:370

The spec says Hermes injects a compact Honcho management-command reference into the system prompt when Honcho is active. In the current prompt block, we only noticed mode/tool guidance and optional context, not a command cheat-sheet or management-command reference.

Honcho spec may be missing additional implemented strategies and commands

• Category: ShadowLogic
• Documentation reference: honcho-integration-spec.md:271-307
• Code reference: plugins/memory/honcho/client.py:454

It appears the implementation supports additional session strategies (per-session, per-repo) and a broader CLI surface (peer, peers, tokens, migrate, enable, disable, sync, identity --show) that are not covered in the integration spec.

Container exec flow may still wrap probe failures

• Category: LogicMismatch
• Documentation reference: specs/container-cli-review-fixes.md:29-33
• Code reference: hermes_cli/main.py:543

The container CLI spec says _exec_in_container is “completely transparent” and that subprocess.run remains only for the sudo probe. In the current implementation, it appears both direct and sudo inspect probes are wrapped in _probe_container(), with custom timeout/probe-failure messages and sys.exit(1) on several paths.

Malformed .container-mode behavior may be more tolerant than spec says

• Category: LogicMismatch
• Documentation reference: specs/container-cli-review-fixes.md:41-43
• Code reference: hermes_cli/config.py:188

The spec says malformed .container-mode data should “LET IT CRASH”. The current implementation appears to let unreadable file errors propagate, but malformed content itself is mostly tolerated: non-key=value lines are ignored and missing fields seem to fall back to defaults such as backend='docker' and container_name='hermes-agent'.

Container CLI spec test count appears stale

• Category: LogicMismatch
• Documentation reference: specs/container-cli-review-fixes.md:289
• Code reference: tests/hermes_cli/test_container_aware_cli.py:1

A minor one: the spec says the existing container-aware CLI test file has 16 tests, but the current file appears to contain 18 test functions. This may just be a stale count in the document.

Container probe timeout is fixed at 15 seconds

• Category: HardcodedDrift
• Documentation reference: specs/container-cli-review-fixes.md:77-78
• Code reference: hermes_cli/main.py:549

The spec references a 15-second container probe timeout, and the implementation appears to hardcode that exact value in _probe_container(). If that value is intentionally fixed, the docs might say so explicitly; otherwise it may be worth deciding whether it should be configurable.

Suggested follow-up

• Review whether the affected docs/specs should be updated to reflect current behavior, especially for ACP setup, Honcho integration, and container CLI behavior.
• For the pricing architecture plan, consider marking sections as historical/current-state snapshots versus future design goals, if that is the intent.
• If some documented behaviors are still intended, consider updating the implementation to restore them (for example, ACP text streaming or env-controlled ACP log level).
• If any of these findings are based on incomplete context or audited the wrong runtime path, a quick clarification in comments would be very helpful, and feel free to close the issue.

---

If any of the above findings are false positives or we have misunderstood the context, we sincerely apologize for the noise. Please close this issue or leave a comment and we will take note.