> 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/phase25-session09-documentation-validation-release/spec.md).

# Session Specification

**Session ID**: `phase25-session09-documentation-validation-release` **Phase**: 25 - Hermes Mission Control Activation **Status**: Not Started **Created**: 2026-06-08

***

## 1. Session Overview

This session closes Phase 25 by reconciling the shipped Mission Control contract with the project documentation, security posture, and release validation evidence. Sessions 01 through 08 restored preview-to-commit mission writes, schema-versioned mission storage, safe planning prompts, multi-goal authoring, full-prompt execution briefings, active mission progress, archive reactivation, and Hermes/Claude Code responsive parity. The remaining work is to prove that the documented product and API contract match the implementation.

The session is intentionally documentation and certification focused. It should not add new product behavior, endpoints, mission schema fields, local-agent execution paths, or visual polish. The implementation work is to audit the source contract, update the authoritative docs, carry forward security and institutional memory, and run the full validation envelope needed to determine whether the Phase 25 binary outcome is YES.

The most important outcome is that an operator or future maintainer can read the docs and understand exactly how Mission Control works: the AI OS `/__hermes_missions` read envelope, `schema_version: 1`, optimize preview, commit activation, set-active reactivation, safe import/authorized snippet posture, admin gate requirements, demo/live behavior, and the ten expected UI states.

***

## 2. Objectives

1. Update final Mission Control documentation so agent-page, data-contract, and local API notes match the shipped Hermes and Claude Code contract.
2. Carry Phase 25 lessons into considerations and update the security posture for preview commit, set-active, authorized snippets, admin gates, and token redaction.
3. Run and record the full release validation envelope: tests, typecheck, script typecheck, lint, format or diff hygiene, build, e2e, accessibility, private-artifact checks, and security review.
4. Certify all ten Mission Control states and record a binary Phase 25 outcome with actionable blockers if any gate fails.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase25-session01-mission-write-contract-preview-commit` - provides the guarded mission writer, optimize preview, and commit activation model.
* [x] `phase25-session02-mission-schema-version-legacy-compatibility` - provides `schema_version: 1` normalization and legacy store compatibility.
* [x] `phase25-session03-safe-planning-prompt-authorized-write` - provides the safe planning prompt and authorized import/commit path.
* [x] `phase25-session04-multi-goal-authoring-preview-ui` - provides multi-goal authoring and optimized preview UI.
* [x] `phase25-session05-full-prompt-drawer-copy-briefings` - provides per-goal full prompts, `/goal` copy, and human briefing drawers.
* [x] `phase25-session06-active-mission-rail-progress` - provides active mission rail and progress behavior.
* [x] `phase25-session07-mission-archive-actions` - provides set-active archive reactivation.
* [x] `phase25-session08-claude-code-parity-responsive-e2e` - provides responsive Hermes and Claude Code parity evidence.

### Required Tools/Knowledge

* Bun 1.3.14 project toolchain.
* Existing package scripts in `package.json`.
* React 19, TypeScript 6, TanStack Query, Vite 8, Vitest, and Playwright.
* Current Mission Control source files: `src/hooks/use-hermes.ts`, `src/hooks/use-hermes-admin.ts`, `src/lib/hermes-types.ts`, `src/lib/hermes-admin-types.ts`, `src/components/hermes/hermes-mission-control.tsx`, and `scripts/lib/hermes-admin-bridge.ts`.
* Existing documentation conventions: document what exists, validate commands and paths before documenting them, and avoid planned-as-implemented claims.

### Environment Requirements

* Work from the repository root.
* No real Hermes credentials are required for automated e2e; mocked fixtures should cover browser states and bridge boundaries.
* Any live/manual check must avoid destructive writes unless it uses an isolated temporary Hermes home and records the isolation path generically.
* Generated private data, `.env*`, real tokens, logs, screenshots, traces, Playwright reports, and local mission files remain out of git.

***

## 4. Scope

### In Scope (MVP)

* Maintainers can rely on agent-page docs - update `/agents/hermes` and `/agents/claude-code` documentation with activated Mission Control behavior, ten UI states, demo/live boundaries, admin-ready/admin-disabled behavior, and Claude Code presentation parity.
* Maintainers can rely on data-contract docs - document the AI OS mission read envelope, `schema_version: 1`, legacy normalization, optimize preview, commit, set-active, and rejected raw v2.3 browser envelope.
* Maintainers can rely on local API notes - document `POST /__hermes_missions/commit` and `POST /__hermes_missions/set-active` along with create, optimize, tick, clear, request/response semantics, admin gates, duplicate-trigger posture, and redacted failure behavior.
* Future agents inherit accurate lessons - update considerations with Phase 25 patterns around hook reuse, admin-gated Mission Control writes, and final docs validation.
* Security reviewers get a current posture - update security/compliance for the new write surface, authorized commit/import snippets, set-active pointer writes, token redaction, demo/live separation, and lack of new third-party transfer.
* Release owners get evidence - record command output, all ten state checks, demo/live parity, accessibility review, security review, and binary phase outcome.

### Out of Scope (Deferred)

* New Mission Control functionality - Reason: Phase 25 implementation is complete; this session certifies it.
* New local-agent execution paths - Reason: Claude Code remains a presentation variant over existing Hermes hooks and bridge endpoints.
* New mission schema version or migration - Reason: Session 02 owns the current `schema_version: 1` compatibility contract.
* Live destructive smoke testing against a real Hermes home - Reason: release validation should not mutate operator data by default.
* PRD completion state changes - Reason: the `updateprd` workflow step owns final PRD/state completion after validation.

***

## 5. Technical Approach

### Architecture

Use the source contract as the authority, then update documentation and release evidence around it. The key browser read contract is `HermesMissionsBody` in `src/lib/hermes-types.ts`, served by the local dev bridge as `{ ok, active, mission, total, missions }`. The key admin write contract is `HermesMissionActions` in `src/hooks/use-hermes-admin.ts`, which posts to create, optimize, commit, tick, clear, and set-active endpoints through the existing hook-mediated admin path.

Documentation updates should describe current shipped behavior and explicitly separate it from unsupported behavior. Agent pages should explain route behavior and user-facing states. Data contract docs should explain payload shape, schema versioning, and compatibility. API notes should explain local dev endpoints, access controls, and request/response behavior.

Validation should use existing scripts and tests. Automated checks provide the primary evidence. Manual review fills the gaps for all ten UI states, accessibility, demo/live parity, token redaction, and security posture, with blockers recorded instead of hidden.

### Design Patterns

* Source-first docs: verify source and tests before updating prose.
* Current behavior only: remove or qualify stale endpoint names and planned claims.
* One boundary, two presentations: Hermes and Claude Code share hooks, contracts, admin gates, and differ only in presentation copy.
* Local admin gate preservation: every write requires loopback, per-run token, `HERMES_DASHBOARD_ADMIN=1`, non-demo mode, and hook-mediated calls.
* Bounded evidence: validation records statuses, counts, command names, and sanitized summaries, not real tokens, private paths, or generated data.
* Phase closeout discipline: if a gate fails, record an actionable blocker and avoid declaring the phase outcome YES.

### Technology Stack

* TypeScript 6.0.3.
* React 19.
* TanStack Query 5 through existing Hermes hooks.
* Vite 8 local dev middleware.
* Vitest 4.1.6 and Testing Library.
* Playwright 1.60.
* Bun 1.3.14 project scripts.

***

## 6. Deliverables

### Files to Create

| File                                                                                            | Purpose                                                                                                        | Est. Lines |
| ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------- |
| `.spec_system/specs/phase25-session09-documentation-validation-release/implementation-notes.md` | Command output, state matrix, documentation audit notes, blockers, and binary phase outcome.                   | \~160      |
| `.spec_system/specs/phase25-session09-documentation-validation-release/security-compliance.md`  | Session security review for Mission Control docs, write surface, authorized snippets, and validation evidence. | \~120      |

### Files to Modify

| File                                  | Changes                                                                                                                    | Est. Lines |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `docs/agent-pages.md`                 | Update Hermes and Claude Code Mission Control capabilities, states, admin-ready/admin-disabled behavior, and parity notes. | \~120      |
| `docs/data-contract.md`               | Update mission read/write contract, schema version, compatibility, optimize preview, commit, and set-active documentation. | \~120      |
| `docs/api/README_api.md`              | Update Hermes admin endpoint table and request/response notes for commit, set-active, admin gates, and redaction.          | \~140      |
| `.spec_system/CONSIDERATIONS.md`      | Carry forward Phase 25 lessons and any active concerns while staying within the line budget.                               | \~60       |
| `.spec_system/SECURITY-COMPLIANCE.md` | Update posture, data inventory notes if needed, and Phase 25 security/compliance certification.                            | \~120      |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Agent-page docs accurately describe activated Hermes and Claude Code Mission Control behavior.
* [ ] Data-contract docs accurately describe the AI OS mission read envelope, `schema_version: 1`, legacy compatibility, optimize preview, commit, and set-active behavior.
* [ ] Local API notes list all shipped Hermes mission admin endpoints: create, optimize, commit, tick, clear, and set-active.
* [ ] Docs clearly state that Claude Code adds no Claude-specific spawn, shell, git, workspace, or execution endpoint.
* [ ] Security docs reflect the current admin-gated write surface and token redaction posture.
* [ ] Considerations capture Phase 25 lessons without exceeding the file line budget.
* [ ] All ten Mission Control states are certified or have actionable blockers: idle, loading, success, empty, error, offline, token-failure, demo, admin-disabled, and admin-ready.
* [ ] Phase 25 binary outcome is recorded as YES only if release gates pass.

### Testing Requirements

* [ ] Full Vitest suite run and output recorded.
* [ ] App typecheck, script typecheck, lint, build, and diff hygiene run and output recorded.
* [ ] Playwright Hermes and Claude Code route checks run and output recorded.
* [ ] Private artifact, ASCII/LF, and documentation hygiene checks run and output recorded.
* [ ] Accessibility and demo/live parity review completed or blockers recorded.

### Non-Functional Requirements

* [ ] No new product code, endpoints, schema fields, dependencies, or local execution paths are introduced.
* [ ] Documentation is source-verified and does not describe planned behavior as shipped.
* [ ] Validation evidence does not expose real tokens, credentials, private paths, local mission file contents, screenshots, traces, or generated private runtime data.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code and docs follow project conventions.
* [ ] All required commands pass or blockers are recorded with owners and follow-up commands.

***

## 8. Implementation Notes

### Key Considerations

* The docs currently contain partial Mission Control contract coverage, but API notes still need the final commit and set-active endpoint details.
* The release record should explicitly say whether each failed command blocks the phase or is pre-existing drift outside the session scope.
* Avoid broad prose churn in long docs; update the narrow Mission Control sections and keep public Trend Finder boundaries separate from AI OS host agent pages.
* Treat `validation.md` as the validate workflow output; implementation should collect evidence in `implementation-notes.md` and `security-compliance.md`.

### Potential Challenges

* Full e2e runtime cost: Use focused Hermes and Claude Code route specs first, then run the full Playwright suite if time and environment allow; record any environment blocker precisely.
* Existing format drift: If `bun run format:check` fails on unrelated files, record the failure and run `git diff --check` plus ASCII/LF checks for session files.
* Live admin checks: Do not mutate a real Hermes home. Use tests and mocked e2e as primary evidence unless an isolated temporary home is available.
* Documentation staleness: Source files must win over older docs or v2.3 reference comments.

### Relevant Considerations

* \[P00] **Do not document planned features as implemented**: This session must reconcile docs to source behavior, not the folded reference backlog.
* \[P01] **Do not batch quality debt to final sessions**: Any final drift must be recorded as a blocker or scoped follow-up, not hidden.
* \[P04] **Hermes bridge guardrails must stay intact**: Docs and security review must preserve loopback, token, admin, no-clobber, and disabled-by-default write boundaries.
* \[P17] **Reuse existing hook contracts for write surfaces**: Mission Control docs should keep writes on `useHermesAdmin`, not component-level fetches.
* \[P20] **Long-tail Hermes surfaces stay modular and prop-driven**: Final docs should describe Mission Control without coupling unrelated Hermes sections.
* \[P23] **Hermes hook reuse for related agent routes**: Claude Code parity must remain presentation-only over shared Hermes contracts.

***

## 9. Testing Strategy

### Unit Tests

* Run `bun run test` for the full Vitest suite.
* If a failure appears, rerun focused Hermes suites such as `src/components/hermes/__tests__/hermes-mission-control.test.tsx`, `src/hooks/__tests__/use-hermes-admin.test.tsx`, `src/lib/__tests__/hermes-admin-types.test.ts`, and `src/routes/__tests__/agents.test.tsx` to isolate scope.

### Integration Tests

* Run `bun run typecheck`.
* Run `bun run typecheck:scripts`.
* Run `bun run lint`.
* Run `bun run build`.
* Run `bun run runtime:check`.
* Run `bun run budget:check` after a successful build.

### Browser And Accessibility Tests

* Run focused Playwright specs: `bunx playwright test tests/e2e/hermes-agent.spec.ts tests/e2e/claude-code-agent.spec.ts`.
* Run `bun run test:e2e` if the environment supports the full suite.
* Manually review or record automated evidence for focus order, named regions, keyboard access, copy buttons, drawer close behavior, no horizontal overflow, and the ten state matrix.

### Manual Testing

* Review `/agents/hermes` and `/agents/claude-code` docs against source and route tests.
* Verify demo mode cannot send writes.
* Verify admin-disabled and token-failure states are documented and tested.
* Verify commit and set-active docs match request bodies and response parsers.

### Edge Cases

* Missing local token.
* Offline browser.
* Admin disabled.
* Demo mode.
* Empty mission list.
* Malformed mission response.
* Optimize preview generated but not committed.
* Commit succeeds and activates the mission.
* Set-active target already active.
* Set-active target missing or rejected.

***

## 10. Dependencies

### External Libraries

* No new external libraries.

### Other Sessions

* **Depends on**: `phase25-session01-mission-write-contract-preview-commit`, `phase25-session02-mission-schema-version-legacy-compatibility`, `phase25-session03-safe-planning-prompt-authorized-write`, `phase25-session04-multi-goal-authoring-preview-ui`, `phase25-session05-full-prompt-drawer-copy-briefings`, `phase25-session06-active-mission-rail-progress`, `phase25-session07-mission-archive-actions`, `phase25-session08-claude-code-parity-responsive-e2e`.
* **Depended by**: Phase 25 validation, `updateprd`, and phase transition `audit` if the phase completes.

***

## 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/phase25-session09-documentation-validation-release/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.