> 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/phase40-session01-baseline-and-port-invariants/spec.md).

# Session Specification

**Session ID**: `phase40-session01-baseline-and-port-invariants` **Phase**: 40 - Claude OS v2.10.1 Semantic Port **Status**: Not Started **Created**: 2026-07-02 **Base Commit**: c7c58c3eb36b976ee05ae1e82837b194a88fbe99

***

## 1. Session Overview

This session opens Phase 40 by proving the Claude OS v2.9 through v2.10.1 semantic port has a stable baseline before feature implementation begins. The session rechecks the folded Phase 40 source record, upstream diff evidence, current AI OS Hermes ownership, existing tests, and non-negotiable privacy and control-plane boundaries.

The work is intentionally an audit and decision session. It should produce implementation notes that later sessions can cite when translating upstream model, provider, chat, command, Ministry, voice, asset, docs, and metadata behavior into AI OS owners.

No endpoint, UI feature, asset import, package metadata change, or docs claim should ship in this session. The important output is a clear invariant and classification record that prevents later sessions from copying upstream monolithic route or Vite middleware code into AI OS.

***

## 2. Objectives

1. Confirm upstream source evidence, patch scope, current git state, and focused Hermes test baselines before implementation sessions start.
2. Map the current AI OS Hermes route, component, hook, schema, public bridge, admin bridge, voice, graph, media, and demo ownership boundaries.
3. Classify upstream changes as direct translation, AI OS adaptation, intentional non-port, or already covered.
4. Record decisions and invariants for stderr diagnostics, live pricing, connection probes, voice key persistence, graph ignores, demo data, asset handling, package identity, and docs naming.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase39-session08-validation-and-documentation-hardening` - Completed Phase 39 and left the repository ready for the Phase 40 semantic port.

### Required Tools Or Knowledge

* Bun 1.3.14 package/runtime baseline.
* Folded Phase 40 source record in `.spec_system/PRD/phase_40/PRD_phase_40.md`.
* Session 01 stub in `.spec_system/PRD/phase_40/session_01_baseline_and_port_invariants.md`.
* Existing Hermes split architecture under `src/routes/agents.hermes.tsx`, `src/components/hermes/`, `src/hooks/`, `src/lib/`, `scripts/lib/hermes-dev-bridge.ts`, and `scripts/lib/hermes-admin-bridge.ts`.

### Environment Requirements

* Local repository checkout with dependencies installed or installable through `bun install`.
* Upstream checkout and v2.8.1-to-v2.10.1 patch named in the folded Phase 40 source record available locally.
* No credentials, third-party dashboards, or live provider access required.

***

## 4. Scope

### In Scope (MVP)

* AI OS maintainers get a baseline audit record covering upstream patch stat, name-status, changelog, cited Hermes snippets, current git status, and the planned implementation owner files.
* AI OS maintainers get a port invariant list for loopback, same-run token, public/demo, admin, chat SSE, graph, media, package identity, docs naming, and no-upstream-monolith-copy boundaries.
* AI OS maintainers get an upstream-change classification table that later sessions can cite before implementing models, redaction, chat, command, MoA, connection, catalog, pricing, assets, selector, compact, Ministry, voice, docs, and validation work.
* AI OS maintainers get focused baseline test outcomes for Hermes bridge, admin, hook, chat, voice, control-plane, sanitizer, and typecheck owners.

### Out Of Scope (Deferred)

* Implementing bridge endpoints, chat overrides, command execution, MoA save, Ministry UI, model selector, context meter, compact, or voice fixes - Reason: those are scoped to later Phase 40 sessions after this invariant record.
* Copying upstream `src/routes/agents.hermes.tsx` or Vite middleware into AI OS
  * Reason: Phase 40 requires semantic translation into current split owners.
* Importing or committing upstream assets - Reason: media work belongs to Session 10 after asset and vendor needs are finalized.
* Updating product/API docs beyond session artifacts - Reason: docs updates must wait until matching behavior is implemented and tested in Session 17.
* Changing package identity, graph ignore rules, or generated data behavior - Reason: this baseline only records decisions and evidence.

***

## 5. Technical Approach

### Architecture

Use the folded Phase 40 source record and session stubs as the source of port intent, then verify the current AI OS implementation owners before any feature change. `src/routes/agents.hermes.tsx` should remain a thin route shell; behavior belongs in Hermes components, hooks, schemas, public bridge, admin bridge, voice bridge, and tests.

The implementation output belongs in the session artifact directory. The main record should be `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md`, with a concise `IMPLEMENTATION_SUMMARY.md` for the handoff. Later sessions should be able to cite invariant IDs and classification rows instead of reopening the same port-boundary questions.

### Design Patterns

* Semantic port ledger: Record upstream behavior by AI OS owner and classification before implementation.
* Boundary-first review: Confirm local control-plane, demo, voice-secret, graph, media, package, and docs naming constraints before adding features.
* Existing owner mapping: Prefer current split Hermes files over copying upstream monolithic route or Vite middleware code.
* Evidence record: Capture commands, pass/fail outcomes, and exact local limitations without claiming unrun validation.

***

## 6. Deliverables

### Files To Create

| File                                                                                          | Purpose                                                                           | Est. Lines |
| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ---------- |
| `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md`   | Baseline audit notes, invariant list, decision list, and upstream classification. | \~180      |
| `.spec_system/specs/phase40-session01-baseline-and-port-invariants/IMPLEMENTATION_SUMMARY.md` | Concise Session 01 output summary and handoff index for later sessions.           | \~80       |

### Files To Modify

| File                                                                                        | Changes                                                            | Est. Lines |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------- |
| `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md`                | Mark completed tasks during implementation and final evidence.     | \~30       |
| `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` | Update with exact command outputs, decisions, and classifications. | \~180      |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Upstream diff, changelog, patch stat/name-status, and cited Hermes source snippets are reviewed and summarized without copying upstream monolithic files.
* [ ] Current AI OS Hermes route, component, hook, schema, bridge, voice, graph, media, package, demo, and docs boundaries are mapped to specific repo owners.
* [ ] Every material upstream change named in the folded Phase 40 source record is classified as direct translation, AI OS adaptation, intentional non-port, or already covered.
* [ ] Later sessions can cite explicit invariant or decision IDs for stderr `info` events, live pricing, connection probes, voice key persistence, graph ignores, demo data, asset handling, package identity, and docs naming.

### Testing Requirements

* [ ] Focused Hermes bridge, admin, hook, chat, voice, control-plane, sanitizer, and provider/readiness-adjacent tests pass or exact local failures are recorded.
* [ ] `bun run typecheck` and `bun run typecheck:scripts` pass or exact local failures are recorded.
* [ ] Session artifacts pass ASCII, LF, and diff whitespace checks.

### Non-Functional Requirements

* [ ] Session artifacts avoid raw credentials, bearer tokens, account-auth material, generated private data, logs, coverage, raw prompts, transcripts, and new raw private-path exposure.
* [ ] No user-facing route, Vite middleware, production source, package metadata, public demo fixture, or docs claim is changed in this baseline session.
* [ ] AI OS, Trend Finder, Hermes, Voice, and Intelligence naming boundaries remain aligned with current shipped behavior.

### Quality Gates

* [ ] All files ASCII-encoded
* [ ] Unix LF line endings
* [ ] Code follows project conventions
* [ ] No upstream monolithic route or Vite middleware file copied

***

## 8. Implementation Notes

### Working Assumptions

* Session 01 should create evidence artifacts, not production behavior: the session stub explicitly scopes implementation changes out and asks for baseline audit notes, invariants, decisions, and classifications. Planning can proceed because later Phase 40 sessions depend on these decisions before changing code.
* The upstream source inputs named in the folded Phase 40 source record are locally available: planning verified the upstream checkout directory and the v2.8.1-to-v2.10.1 patch file are present. Implementation can proceed without user arbitration because no credentials or remote service are required.

### Key Considerations

* \[P38] **Upstream ports are semantic, not wholesale**: Map hunks to AI OS module owners, record superseded or skipped upstream paths, and keep release reconciliation evidence.
* \[P38] **Local control-plane gates are defense in depth**: Preserve socket loopback, Host-header, token/admin, method, body-size, schema, timeout, and safe-error checks.
* \[P38] **OpenAI Realtime keys stay environment-only**: Voice broker credentials must never come from browser bodies, argv, docs, fixtures, or generated data.
* \[P31-P39] **Public-demo, AI Rogue, and hosted-surface gates stay bundled**: Run privacy, fixture, no-bridge, hosted metadata, asset, browser, and review gates when public, media, runtime, or authored-content changes occur.
* \[P00] **Stack conventions**: Bun, Vite 8, TanStack Start, React 19, Radix UI, and Cloudflare Worker compatibility remain baseline constraints.

### Potential Challenges

* Large upstream diff scope: Mitigate by classifying the named Phase 40 source record items first, then only sampling upstream hunks needed to verify owner mapping.
* Baseline tests may fail for pre-existing reasons: Record exact commands, output summaries, and whether failures are pre-existing rather than claiming success.
* Absolute upstream evidence paths already exist in the Phase 40 PRD: Avoid duplicating them unnecessarily in new artifacts and refer to the folded source record when possible.

***

## 9. Testing Strategy

### Unit Tests

* Run focused Vitest coverage for `scripts/lib/hermes-admin-bridge.ts`, `scripts/lib/hermes-dev-bridge.ts`, `src/hooks/use-hermes-admin.ts`, `src/components/hermes/chat/hermes-chat-tab.tsx`, `scripts/lib/voice-launch-bridge.ts`, `scripts/lib/local-control-plane-guard.ts`, and `scripts/lib/sanitize.ts`.

### Integration Tests

* Run `bun run typecheck` and `bun run typecheck:scripts` as baseline gates.
* Do not add browser or e2e requirements unless the baseline audit finds an already-owned Hermes route smoke that must be recorded.

### Runtime Verification

* Confirm current route shell and bridge registration points by source inspection rather than starting live Hermes or requiring provider credentials.

### Edge Cases

* Upstream checkout or patch missing during implementation: record the missing input as a blocker in implementation notes and stop without inventing port decisions.
* Dirty worktree before implementation: capture `git status --short` and avoid overwriting unrelated user changes.
* Sanitized diagnostics and command output: classify desired behavior without adding browser-visible diagnostics in this session.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase39-session08-validation-and-documentation-hardening`
* Depended by: `phase40-session02-models-and-provider-readiness`, `phase40-session03-shared-redaction-foundation`, `phase40-session04-chat-overrides-and-runtime`, `phase40-session07-connection-probe-parity`, `phase40-session10-assets-and-media-compliance`, `phase40-session16-voice-parity-and-broker-respawn`, and all later Phase 40 implementation and validation sessions that cite the invariant record.

***

## Next Steps

Run the `implement` workflow step to begin 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/phase40-session01-baseline-and-port-invariants/spec.md?ask=<question>&goal=<endgoal>
```

`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.