fix(setup): configure a comment-only Hermes config.yaml - #2096

Summary

rea setup --client hermes still fails when ~/.hermes/config.yaml holds only comments. #1983 fixed the empty file, and its PR body left the comment-only file out because the serializer would need separate handling. This finishes that case. No issue is linked, because the gap is the one #1983 already describes.

Problem and expected behavior

A file such as # Hermes configuration\n is not whitespace, so it skips the empty-file rule #1983 added. YAML then parses it to null, the same value an empty file gives, and the Hermes branch of parseDocument rejects it:

$ printf '# Hermes configuration\n' > "$HOME/.hermes/config.yaml"
$ rea setup --client hermes --yes --format json
"status": "needs_human"
"remediation": "Hermes: Configuration …/.hermes/config.yaml is malformed: … \"Invalid input: expected record, received null\""

A file holding only a --- marker fails the same way, and fixing the parse is not enough for it. yaml 2.9.0 gives a bare --- document a null scalar as its root, where a comment-only file has empty contents. serializeHermesConfiguration cannot set a key path on a scalar ("Expected a YAML collection as document contents").

Expected: both files are configured like an empty one, and their comments stay. DeepSeek Harness already does this for a comment-only cordis.patch.yml (appends a registration to a comment-only patch file in dshClientConfiguration.test.ts).

Change and scope

• parseDocument reads a Hermes document with no settings as {}: comments only, or a bare ---. An explicit null or ~ root is written out, so it is still rejected like any other root that is not a map (changed after review).
• serializeHermesConfiguration replaces a null-scalar root with an empty map before it adds the entry. The comments the scalar carried move to the new map, so ---\n# Hermes configuration\n keeps its comment.
• A comment-only file needed no serializer change. Its root is empty and setIn already builds the map, keeping the comment above it.

Not changed, and yours to decide:

• DeepSeek Harness accepts a comment-only cordis.patch.yml but rejects a bare --- one with "Cordis patches must be a YAML operation list". It is the same null-scalar root, in a separate reader (DshCordisYaml). I left it alone to keep this to Hermes.
• JSON and JSONC clients reject a file that holds only a comment, for example // cursor\n in ~/.cursor/mcp.json, with "Invalid JSON/JSONC at offset 10: ValueExpected". That comes from the JSON parser, so this fix does not reach it, and whether each client should accept such a file is a separate question.
• Uninstall leaves mcp_servers: {} behind, after the kept comments. An empty file does the same today after fix(setup): configure an empty Hermes config.yaml #1983.

Contract and boundary impact

• Semantic owner and earliest changed stage: Hermes document parsing in parseDocument and its serializer, serializeHermesConfiguration (src/application/ClientConfigurationDocument.ts).
• CLI and MCP/tool-catalog contract: none.
• Provider, bridge, target-format, or platform compatibility: Hermes client setup on every platform.
• Evidence, artifact, provenance, or reconstruction contract: none.
• Process execution, authorization, cleanup, or containment impact: none. Backups and readback are unchanged.
• Generated metadata (docs/public/product-catalog.json), package, or installation impact: none.

Evidence and regression coverage

• Tests: fix(setup): configure an empty Hermes config.yaml #1983's it.each in tests/boundary/filesystem/hermesClientConfiguration.test.ts gets 3 more inputs: "# Hermes configuration\n", "---\n" and "---\n# Hermes configuration\n". Each case now also checks that the written file starts with the original text. The shape-diagnostics it.each gets null, ~, a comment then null, and --- ~, which must still be rejected before any change. All 4 fail on the first commit and pass on the second.
• Base reproduction: on the parent commit all 3 new cases fail with expected 'failed' to be 'configured'. The 2 existing cases still pass.
• Each part of the fix is needed. Without the empty-document check in parseDocument, all 3 fail. Without the root replacement, the 2 --- cases fail. Without carrying the comments over, "---\n# Hermes configuration\n" fails on the kept text.
• User-visible CLI output: the built CLI, rea setup --client hermes --yes against a scratch HOME, before and after.

With the fix, a second rea setup plans no actions and leaves the file byte-identical, and doctor reads the registration as aligned. rea uninstall then reports removed and keeps the comments and the marker.

For evidence-bearing changes:

• Observed, derived, and inferred claims remain distinguishable.
• Artifact identity, source provenance, and failed attempts remain preserved.
• Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

• npm run test:focused over the 8 files that cover client configuration setup, including the Hermes and DeepSeek Harness acceptance and boundary tests: 227 tests passed.
• npm run check:fast: passed.
• npm run verify:test-discovery: "Discovered all 915 test files exactly once."

Compatibility, safety, and release

• Breaking changes or migration steps: none.
• Real Hopper/Ghidra, browser, or OS coverage: Linux x64 (Fedora 44) only. No real Hermes client was run.
• Package or release metadata impact: none.
• Security, privacy, process, or containment review: none. Only a YAML document with no root, or a bare ---, is newly accepted, as a document with no settings. An explicit null root is rejected as before.

Review checklist

• This PR addresses a concrete problem or an agreed enhancement.
• The PR has one focused outcome and the title follows type(scope): outcome.
• Related issue is linked, or the reason for not linking one is stated above.
• Tests cover changed observable behavior and meaningful failure paths.
• Owning docs, contracts, and generated metadata are updated where needed.
• User-visible CLI/MCP changes include representative output.
• I checked the final diff for secrets, unrelated cleanup, and unsupported claims.