> 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/phases/phase_25/session_01_mission_write_contract_preview_commit.md).

# Session 01: Mission Write Contract Preview Commit

**Session ID**: `phase25-session01-mission-write-contract-preview-commit` **Status**: Completed **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Make Mission Control optimize semantics explicit by returning a non-persisted preview and adding a separate admin-gated commit path that persists and activates the mission.

***

## Scope

### In Scope (MVP)

* Reproduce the confirmed optimize silent-success bug with a failing bridge test.
* Update `scripts/lib/hermes-admin-bridge.ts` so optimize returns an explicit preview envelope and never writes `missions.json`.
* Add a commit endpoint that validates an optimized or authored mission and persists it as active through the existing mission store writer.
* Extend `src/lib/hermes-admin-types.ts` with commit request/response parsing and an optimize preview discriminator.
* Extend `src/hooks/use-hermes-admin.ts` with `commitMission` and split optimize preview state from active-mission invalidation.
* Update bridge inventory and preflight tests for the new write endpoint.

### Out of Scope

* Rendering optimized previews in the Mission Control UI.
* Adding mission schema version fields.
* Changing the admin preflight strength or write authorization model.

***

## Prerequisites

* [x] Phase 25 PRD reviewed.
* [x] Existing Phase 19 Mission Control write path understood.
* [x] Existing Hermes admin bridge and hook tests runnable.

***

## Deliverables

1. Optimize preview contract in the admin bridge and admin types.
2. Admin-gated commit endpoint and hook mutation.
3. Tests proving optimize does not persist and commit does persist.

***

## Success Criteria

* [x] Optimize never mutates `missions.json`.
* [x] Commit persists the mission and sets it active.
* [x] Commit is rejected when admin mode, token, loopback, or payload validation fails.
* [x] Focused bridge, type-parser, and admin-hook tests pass.

***

## Folded Comparison Detail

This section preserves the shared Phase 25 reference context and the complete S25-01 session detail from the folded Phase 25 comparison record. This stub is self-contained so the old ongoing-project document can be deleted without losing source anchors, implementation scope, build steps, or exit criteria.

### Source Project Reference Links

#### AI OS

* [Hermes route](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/routes/agents.hermes.tsx)
* [Hermes page shell](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/components/hermes/hermes-read-only-page.tsx)
* [Mission Control UI](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/components/hermes/hermes-mission-control.tsx)
* [Claude Code mission page](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/components/hermes/claude-code-mission-page.tsx)
* [Hermes read hook](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/hooks/use-hermes.ts)
* [Hermes admin hook](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/hooks/use-hermes-admin.ts)
* [Hermes read contracts](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/lib/hermes-types.ts)
* [Hermes admin contracts](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/lib/hermes-admin-types.ts)
* [Hermes read bridge](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/hermes-dev-bridge.ts)
* [Hermes admin bridge](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/hermes-admin-bridge.ts)
* [Hermes demo fixtures](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/lib/hermes-demo-data.ts)

#### Claude OS v2.3 Reference

* [Reference Hermes route](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/routes/agents.hermes.tsx)
* [Reference Mission Control component](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/components/hermes-mission-control.tsx)
* [Reference Vite middleware/endpoints](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/vite.config.ts)
* [Reference Documents Gallery](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/components/hermes-documents-gallery.tsx)
* [Reference Mnemosyne component](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/components/hermes-mnemosyne.tsx)
* [Reference README](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/README.md)
* [Reference CHANGELOG](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/CHANGELOG.md)

### Reference Source Map

Every session below carries a **Reference (v2.3)** line pointing at the exact reference code to mirror. Citations are relative to the reference root `v2.3/` = `/home/aiwithapex/projects/claudeos/claude-os-v2.3/`. Line numbers are the 2026-06-08 inspection snapshot - treat them as anchors and re-confirm before editing. The two reference files that matter for this plan:

* `v2.3/src/components/hermes-mission-control.tsx` - the entire Mission Control UI, planning prompt, per-card copy, briefing renderer, and goal rail. Key anchors: `Actor`/`Status`/`MiniGoal`/`Mission` types (265-286); endpoint contract comments (243-249); `LONG_PROMPT_BODY` (313-509); `buildLongPrompt` (511-523); `MissionControlAgent` (532); `refetch` GET (547-555); exact-decimal progress geometry (561-569); tick/clear fetches (610, 633); `EmptyPanel` + `copy()` + Copy-prompt button (783-944); `MissionBody` (945-1034); `estimateToPips` (1035-1073); `buildCopyText` incl. `/goal` safety net (1074-1128); `formatHumanBrief` + `HUMAN_BRIEF_LABELS` (1130-1196); `BriefingDrawer` (1209-1577); `MissionGoalRail` incl. progress bar + milestone ticks (1583-1987).
* `v2.3/vite.config.ts` - the local mission endpoints: GET `/__hermes_missions` (778-799), `optimize` (799-943), `create` (944-1050), `tick` (1051-1099), `clear` (1100-1124); `MISSIONS_FILE` (751).

Where a session has no reference, the capability has no v2.3 equivalent and is marked **Reference (v2.3): none - AI OS-new**; the AI OS contracts/bridges named in that session are the substrate to build on.

### Phase Outcome (binary)

`/agents/hermes` (and the Claude Code mission route) fully restore the v2.3 Mission Control orchestration loop - planning prompt, discovery-driven decomposition, multi-goal authoring, optimized preview -> commit, per-goal `/goal` and human-briefing copy, and archive management - on top of the AI OS typed-contract, admin-gated, tested architecture, with documentation and end-to-end validation. YES/NO at the end of the last session.

### Cross-Cutting Guardrails (every session must hold these)

These are the AI OS strengths the plan must preserve while adding v2.3 affordances. No session may regress them:

1. Admin-gate is never weakened. All writes keep requiring loopback + valid per-run `X-Claude-OS-Token` + `HERMES_DASHBOARD_ADMIN=1` + non-demo + hook-mediated path.
2. Typed contracts stay authoritative. New fields/endpoints get read/admin parsers that reject malformed payloads; no ad hoc JSON.
3. State machine stays explicit. idle / loading / success / empty / error / offline / token-failure / demo / admin-disabled / admin-ready all keep rendering and stay tested.
4. Errors stay bounded and redacted through the existing display helpers.
5. Reads use query invalidation, not polling or fetch bypasses.
6. Demo/live parity holds; demo mode never triggers a real write.
7. Both agent presentations (`hermes`, `claude-code`) stay at parity at the contract layer; differences remain presentation copy only.
8. Every new affordance ships with unit/component coverage in the same session; responsive/e2e coverage lands by S25-08.

### S25-01 - Mission Write Contract: Fix Optimize, Add Preview -> Commit Path

**Resolves:** Finding #3, Priority 1.1, Endpoint Comparison (optimize row), Suggested Target UX item 3 (contract half).

**Reference (v2.3):** `v2.3/vite.config.ts:778-799` (GET `/__hermes_missions` -> bare `{ mission | null }`), `:799-943` (optimize handler - token-gated, shells `hermes`, returns the mission), `:944-1050` (create handler - loopback-only, no token, persists as active: the persistence pattern optimize must adopt for commit), `:1051-1099` (tick), `:1100-1124` (clear). Component side: `v2.3/src/components/hermes-mission-control.tsx:243-249` (endpoint contract comments), `:547-555` (`refetch` GET), `:610-640` (tick/clear fetches). Note: v2.3 `create` persists immediately with no preview step - the preview -> commit split is AI OS-new, layered on top of this endpoint shape to preserve the admin gate.

**Objective.** Eliminate the confirmed optimize-write bug and replace ambiguous optimize semantics with an explicit two-step model: optimize returns a non-persisted candidate; a separate authorized commit persists it and sets it active.

**Scope (in).**

* `scripts/lib/hermes-admin-bridge.ts`: make `handleMissionOptimizeRequest` return an explicit preview envelope (`{ ok: true, preview: true, mission }`) that does not write the store. Add `handleMissionCommitRequest` (`POST /__hermes_missions/commit`) that validates an optimized/authored mission document and persists it as active via `writeMissionStore`, reusing the create validation and ID rules.
* `src/lib/hermes-admin-types.ts`: add `HermesMissionCommitRequest`, a `preview` discriminator on the optimize write body, and parsers that reject malformed payloads.
* `src/hooks/use-hermes-admin.ts`: split `optimizeMission` (returns preview, never invalidates as if active) from a new `commitMission`; keep mutation state, busy guards, and admin gating.

**Scope (out).** No UI rendering of the preview yet (S25-04). No schema version field yet (S25-02).

**Build steps.**

1. Reproduce the bug in a failing bridge test (optimize currently reports success without persisting).
2. Implement the preview return + the commit endpoint + path/ID confinement.
3. Wire the admin hook split and update existing optimize call sites to treat the result as a candidate.
4. Update bridge inventory/preflight tests for the new write endpoint.

**Exit criteria.**

* Optimize never mutates `missions.json`; commit persists and sets active.
* Commit requires the full admin preflight; rejected/again-tested when gate is off or token fails.
* `hermes-admin-bridge.test.ts`, `hermes-admin-types.test.ts`, and `use-hermes-admin.test.tsx` cover preview-vs-commit, persistence, and rejection paths and pass.

***


---

# 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/phases/phase_25/session_01_mission_write_contract_preview_commit.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.