> 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/phase16-session01-guardrails-architecture-parity-baseline/spec.md). # Session Specification **Session ID**: `phase16-session01-guardrails-architecture-parity-baseline` **Phase**: 16 - Hermes v2.3 Port Foundation **Status**: Not Started **Created**: 2026-06-02 *** ## 1. Session Overview This session records the Phase 16 Hermes v2.3 port guardrails before any new endpoint, hook, data, or UI implementation lands. It confirms that the port will bring v2.3 features into the existing AI OS Hermes architecture instead of copying the v2.3 monolith, and it documents the information architecture for the expanded Hermes page. The session also snapshots the current AI OS Hermes parity baseline: the existing five-tab read-only page, the Hermes component tests, the admin type tests, and the bridge module extension points. This gives Sessions 02 and 03 a stable comparison record before endpoint parity and data-layer work begin. The output is a spec-system evidence artifact only. Production source code, bridge endpoints, hooks, types, demo fixtures, and visual shell changes remain out of scope for this session. *** ## 2. Objectives 1. Record the architecture decision: port v2.3 features into AI OS modules, not the v2.3 monolith. 2. Resolve the Phase 16 IA question by keeping the existing Tabs shell and planning top-level `Chat`, `Mission`, `Documents`, `Mnemosyne`, and `Connections` tabs. 3. Snapshot the current Hermes test and UI parity baseline before implementation begins. 4. Confirm the bridge, hook, type, and demo-data extension points that Sessions 02 and 03 must use. *** ## 3. Prerequisites ### Required Sessions * [x] `phase15-session01-scheduler-config-contract` - Scheduler config contract foundation is complete in spec-system state. * [x] `phase15-session02-live-data-merge-boundary` - Generated-data merge boundary is complete in spec-system state. * [x] `phase15-session03-aggregate-orchestration-refactor` - Aggregate orchestration extraction is complete in spec-system state. * [x] Phase 15 is marked `completed` by `analyze-project.sh --json`. ### Required Tools/Knowledge * Bun 1.3.14, Vitest, TypeScript, and the existing test scripts in `package.json`. * Phase 16 master reference: `.spec_system/PRD/phase_16/PRD_phase_16.md`. * v2.3 source root: `/home/aiwithapex/projects/claudeos/claude-os-v2.3/`. * Diff reference root: `/home/aiwithapex/projects/claudeos/diff-v1-v2.3/`. ### Environment Requirements * The AI OS repo is available at `/home/aiwithapex/projects/aios`. * The v2.3 source and diff roots are readable for inventory confirmation. * No dev server is required for this planning/baseline session. *** ## 4. Scope ### In Scope (MVP) * The operator can see a recorded architecture decision - capture feature parity, not file parity, and state that v2.3 features are decomposed into AI OS modules. * The operator can see a recorded IA decision - keep the existing Hermes Tabs shell and add planned top-level tabs rather than nested tabs or long-scroll. * The next implementation agent can compare against a parity baseline - snapshot the current five-tab read-only surface and the current Hermes test suite. * The next implementation agent can find safe extension points - document the dev bridge, admin bridge, hooks, types, demo-data, and test files that Session 02 and Session 03 must extend. ### Out of Scope (Deferred) * New read or write endpoints - *Reason: owned by Session 02.* * `confinePath` implementation and write security tests - *Reason: owned by Session 02.* * New hook queries, admin mutations, payload validators, or demo fixtures - *Reason: owned by Session 03.* * New tabs, visual shell, global status pill, Chat, Mission, Documents, Mnemosyne, or Connections UI - *Reason: owned by Phases 17-20.* * Production source code changes - *Reason: this session establishes the baseline before code changes.* *** ## 5. Technical Approach ### Architecture Use the Phase 16 PRD as the source of truth and record a concise session evidence artifact in `implementation-notes.md`. The artifact should preserve the architecture decision, IA decision, current five-tab surface, test baseline, bridge extension points, data-layer extension points, and source-to-session mapping. The evidence should reference existing AI OS modules instead of re-describing the v2.3 monolith as the implementation plan. Session 02 extends `scripts/lib/hermes-dev-bridge.ts` and `scripts/lib/hermes-admin-bridge.ts`. Session 03 extends `src/hooks/use-hermes.ts`, `src/hooks/use-hermes-admin.ts`, `src/lib/hermes-types.ts`, `src/lib/hermes-admin-types.ts`, and `src/lib/hermes-demo-data.ts`. ### Design Patterns * Evidence artifact: Keep baseline facts in the session implementation notes so later validation can audit exactly what was decided. * Read-only first: Preserve the existing Hermes read-only surface until write safety and data-layer work land. * Existing patterns over new abstractions: Reuse the current bridge, hook, type, demo-data, and test boundaries. * Security before UI: Record write-safety gates before any UI consumes new writes. ### Technology Stack * Bun 1.3.14. * React 19 with TanStack Router and React Query. * Vite 8 dev middleware for local bridge endpoints. * TypeScript 6.0.3 for application and script code. * Vitest 4.1.6 for focused baseline tests. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/specs/phase16-session01-guardrails-architecture-parity-baseline/implementation-notes.md` | Session evidence for architecture decision, IA decision, parity baseline, extension-point map, and validation results | \~180 | ### Files to Modify | File | Changes | Est. Lines | | ---- | --------------------------------------------------------------------- | ---------- | | None | No production source or PRD file changes are planned for this session | \~0 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Architecture decision is recorded and references the Phase 16 Core Decision. * [ ] IA decision is recorded with planned tabs `Chat`, `Mission`, `Documents`, `Mnemosyne`, and `Connections`. * [ ] Current five-tab Hermes read-only surface is snapshotted as the parity baseline. * [ ] Current Hermes test files and baseline commands are recorded. * [ ] Bridge, hook, type, admin type, and demo-data extension points are confirmed for Sessions 02 and 03. * [ ] No production source code is changed. ### Testing Requirements * [ ] Focused Hermes component, admin type, dev bridge, and admin bridge tests are run or explicitly documented if blocked. * [ ] `git diff --check` passes. * [ ] Session artifacts are ASCII-only. ### Non-Functional Requirements * [ ] Security guardrails stay intact: loopback checks, token gating, admin-mode writes, path confinement, redaction, and args-array spawn are documented as non-negotiable. * [ ] The plan preserves AI OS host identity and Hermes as a local-agent surface. * [ ] The evidence is concise enough for Session 02 and Session 03 agents to use without re-indexing the entire v2.3 source. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. *** ## 8. Implementation Notes ### Key Considerations * The analyzer reports Phase 16 as current with no active session and Session 01 as the first unfinished candidate. * Sessions 02 and 03 both depend on Session 01's baseline and decisions. * The existing `hermes-read-only-page.tsx` Tabs shell currently renders `Sessions`, `Memory`, `Pantheon`, `Skills`, and `Admin`. * The Phase 16 PRD states that AI OS already extracted bridge code into dev and admin modules; the implementation must extend those modules rather than re-inline bridge logic in `vite.config.ts`. ### Potential Challenges * Source anchors can drift after edits: Treat PRD line numbers as "start reading here" anchors and record current local observations in the notes. * Scope pressure toward endpoint work: Keep this session to evidence and baseline only; Session 02 owns endpoint parity. * Test command cost: Prefer focused Hermes baseline tests and record any blocked command with cause. ### Relevant Considerations * \[P04] **Hermes bridge guardrails must stay intact**: This session records the guardrails and names them as Session 02 merge gates. * \[P01] **Old `claude-os-*` naming in code identifiers**: Keep compatibility names such as `x-claude-os-token`; do not rename them in Phase 16 Session 01. * \[P01] **Bundle budget watch on 3D vendor chunks**: Mnemosyne is future Phase 18 work; the IA decision should not pull heavy 3D code into this foundation session. * \[P00] **Stack conventions**: Bun, Vite 8, TanStack Start, React 19, Radix UI, and Cloudflare Worker compatibility remain baseline constraints. *** ## 9. Testing Strategy ### Unit Tests * Run focused Hermes component baseline tests: `src/components/hermes/__tests__/hermes-sections.test.tsx`. * Run focused Hermes admin type parser tests: `src/lib/__tests__/hermes-admin-types.test.ts`. * Run focused bridge baseline tests: `scripts/lib/__tests__/hermes-dev-bridge.test.ts` and `scripts/lib/__tests__/hermes-admin-bridge.test.ts`. ### Integration Tests * No browser or endpoint integration test is required because this session does not modify runtime code. ### Manual Testing * Manually inspect the existing Tabs shell in `src/components/hermes/hermes-read-only-page.tsx` and record the current five tabs plus planned insertion points. ### Edge Cases * Missing v2.3 source root: Record the blocked source-root check and stop before claiming source inventory confirmation. * Existing tests fail before code changes: Record failures as baseline facts, not as Session 01 production fixes. * Uncommitted user changes: Do not revert unrelated work; record any conflicting Hermes edits if they affect the baseline. *** ## 10. Dependencies ### External Libraries * None added. ### Internal Dependencies * `.spec_system/PRD/phase_16/PRD_phase_16.md` * `.spec_system/PRD/phase_16/session_01_guardrails_architecture_parity_baseline.md` * `src/components/hermes/hermes-read-only-page.tsx` * `src/components/hermes/__tests__/hermes-sections.test.tsx` * `scripts/lib/hermes-dev-bridge.ts` * `scripts/lib/hermes-admin-bridge.ts` * `src/hooks/use-hermes.ts` * `src/hooks/use-hermes-admin.ts` * `src/lib/hermes-types.ts` * `src/lib/hermes-admin-types.ts` * `src/lib/hermes-demo-data.ts` ### Other Sessions * **Depends on**: Phase 15 completed in analyzer state. * **Depended by**: `phase16-session02-backend-endpoint-parity-write-safety`, `phase16-session03-data-layer-demo-fixtures`, and later Hermes port phases. *** ## 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/phase16-session01-guardrails-architecture-parity-baseline/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.