[PR #4145] [MERGED] docs(hermes): explain nested-home routing and preview limits #6085

Closed
opened 2026-10-31 01:11:43 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/4145
Author: @hichipli
Created: 10/15/2026
Status: ✅ Merged
Merged: 10/27/2026
Merged by: @morluto

Base: main ← Head: docs/hermes-nested-profile-selection


📝 Commits (6)

  • 7e2fea7 docs(hermes): clarify sticky profiles for nested homes
  • 8b54071 docs(hermes): qualify nested homes beneath default symlinks
  • 8c3e357 docs(hermes): cover canonicalized ancestor paths
  • 788bc16 docs(hermes): clarify both missing-path containment errors
  • e9b1018 docs(hermes): resolve upstream test imports
  • 474d3da docs(hermes): align nested-home guidance with current routing

📊 Changes

2 files changed (+240 additions, -11 deletions)

View changed files

📝 docs/client-configuration.md (+38 -9)
📝 tests/acceptance/setup/hermesClientSetup.test.ts (+202 -2)

📄 Description

Summary

Explain the destinations REA currently previews for nested Hermes homes, warn about a resolver-level difference with pinned Hermes, and cover the documented missing-directory workaround with compiled CLI tests. Refs #3939; this does not close it.

Problem and expected behavior

After main's resolver change in d1fbebb578, a nested HERMES_HOME=~/.hermes/sub with native active_profile=coder selects ~/.hermes/profiles/coder. This PR's previous revision described the older nested destination.

The guide should show the actual configuration and skill paths, explain why creating a missing override can change routing through symlinks, and avoid claiming full Hermes compatibility. At the guide's pinned Hermes commit 748c79a1, resolve_profile_env still resolves a named profile below the configured override.

Change and scope

Refresh against main 9140deae63; update the guide and public CLI acceptance cases to current REA routing. Add both missing-directory symlink controls, including before/after directory creation. Preserve the upstream named-user and existing profile lifecycle coverage. The shared CLI fixture formatting is already on main and drops out of this PR.

Production resolution is unchanged. A separate resolver compatibility decision remains in #3939; these tests describe current REA behavior rather than establish it as the desired upstream contract.

Follow the contribution scope.
Unresolved scope, authority, side effects, or required verification block
integration. Link the required maintainer scope decision for new providers or
capabilities involving target execution, injection, mutation, or protection
recovery; ordinary fixes within existing boundaries may state "not applicable".
Draft PRs may leave the scope decision pending and the readiness and merge checklists
unchecked. Maintainers can help resolve open questions.

Contract and boundary impact

  • Semantic owner and earliest changed stage: resolveHermesClientHome remains unchanged; this updates user guidance and compiled CLI acceptance coverage.
  • Contribution scope fit and linked maintainer decision: ordinary documentation/tests within existing boundaries; advance scope decision not applicable. Does not settle #3939's resolver contract.
  • CLI and MCP/tool-catalog contract: unchanged.
  • Provider, bridge, target-format, or platform compatibility: no production change; Windows junction behavior remains for CI to verify.
  • Evidence, artifact, provenance, or reconstruction contract: unchanged; dry runs assert fixture configuration, selection files, backups and skills remain untouched.
  • Target selection, authority, upstream behavior, and cleanup details (if applicable): tests use disposable homes and local REA CLI dry runs; no analysis target or provider is started.
  • Generated metadata (docs/public/product-catalog.json), package, or installation impact (CI generates and validates ignored catalogs and skills/; edit authored instructions in .agents/skills/reverse-engineer-anything/ and never commit build outputs): none.

Expected effects (check known effects; use documentation-only on its own).
Unchecked items do not establish absence; leave uncertainties visible.

  • Read existing files or captured data.
  • Launch or attach to a process.
  • Inject instrumentation or run scripts/code.
  • Change process memory, registers, files, or configuration.
  • Contact network services.
  • Recover protected code or work around protections.
  • Documentation or usability only; no target interaction.
  • Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

  • Tests added or updated: five nested-home cases (native profile missing, native only, both roots populated, no native selection, pre-created symlinked root), plus both missing-directory symlink directions before/after creation. Existing explicit-profile lifecycle coverage is retained.
  • Base reproduction or other evidence: current compiled REA CLI selects native profiles/coder when live, refuses when only the nested coder exists, uses the override without native selection, and bypasses sticky selection for explicit profiles. AST-extracted original Hermes resolver functions at 748c79a1 disagree on the first three named-profile layouts; they agree on no-selection and explicit-profile controls. This runs resolver functions, not a full installed Hermes CLI.
  • User-visible CLI/MCP output (if applicable): setup previews native profiles/coder/config.yaml and its skills/reverse-engineer-anything; a missing native profile returns needs_human with no planned/applied actions. Missing symlinked paths can preview a different root until the override directory exists, as documented.
  • Remaining proof gaps: full installed Hermes and other Hermes versions, Linux/Windows execution, and completion of the hosted compiled-test shards. Hosted Codex review returned an unknown service error on the automatic run and one manual retry; all existing inline threads are resolved. No real analysis-provider verification is claimed.

For boundary fixes, identify the applicable boundary regressions
and lifecycle regressions
covered by the evidence above, and explain relevant gaps.

This is documentation/current-behavior coverage: conflicting path selections and refusal remain visible across the public CLI, and dry runs preserve the fixture files. Existing setup/doctor/uninstall lifecycle cases remain intact.

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

Node 24.22.1 / npm 11.16.0, macOS arm64:

  • npm run test:focused -- tests/acceptance/setup/hermesClientSetup.test.ts tests/boundary/filesystem/hermesClientConfiguration.test.ts tests/boundary/filesystem/skillSelectionProvenance.test.ts tests/conformance/providers/managed/managedNativeVerification.test.ts — 101 passed: 23 CLI acceptance, 37 Hermes/skill boundary and 41 managed verification tests.
  • npm run check — passed typecheck, formatting, lint (0 errors), unused-code, metadata, module boundaries and architecture guards.
  • npm run docs:check — passed generated-document/license checks and 9 consistency tests.
  • npm run docs:build — VitePress build/render passed.
  • Pinned Hermes resolver / actual REA CLI comparison — five asserted layouts completed; three named-profile routing differences and two matching controls recorded above.
  • npm run verify:test-discovery — all 2,451 test files discovered exactly once.
  • Hosted checks at 474d3daba, checked 2026-10-24 23:16 UTC — PR title, readiness, static checks, package build, documentation and source tests passed; eight compiled-test shards are still running in CI run 40141466065. Greptile completed with no actionable findings.
  • git diff --check — passed.

Compatibility, safety, and release

  • Breaking changes or migration steps: none in this PR; existing main behavior is documented. Users can select a profile directly while #3939's compatibility decision remains open.
  • Real Hopper/Ghidra, browser, or OS coverage: actual compiled CLI on macOS; full installed Hermes and Windows/Linux execution unavailable. Providers/browser not applicable.
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: no runtime changes; isolated dry runs assert no configuration/skill writes. Both missing-path containment directions are documented and tested.

Author readiness

Human owner: @hichipli

On 2026-10-15, @hichipli confirmed review of the initially submitted diff, validation evidence and limitations, accepted responsibility, and explicitly declared this PR ready for initial maintainer review. Subsequent review fixes keep the description and validation current; the repository policy retains that initial readiness declaration.

  • I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
  • I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
  • I declare this PR ready for initial maintainer review.

Before merge

  • This PR addresses a concrete problem or an agreed enhancement.
  • Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
  • 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.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/4145 **Author:** [@hichipli](https://github.com/hichipli) **Created:** 10/15/2026 **Status:** ✅ Merged **Merged:** 10/27/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `docs/hermes-nested-profile-selection` --- ### 📝 Commits (6) - [`7e2fea7`](https://github.com/morluto/rea/commit/7e2fea7af9f1ef2714e30660c1decdfa05bfc402) docs(hermes): clarify sticky profiles for nested homes - [`8b54071`](https://github.com/morluto/rea/commit/8b5407130e4020261dc0f961ea9d3d56c328032b) docs(hermes): qualify nested homes beneath default symlinks - [`8c3e357`](https://github.com/morluto/rea/commit/8c3e3574801e27af458e02e41286448c03c1404c) docs(hermes): cover canonicalized ancestor paths - [`788bc16`](https://github.com/morluto/rea/commit/788bc164f75159f38d7da915d6cd5d26f6446f2f) docs(hermes): clarify both missing-path containment errors - [`e9b1018`](https://github.com/morluto/rea/commit/e9b1018760e7cd12157f8b4da352fca549cc08b4) docs(hermes): resolve upstream test imports - [`474d3da`](https://github.com/morluto/rea/commit/474d3daba53c0fd7ffa4f40ebf412bff8942e645) docs(hermes): align nested-home guidance with current routing ### 📊 Changes **2 files changed** (+240 additions, -11 deletions) <details> <summary>View changed files</summary> 📝 `docs/client-configuration.md` (+38 -9) 📝 `tests/acceptance/setup/hermesClientSetup.test.ts` (+202 -2) </details> ### 📄 Description ## Summary Explain the destinations REA currently previews for nested Hermes homes, warn about a resolver-level difference with pinned Hermes, and cover the documented missing-directory workaround with compiled CLI tests. Refs #3939; this does not close it. ## Problem and expected behavior After main's resolver change in d1fbebb578, a nested `HERMES_HOME=~/.hermes/sub` with native `active_profile=coder` selects `~/.hermes/profiles/coder`. This PR's previous revision described the older nested destination. The guide should show the actual configuration and skill paths, explain why creating a missing override can change routing through symlinks, and avoid claiming full Hermes compatibility. At the guide's pinned Hermes commit `748c79a1`, `resolve_profile_env` still resolves a named profile below the configured override. ## Change and scope Refresh against main `9140deae63`; update the guide and public CLI acceptance cases to current REA routing. Add both missing-directory symlink controls, including before/after directory creation. Preserve the upstream named-user and existing profile lifecycle coverage. The shared CLI fixture formatting is already on main and drops out of this PR. Production resolution is unchanged. A separate resolver compatibility decision remains in #3939; these tests describe current REA behavior rather than establish it as the desired upstream contract. Follow the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope). Unresolved scope, authority, side effects, or required verification block integration. Link the required maintainer scope decision for new providers or capabilities involving target execution, injection, mutation, or protection recovery; ordinary fixes within existing boundaries may state "not applicable". Draft PRs may leave the scope decision pending and the readiness and merge checklists unchecked. Maintainers can help resolve open questions. ## Contract and boundary impact - Semantic owner and earliest changed stage: `resolveHermesClientHome` remains unchanged; this updates user guidance and compiled CLI acceptance coverage. - Contribution scope fit and linked maintainer decision: ordinary documentation/tests within existing boundaries; advance scope decision not applicable. Does not settle #3939's resolver contract. - CLI and MCP/tool-catalog contract: unchanged. - Provider, bridge, target-format, or platform compatibility: no production change; Windows junction behavior remains for CI to verify. - Evidence, artifact, provenance, or reconstruction contract: unchanged; dry runs assert fixture configuration, selection files, backups and skills remain untouched. - Target selection, authority, upstream behavior, and cleanup details (if applicable): tests use disposable homes and local REA CLI dry runs; no analysis target or provider is started. - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact (CI generates and validates ignored catalogs and `skills/`; edit authored instructions in `.agents/skills/reverse-engineer-anything/` and never commit build outputs): none. Expected effects (check known effects; use documentation-only on its own). Unchecked items do not establish absence; leave uncertainties visible. - [ ] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [x] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: five nested-home cases (native profile missing, native only, both roots populated, no native selection, pre-created symlinked root), plus both missing-directory symlink directions before/after creation. Existing explicit-profile lifecycle coverage is retained. - Base reproduction or other evidence: current compiled REA CLI selects native `profiles/coder` when live, refuses when only the nested `coder` exists, uses the override without native selection, and bypasses sticky selection for explicit profiles. AST-extracted original Hermes resolver functions at `748c79a1` disagree on the first three named-profile layouts; they agree on no-selection and explicit-profile controls. This runs resolver functions, not a full installed Hermes CLI. - User-visible CLI/MCP output (if applicable): setup previews native `profiles/coder/config.yaml` and its `skills/reverse-engineer-anything`; a missing native profile returns `needs_human` with no planned/applied actions. Missing symlinked paths can preview a different root until the override directory exists, as documented. - Remaining proof gaps: full installed Hermes and other Hermes versions, Linux/Windows execution, and completion of the hosted compiled-test shards. Hosted Codex review returned an unknown service error on the automatic run and one manual retry; all existing inline threads are resolved. No real analysis-provider verification is claimed. For boundary fixes, identify the applicable [boundary regressions](https://github.com/morluto/rea/blob/main/docs/testing.md#boundary-regressions) and [lifecycle regressions](https://github.com/morluto/rea/blob/main/docs/testing.md#lifecycle-regressions) covered by the evidence above, and explain relevant gaps. This is documentation/current-behavior coverage: conflicting path selections and refusal remain visible across the public CLI, and dry runs preserve the fixture files. Existing setup/doctor/uninstall lifecycle cases remain intact. For evidence-bearing changes: - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed Node 24.22.1 / npm 11.16.0, macOS arm64: - `npm run test:focused -- tests/acceptance/setup/hermesClientSetup.test.ts tests/boundary/filesystem/hermesClientConfiguration.test.ts tests/boundary/filesystem/skillSelectionProvenance.test.ts tests/conformance/providers/managed/managedNativeVerification.test.ts` — 101 passed: 23 CLI acceptance, 37 Hermes/skill boundary and 41 managed verification tests. - `npm run check` — passed typecheck, formatting, lint (0 errors), unused-code, metadata, module boundaries and architecture guards. - `npm run docs:check` — passed generated-document/license checks and 9 consistency tests. - `npm run docs:build` — VitePress build/render passed. - Pinned Hermes resolver / actual REA CLI comparison — five asserted layouts completed; three named-profile routing differences and two matching controls recorded above. - `npm run verify:test-discovery` — all 2,451 test files discovered exactly once. - Hosted checks at `474d3daba`, checked 2026-10-24 23:16 UTC — PR title, readiness, static checks, package build, documentation and source tests passed; eight compiled-test shards are still running in [CI run 40141466065](https://github.com/morluto/rea/actions/runs/40141466065). Greptile completed with no actionable findings. - `git diff --check` — passed. ## Compatibility, safety, and release - Breaking changes or migration steps: none in this PR; existing main behavior is documented. Users can select a profile directly while #3939's compatibility decision remains open. - Real Hopper/Ghidra, browser, or OS coverage: actual compiled CLI on macOS; full installed Hermes and Windows/Linux execution unavailable. Providers/browser not applicable. - Package or release metadata impact: none. - Security, privacy, process, or containment review: no runtime changes; isolated dry runs assert no configuration/skill writes. Both missing-path containment directions are documented and tested. ## Author readiness Human owner: @hichipli On 2026-10-15, @hichipli confirmed review of the initially submitted diff, validation evidence and limitations, accepted responsibility, and explicitly declared this PR ready for initial maintainer review. Subsequent review fixes keep the description and validation current; the repository policy retains that initial readiness declaration. - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## Before merge - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
bsakaguchi 2026-10-31 01:11:43 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#6085
No description provided.