> 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-session18-full-validation-and-handoff/spec.md). # Session Specification **Session ID**: `phase40-session18-full-validation-and-handoff` **Phase**: 40 - Claude OS v2.10.1 Semantic Port **Status**: Validated **Created**: 2026-07-03 **Base Commit**: dce1167502a2d9a260454524b7a01d3d24e8cb4d *** ## 1. Session Overview This session proves that the Phase 40 Claude OS v2.10.1 semantic port is ready for handoff. It does not add new product behavior. It runs focused Hermes, chat, command, MoA, Ministry, voice, parser, bridge, and control-plane checks, then runs broad repo validation, public/demo privacy gates, and manual smoke coverage for the shipped Phase 40 user paths. This is next because the analyzer reports Phase 40 sessions 01 through 17 are complete and the only unfinished Phase 40 candidate is Session 18. The session turns the completed port and Session 17 documentation closeout into explicit evidence: pass/fail command results, smoke outcomes, privacy status, staged-file safety, and bounded follow-up for any validation item that cannot run in the local environment. The handoff must preserve AI OS boundaries: upstream changes are semantic ports, Hermes writes remain local/admin-gated, voice provider secrets remain environment-only, public/demo output stays static and fixture-safe, and docs must describe shipped behavior rather than planned upstream behavior. *** ## 2. Objectives 1. Verify that all Phase 40 prerequisite sessions are complete and that the closeout scope matches the folded Phase 40 source record. 2. Run focused Hermes bridge, parser, hook, chat, command, MoA, Ministry, voice, redaction, and control-plane guard tests with recorded results. 3. Run broad repository validation, build, asset, privacy, demo, and dependency checks with pass/fail evidence and root-cause notes for any failure. 4. Smoke the shipped live and demo user paths for model selection, MoA presets, context meter, commands, compact flow, Ministry, MoA save, voice respawn, and redaction without exposing private data. 5. Produce final validation, manual smoke, and handoff artifacts that make any bounded follow-up explicit before `updateprd`. *** ## 3. Prerequisites ### Required Sessions * [x] `phase40-session01-baseline-and-port-invariants` through `phase40-session17-docs-metadata-and-gitignore-closeout` - Analyzer reports all prerequisite sessions complete and Session 18 is the only unfinished Phase 40 candidate. ### Required Tools Or Knowledge * Bun 1.3.14 and the repo scripts in `package.json`. * Vitest, Playwright, Vite, TypeScript, ESLint, markdownlint, Prettier, and shell validation scripts already configured in this repo. * Phase 40 closeout context in `.spec_system/PRD/phase_40/PRD_phase_40.md`, `docs/phase-40-port-closeout.md`, and Session 17 validation artifacts. ### Environment Requirements * Local filesystem access to the repo and generated-safe fixtures. * Browser smoke can use demo mode when live provider credentials are absent. * OpenAI Realtime or voice provider credentials are optional; missing live credentials must be recorded as environment-limited proof, not as a shipped live-provider claim. *** ## 4. Scope ### In Scope (MVP) * AI OS operator needs final Phase 40 validation evidence - run focused and broad checks and record exact commands, results, failures, and root causes. * AI OS operator needs smoke confidence in shipped Hermes flows - verify model selection, MoA presets, context meter, commands, compact flow, Ministry, MoA save, voice respawn, redaction, live mode, and demo mode. * AI OS maintainer needs privacy and source-control safety - scan staged and unstaged changes for generated private data, raw local paths, auth JSON paths, account material, logs, coverage, and secret-shaped strings. * AI OS maintainer needs a bounded handoff - create validation, smoke, and handoff artifacts that state what passed, what could not run, and what follow-up remains. ### Out Of Scope (Deferred) * New feature work - Reason: Session 18 is a validation and handoff session. * Porting intentionally skipped upstream browser provider-key persistence - Reason: Phase 40 keeps provider credentials environment-only. * Treating environment-limited checks as live-provider proof - Reason: the security record requires real target hosts or credentials before making live proof claims. * Marking Phase 40 complete in PRD/state - Reason: the `updateprd` workflow step owns completion after implementation, review, and validation. *** ## 5. Technical Approach ### Architecture Validation follows the current AI OS split Hermes architecture. Focused tests cover bridge modules under `scripts/lib/`, browser-safe parsers under `src/lib/`, hooks under `src/hooks/`, route and component behavior under `src/components/hermes/`, and browser smoke under `tests/e2e/`. The session creates only spec-system evidence artifacts unless validation exposes a defect that must be documented as bounded follow-up. ### Design Patterns * Evidence ledger: Record each command, result, and relevant output summary in the session validation log so later review does not depend on terminal scroll. * Environment-limited proof: Separate missing credential, missing browser, native host, or provider limits from product failures. * Privacy first scans: Run secret-shaped, private-path, generated-data, public demo, and runtime artifact checks before handoff. * Product-surface smoke: Verify user-facing Hermes and public/demo states, while keeping diagnostics in session artifacts rather than visible product copy. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/specs/phase40-session18-full-validation-and-handoff/implementation-notes.md` | Task log, command evidence, root causes, and running implementation summary | \~260 | | `.spec_system/specs/phase40-session18-full-validation-and-handoff/final-validation-log.md` | Final command matrix, focused and broad validation results, and privacy gate status | \~220 | | `.spec_system/specs/phase40-session18-full-validation-and-handoff/manual-smoke-checklist.md` | Manual live/demo smoke matrix for Hermes, Ministry, voice, redaction, and public/demo paths | \~180 | | `.spec_system/specs/phase40-session18-full-validation-and-handoff/final-handoff.md` | Phase 40 handoff summary, bounded follow-up, and merge-readiness notes | \~140 | ### Files To Modify | File | Changes | Est. Lines | | --------------------------------------------------------------------------- | ------------------------------------------------------ | ---------- | | `.spec_system/specs/phase40-session18-full-validation-and-handoff/tasks.md` | Mark tasks complete as validation evidence is recorded | \~24 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Focused Hermes bridge, parser, hook, chat, command, MoA, Ministry, voice, redaction, and control-plane tests run with recorded results. * [ ] Broad typecheck, script typecheck, lint, tests, build, asset, privacy, demo, and dependency gates run with recorded results. * [ ] Manual smoke checklist covers live mode, demo mode, model selection, MoA presets, context meter, commands, compact flow, Ministry, MoA save, voice respawn, and redaction. * [ ] Staged and unstaged changes are reviewed for generated private data, raw local paths, auth JSON paths, account material, logs, coverage, and secret-shaped strings. * [ ] Any failed or skipped validation item has root cause, impact, and bounded follow-up. ### Testing Requirements * [ ] Focused Vitest suites pass or failures are documented with root cause. * [ ] `bun run test` passes or failures are documented with root cause. * [ ] E2E smoke runs for Hermes and Intelligence paths where the environment supports browser execution. * [ ] Public/demo scan and bundle budget checks pass or failures are documented with root cause. ### Non-Functional Requirements * [ ] Validation artifacts contain no secrets, raw private paths, raw provider payloads, prompts, transcripts, or account-auth material. * [ ] Handoff distinguishes shipped behavior from environment-limited proof and intentionally not-ported upstream behavior. * [ ] Public/demo checks keep hosted output static and free of `/__*` bridge calls. ### Quality Gates * [ ] All files ASCII-encoded * [ ] Unix LF line endings * [ ] Code follows project conventions * [ ] Documentation describes current shipped behavior only * [ ] No generated private data is staged *** ## 8. Implementation Notes ### Working Assumptions * Session 18 is ready to plan: the analyzer reports current phase 40, `current_session: null`, and only `phase40-session18-full-validation-and-handoff` remains unfinished. Planning can proceed because the candidate prerequisite states sessions 01 through 17 must be complete, and the analyzer lists them as completed. * The session should create evidence artifacts rather than new product code: the Phase 40 PRD and candidate stub define this as validation and handoff, and both list new feature work as out of scope. This keeps the session inside the 2-4 hour contract. * Live voice proof can be environment-limited: security recommendations and the Session 18 stub allow bounded follow-up when validation cannot run, and OpenAI Realtime credentials must stay environment-only. ### Key Considerations * Do not turn harness or demo evidence into live-provider claims. * Do not expose local usernames, home-directory paths, auth JSON paths, provider payloads, command output, prompts, transcripts, or bearer tokens in artifacts. * Treat failures as evidence to classify, not as permission to silently skip a gate. ### Potential Challenges * Long-running validation commands: Run focused checks first, then broad checks, and record command durations and failure scope. * Browser or provider environment gaps: Record missing browser, missing credential, native-host, or provider limits separately from product defects. * Existing dirty worktree: Review changed/staged files without reverting user or pre-existing changes. ### Relevant Considerations * \[P38] **Upstream ports are semantic, not wholesale**: Validate AI OS owners and skipped upstream paths instead of claiming flat upstream copies. * \[P38] **Local control-plane gates are defense in depth**: Preserve loopback, Host-header, token/admin, method, body-size, schema, timeout, and safe-error evidence. * \[P38] **OpenAI Realtime keys stay environment-only**: Voice validation must not introduce browser-supplied or persisted provider keys. * \[P31-P39] **Public-demo, AI Rogue, and hosted-surface gates stay bundled**: Keep public/demo scans, no-bridge checks, hosted metadata, asset, and browser proof together when validating hosted or public output. *** ## 9. Testing Strategy ### Unit Tests * Run focused Vitest suites for Hermes admin bridge, dev bridge, connection probes, model helpers, model intelligence, voice launch, voice broker, parser contracts, hooks, chat controls, command actions, Ministry config, Ministry analytics, Ministry builder, and Intelligence portal behavior. ### Integration Tests * Run `bun run test`, `bun run typecheck`, `bun run typecheck:scripts`, and `bun run lint`. * Run Hermes and Intelligence Playwright smoke where browser execution is available. * Run public/demo build, scan, and budget checks to confirm static hosted output remains safe. ### Runtime Verification * Start the local app when needed and smoke `/agents/hermes` in demo and live modes for model selection, MoA preset send, context meter, slash commands, command menu, compact flow, Ministry builder, MoA save states, voice respawn states, and redacted failure output. ### Edge Cases * Missing admin token, missing admin gate, missing provider key, rejected browser provider config, local bridge timeout, command failure, MoA duplicate save trigger, demo-mode disabled writes, public-demo no-bridge assertion, and generated-private-data staging. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase40-session01-baseline-and-port-invariants` through `phase40-session17-docs-metadata-and-gitignore-closeout` * Depended by: Phase 40 `creview`, `validate`, and `updateprd` *** ## Next Steps Run the `updateprd` workflow step. Reason: implementation, review, and validation are complete; the session is ready to be marked complete in PRD/state. --- # 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-session18-full-validation-and-handoff/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.