> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase20-session02-cleanup-parity-signoff/spec.md). # Session Specification **Session ID**: `phase20-session02-cleanup-parity-signoff` **Phase**: 20 - Hermes Long-Tail And Parity Sign-off **Status**: Not Started **Created**: 2026-06-02 *** ## 1. Session Overview This session closes the Hermes v2.3 port by auditing the completed Phase 16-20 surface against the Phase 16 endpoint, write-safety, and whole-port completion inventory. Session 01 already ported the remaining long-tail read-only sections; this session proves that the final route, bridge, hook, docs, demo mode, and tests are clean enough to sign off. The work is intentionally audit-first. Implementation changes should happen only where the audit finds confirmed dead scaffolding, raw fetch or polling bypasses, hook/admin contract drift, stale docs, or missing parity coverage. No new Hermes feature scope is added in this session. The final output is a sign-off record showing that every v2.3 Hermes feature is reachable from `/agents/hermes` or the global status pill, all local bridge reads and writes use the AI OS guardrails, docs describe implemented behavior only, and validation gates pass or leave documented residual gaps. *** ## 2. Objectives 1. Audit the current Hermes route, bridge, hook, demo, and docs surfaces against the Phase 16 whole-port inventory and Phase 20 session stub. 2. Remove confirmed dead Hermes scaffolding and fix any confirmed hook/admin bypasses without weakening local-only, token, loopback, or admin gates. 3. Update README and changelog documentation with the completed AI OS Hermes surface, `~/.hermes` layout, and final port record. 4. Produce implementation notes that capture endpoint parity, write-safety, demo-mode, test, bundle, and side-by-side visual parity evidence. *** ## 3. Prerequisites ### Required Sessions * [x] `phase16-session01-guardrails-architecture-parity-baseline` - Provides the v2.3 inventory and architecture decision. * [x] `phase16-session02-backend-endpoint-parity-write-safety` - Provides the bridge endpoint parity and write-safety contract. * [x] `phase16-session03-data-layer-demo-fixtures` - Provides typed hooks, parsers, validators, and demo fixtures. * [x] `phase17-session01-visual-system-shell-status-pill` - Provides the Hermes visual shell and global status affordance. * [x] `phase17-session02-chat-tab-write` - Provides admin-gated chat and image upload surfaces. * [x] `phase17-session03-pantheon-upgrade-write` - Provides Pantheon templates, persona writes, and sync surface. * [x] `phase18-session01-memory-upgrade-write` - Provides token-gated memory and Obsidian write surface. * [x] `phase18-session02-mnemosyne-constellation-readonly` - Provides the lazy-loaded read-only 3D view. * [x] `phase19-session01-mission-control-write` - Provides mission write surfaces. * [x] `phase19-session02-documents-gallery-write` - Provides document soft-delete, restore, and purge surfaces. * [x] `phase20-session01-connections-stats-long-tail` - Provides connections, stats, skills, sessions, roles, activity, and CLI surfaces. ### Required Tools/Knowledge * Bun project commands from `package.json`. * Phase 16 archived PRD at `.spec_system/archive/phases/phase_16/PRD_phase_16.md`. * Phase 20 PRD and session stub under `.spec_system/archive/phases/phase_20/`. * V23 source root at `/home/aiwithapex/projects/claudeos/claude-os-v2.3/`. * AI OS bridge and hook contracts in `scripts/lib/`, `src/hooks/`, and `src/components/hermes/`. ### Environment Requirements * AI OS repo checked out at `/home/aiwithapex/projects/aios`. * Optional v2.3 source checkout available for side-by-side visual/reference review. * No real Hermes installation is required for demo and mocked test coverage. * If live admin smoke checks are used, run them with a temporary `HERMES_HOME` and explicit `HERMES_DASHBOARD_ADMIN=1`; do not write to the default `~/.hermes` during closeout unless the operator explicitly chooses that. *** ## 4. Scope ### In Scope (MVP) * An AI OS maintainer can verify every v2.3 Hermes feature listed in the Phase 16 completion criteria is reachable from `/agents/hermes` or the global status pill - record the reachability matrix and fix any route composition gap. * An AI OS maintainer can verify the 5 read endpoints and 10 write endpoints from the Phase 16 inventory exist and remain gated - audit bridge code, hooks, tests, and docs, then fix any confirmed drift. * An AI OS maintainer can verify no raw fetch, polling, direct filesystem mutation, or client write bypasses the `useHermes` or `useHermesAdmin` layers * search, inspect, and fix any confirmed bypass. * An AI OS maintainer can verify docs describe the completed AI OS Hermes port and local `~/.hermes` layout without overclaiming future behavior - update README and changelog. * An AI OS maintainer can validate demo mode, focused tests, full quality gates, bundle budget, and side-by-side parity evidence - record exact commands and results in implementation notes. ### Out of Scope (Deferred) * New Hermes features beyond the v2.3 parity inventory - Reason: this is a closeout and sign-off session. * Rebranding AI OS back to Claude OS or making Hermes the entire product - Reason: AI OS host identity remains the product boundary. * Weakening loopback, token, admin, path-confinement, redaction, or confirmation safeguards to match v2.3 behavior - Reason: AI OS safety gates are the port contract. * Importing superseded `.png` or `.jpg` assets when AI OS already has optimized `.webp` versions - Reason: media policy and bundle budget remain active. * Running destructive live writes against default local Hermes data - Reason: closeout validation should use demo, mocks, or temporary `HERMES_HOME` unless the operator explicitly opts into live local writes. *** ## 5. Technical Approach ### Architecture Use an audit-first closeout workflow. Start with the Phase 16 whole-port inventory, then inspect the AI OS bridge modules, hook modules, Hermes route composition, tests, docs, and v2.3 references. Treat the current code as the source of truth for implementation details and the PRD/stub as the source of truth for scope. Read paths must remain owned by `useHermes` and bridge endpoints in `scripts/lib/hermes-dev-bridge.ts`. Write paths must remain owned by `useHermesAdmin` and `scripts/lib/hermes-admin-bridge.ts`, with `requirePreflight`, `confinePath`, bounded bodies, spawn-safe argv, confirmation, redaction, and query invalidation preserved. Component-level direct fetches are allowed only for the existing global status pill's coarse status affordance and document file access helper where the hook exposes that boundary. ### Design Patterns * Audit matrix: Convert the Phase 16 inventory into a concrete pass/fail matrix before making code changes. * Hook-owned runtime access: Keep React Query and hook-provided document access as the runtime data layer for browser components. * Admin boundary enforcement: Keep authorization closest to the write resource in the dev/admin bridge and duplicate-trigger prevention in the hook/UI layer. * Demo/live parity: Use bounded synthetic demo fixtures and mocked bridge tests so the page renders with no local bridge. * Documentation as evidence: README and changelog updates must describe implemented behavior only and cite residual gaps if any remain. ### Technology Stack * Bun 1.3.14 project runtime. * Vite 8 and TanStack Start for dev server and routing. * React 19 with TanStack React Query for local runtime reads and writes. * TypeScript 6, ESLint, Prettier, Vitest, Playwright, and bundle-budget script. * Local dev bridge modules under `scripts/lib/`. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------- | | `.spec_system/specs/phase20-session02-cleanup-parity-signoff/implementation-notes.md` | Audit matrix, changes made, command results, parity evidence, residual gaps | \~180 | | `.spec_system/specs/phase20-session02-cleanup-parity-signoff/security-compliance.md` | Final Hermes bridge safety and privacy sign-off notes | \~100 | ### Files to Modify | File | Changes | Est. Lines | | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------- | | `src/components/hermes/hermes-read-only-page.tsx` | Conditional route cleanup if confirmed stale scaffolding exists | \~20 | | `src/components/hermes/hermes-long-tail-data.ts` | Conditional stale constant or copy cleanup if confirmed unused | \~20 | | `scripts/lib/hermes-dev-bridge.ts` | Conditional read endpoint parity or gating correction if audit finds drift | \~30 | | `scripts/lib/hermes-admin-bridge.ts` | Conditional write-safety correction if audit finds drift | \~40 | | `src/hooks/use-hermes.ts` | Conditional read hook or polling ownership correction if audit finds drift | \~30 | | `src/hooks/use-hermes-admin.ts` | Conditional admin hook or invalidation correction if audit finds drift | \~30 | | `scripts/lib/__tests__/hermes-dev-bridge.test.ts` | Read endpoint, sensitive/public, traversal, and malformed response coverage | \~60 | | `scripts/lib/__tests__/hermes-admin-bridge.test.ts` | Write inventory safety, confirmation, spawn, traversal, and redaction coverage | \~80 | | `src/hooks/__tests__/use-hermes.test.tsx` | Sensitive-read token gating, demo no-bridge, public-read, and error-state coverage | \~50 | | `src/hooks/__tests__/use-hermes-admin.test.tsx` | Admin-disabled, token-failure, duplicate-trigger, and invalidation coverage | \~50 | | `src/components/hermes/__tests__/hermes-sections.test.tsx` | Full-tab reachability, demo/live parity, redacted feedback, and overflow-oriented coverage | \~60 | | `tests/e2e/hermes-agent.spec.ts` | Browser parity checks for all tabs, global status pill, demo mode, and text overflow | \~70 | | `README.md` | Completed Hermes surface and `~/.hermes` layout notes | \~40 | | `docs/CHANGELOG.md` | Final Hermes v2.3 port sign-off record | \~30 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Every v2.3 Hermes feature from the Phase 16 completion criteria is reachable from `/agents/hermes` or the global status pill. * [ ] The 5 read endpoints and 10 write endpoints from the Phase 16 inventory exist and are documented with the correct public/sensitive/admin gates. * [ ] No raw fetch, raw `setInterval`, direct filesystem mutation, or client write path bypasses `useHermes`, `useHermesAdmin`, or the bridge boundary. * [ ] Demo mode renders the entire Hermes page with no bridge running. * [ ] README and changelog describe the implemented Hermes port accurately and do not overclaim planned behavior. ### Testing Requirements * [ ] Focused Hermes bridge, hook, parser, component, and browser tests are updated or confirmed sufficient. * [ ] Unit tests and Playwright parity checks pass or have documented, actionable residual gaps. * [ ] Manual side-by-side v2.3 parity evidence is recorded when available. ### Non-Functional Requirements * [ ] Local-only Hermes reads and writes preserve loopback, token, admin, redaction, confirmation, and path-confinement boundaries. * [ ] Browser-visible output does not expose raw paths, prompts, command output, secrets, transcripts, or unbounded local content. * [ ] Bundle budget remains within the current limits: 1.2 MB total client JS gzip, 350 KB gzip per app chunk, 450 KB gzip per lazy vendor chunk, and 300 KB raw CSS. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `bun run typecheck` passes. * [ ] `bun run typecheck:scripts` passes. * [ ] `bun run lint` passes. * [ ] `bun run format:check` passes. * [ ] `bun run test` passes or any residual failures are documented as unrelated/actionable. * [ ] `bun run budget:check` passes after build artifacts exist. *** ## 8. Implementation Notes ### Key Considerations * The Phase 20 PRD points to `.spec_system/PRD/phase_16/PRD_phase_16.md`, but the current repo stores that reference under `.spec_system/archive/phases/phase_16/PRD_phase_16.md`. * Static searches for `fetch(` and `setInterval(` will include legitimate non-Hermes and hook-owned code. Record false positives instead of treating the raw search result as a bug. * The global status pill intentionally performs a coarse status read; it must stay token-free, read-only, and non-sensitive. * Document file access is exposed through `useHermes().documentFile`; component previews should use that hook-owned boundary rather than creating unrelated fetch paths. * Live admin validation should use a temporary `HERMES_HOME` if it writes files. ### Potential Challenges * Search noise from non-Hermes surfaces: Narrow follow-up inspection to `src/components/hermes/`, `src/hooks/use-hermes*.ts`, and `scripts/lib/hermes-*`. * Visual parity can be affected by AI OS branding and safer admin states: Compare functional reachability, layout stability, and state coverage rather than requiring v2.3's looser write model. * Existing tests may already cover a requirement: Record evidence and avoid adding duplicate tests unless a gap is real. * Bundle budget checks require build output: Run `bun run build` before `bun run budget:check` if no current dist exists. ### Relevant Considerations * \[P04] **Hermes bridge guardrails must stay intact**: This session explicitly audits loopback, token, admin, no-clobber path safety, and disabled-by-default admin mode. * \[P01] **Bundle budget watch on 3D vendor chunks**: Re-run the bundle budget after any cleanup or route composition change, especially around Mnemosyne. * \[P09] **Provider-neutral helpers should remain the single UI projection layer**: Do not reintroduce route-specific parsing where shared views already exist. * \[P18] **Lazy 3D surfaces must stay isolated**: Confirm 3D dependencies remain code-split and do not leak into the base Hermes route budget. * \[P19] **Remaining Hermes long-tail tabs should reuse the existing safety pattern**: Any closeout fix must preserve hook-layer polling, query invalidation, admin gating, and demo/live fixture parity. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * A closeout cleanup removes a live/demo state branch and collapses loading, empty, error, offline, or token-failure states into misleading empty UI. * A direct browser fetch, raw polling path, or duplicate write trigger bypasses the hook/admin safety layer. * Error or success feedback exposes local paths, prompts, tokens, command output, or raw Hermes content. * Side-by-side parity claims overstate behavior when AI OS intentionally keeps safer admin gates than v2.3. *** ## 9. Testing Strategy ### Unit Tests * Bridge tests for read endpoint sensitivity, admin write safeguards, path traversal rejection, confirmation requirements, spawn-safe argv, body bounds, redaction, and malformed payload handling. * Hook tests for demo no-bridge behavior, token-gated sensitive reads, public-read sequencing, admin-disabled states, duplicate-trigger prevention, and query invalidation after writes. * Component tests for all Hermes tabs, demo/live transitions, redacted feedback, empty/error/offline/token states, and long-text containment. ### Integration Tests * Playwright Hermes route coverage for all tabs, the global status pill, demo-mode rendering without bridge calls, mocked bridge live mode, and basic text/container overflow checks. ### Manual Testing * Compare AI OS `/agents/hermes` against the v2.3 source/reference for each Hermes inventory surface: status pill, overview, Chat, Mission, Documents, Mnemosyne, Memory, Pantheon, Connections, skills, sessions, roles, activity, stats, CLI, and setup guidance. ### Edge Cases * Missing Hermes install, offline browser, failed token handshake, malformed bridge response, empty sessions/skills/documents, admin disabled, admin gate open with token missing, write in-flight duplicate click, destructive action confirmation reset, unsafe document/trash ID, and long path-like error text. *** ## 10. Dependencies ### External Libraries * No new runtime dependencies are expected. * Existing stack: Bun, Vite, TanStack Start, React, React Query, Vitest, Playwright, and existing 3D lazy dependencies. ### Other Sessions * **Depends on**: Phases 16-19 complete and `phase20-session01-connections-stats-long-tail`. * **Depended by**: Final Hermes v2.3 parity certification and Phase 21 non-Hermes v2.3 migration work. *** ## Next Steps Run the implement workflow step to begin AI-led implementation. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase20-session02-cleanup-parity-signoff/spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.