> 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-session04-multi-goal-authoring-preview-ui/spec.md).

# Session Specification

**Session ID**: `phase25-session04-multi-goal-authoring-preview-ui` **Phase**: 25 - Hermes Mission Control Activation **Status**: Not Started **Created**: 2026-06-08

***

## 1. Session Overview

This session replaces the current one-goal Mission Control create form with a real multi-goal authoring editor. Operators should be able to build a bounded mission by hand with mixed Hermes/human mini-goals, per-goal done-when text, estimates, and optional `full_prompt` values while staying inside the finalized Phase 25 mission contract.

The session also finishes the optimize flow started in Session 01. Optimize already returns a non-persisted preview-shaped mission, but the UI currently only shows feedback. This session stores that candidate locally, renders it as an explicit preview, and requires the operator to either commit it through `admin.missions.commitMission` or discard it before it becomes active.

The implementation must preserve AI OS safety boundaries. Reads still come from `useHermes`, writes still flow through `useHermesAdmin`, demo/offline/admin gates remain explicit, and active mission refresh happens through query invalidation rather than raw bridge fetches or local active-state shortcuts.

***

## 2. Objectives

1. Replace single-goal manual mission creation with a 4-10 mini-goal authoring editor that supports mixed actors and optional `full_prompt` content.
2. Align manual title, outcome, deadline, goal count, actor, done-when, estimate, and full-prompt validation with the finalized mission contract.
3. Render optimize results as a local preview with mission metadata, actor split, mini-goals, commit, and discard controls.
4. Prove manual authoring, validation, preview, commit, discard, disabled gates, duplicate-trigger prevention, and query invalidation with focused tests.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase25-session01-mission-write-contract-preview-commit` - provides the optimize preview response and admin-gated `commitMission` endpoint.
* [x] `phase25-session02-mission-schema-version-legacy-compatibility` - provides schema-versioned mission normalization and legacy-compatible documents.
* [x] `phase25-session03-safe-planning-prompt-authorized-write` - provides the safe planning prompt and existing import-through-commit UI.

### Required Tools/Knowledge

* Bun 1.3.14 project toolchain.
* React 19, TypeScript 6, TanStack Query, and existing Hermes query keys.
* Testing Library and Vitest component-test conventions.
* Existing Mission Control state machine, presentation copy, and redaction helpers in `src/components/hermes/hermes-mission-control.tsx`.
* Finalized Mission Control authoring limits in `src/lib/hermes-mission-planning.ts`.

### Environment Requirements

* Work from the repository root.
* No live Hermes credentials are required; tests should use mocked admin actions.
* Generated private Hermes data, `.env*`, logs, real tokens, and local mission files remain out of git.

***

## 4. Scope

### In Scope (MVP)

* Operators can author manual multi-goal missions - add dynamic mini-goal rows with add/remove controls, actor selection, `done_when`, estimate, and optional `full_prompt` input.
* Manual authoring follows finalized bounds - enforce 4-10 mini-goals, 7-42 day deadlines, required title/outcome/goal title/done-when/estimate fields, and actor values restricted to `hermes` and `human`.
* Manual creation stays admin-gated - submit through `admin.missions.createMission` with duplicate-trigger prevention, disabled states, reset-on-close behavior, redacted errors, and mission query invalidation on success.
* Optimize and manual creation are visually separated - keep lightweight manual authoring, optimize-from-prompt, and import flows scannable inside Mission Control without nested card composition.
* Optimized missions enter preview state - show proposed title, binary outcome, deadline, actor split, mini-goals, and preview-specific commit/discard controls.
* Preview commit uses the existing hook path - call `admin.missions.commitMission` and refresh active mission state through query invalidation only.
* Empty state offers the three primary actions - copy planning prompt, optimize from prompt, and create manually.

### Out of Scope (Deferred)

* Per-goal active-card drawer and copy behavior - Reason: Session 05 owns `full_prompt` drawers, `/goal` copy, and human briefing rendering.
* Active mission rail and gradient progress presentation - Reason: Session 06 owns the rail, milestones, and visual hierarchy.
* Mission archive reactivation or delete actions - Reason: Session 07 owns archive actions.
* New bridge endpoints - Reason: Sessions 01 and 03 already provide the required create, optimize, import, and commit paths.
* Full responsive/e2e parity sweep - Reason: Session 08 owns cross-route responsive and e2e coverage.

***

## 5. Technical Approach

### Architecture

Add a focused authoring helper under `src/lib/` for manual draft defaults, validation, payload conversion, and preview projection. This keeps the large Mission Control component from absorbing all contract logic while matching the existing Session 03 pattern for planning/import utilities.

Update `src/components/hermes/hermes-mission-control.tsx` to consume that helper. Replace the existing single `CreateDraft` shape with a multi-goal draft, render row-level controls with stable keys, and keep reset behavior tied to form close, demo-mode changes, and agent presentation changes.

Optimize success should set a local `optimizedPreview` state instead of only showing feedback. The preview renderer should consume the returned mission document, derive actor split and sorted goals, and expose two actions: discard for local state reset and commit for `admin.missions.commitMission`. Commit success clears the preview and invalidates `HERMES_QUERY_KEYS.missions`; optimize success itself must not invalidate or silently activate a mission.

### Design Patterns

* Contract helper: keep mission limits and payload conversion testable outside the component.
* Hook-mediated writes: create and commit use existing admin actions only.
* Preview before persistence: optimize produces local candidate state, then commit persists explicitly.
* Duplicate-trigger prevention: combine component `busyAction` with existing admin hook in-flight guards.
* Reset on re-entry: manual, optimize, import, and preview state clear when their surfaces close or presentation context changes.
* Redacted feedback: all write failures pass through bounded display helpers.
* Presentation parity: Hermes and Claude Code share behavior and differ only in typed presentation copy.

### Technology Stack

* TypeScript 6.0.3.
* React 19.
* TanStack Query 5 through existing query keys and admin hook invalidation.
* Tailwind CSS 4 and existing Hermes page primitives.
* Vitest 4.1.6 and Testing Library.

***

## 6. Deliverables

### Files to Create

| File                                                                                           | Purpose                                                                                          | Est. Lines |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------- |
| `src/lib/hermes-mission-authoring.ts`                                                          | Manual authoring draft defaults, validation, payload conversion, and preview projection helpers. | \~220      |
| `src/lib/__tests__/hermes-mission-authoring.test.ts`                                           | Unit coverage for authoring limits, payload conversion, row behavior, and preview projection.    | \~180      |
| `.spec_system/specs/phase25-session04-multi-goal-authoring-preview-ui/implementation-notes.md` | Implementation decisions, command output, and known follow-ups.                                  | \~80       |
| `.spec_system/specs/phase25-session04-multi-goal-authoring-preview-ui/security-compliance.md`  | Session security review for authoring, preview, commit, and query refresh boundaries.            | \~80       |

### Files to Modify

| File                                                              | Changes                                                                                                                 | Est. Lines |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------- |
| `src/components/hermes/hermes-mission-control.tsx`                | Replace single-goal create form, add multi-goal editor, render optimized preview, and wire commit/discard.              | \~360      |
| `src/components/hermes/__tests__/hermes-mission-control.test.tsx` | Cover authoring rows, validation, preview render, commit, discard, disabled gates, duplicate submits, and invalidation. | \~320      |
| `src/lib/hermes-mission-planning.ts`                              | Export or reuse shared authoring limits only if needed to avoid drift with import validation.                           | \~20       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Operators can add and remove manual mini-goal rows while preserving a stable 4-10 goal count.
* [ ] Operators can set each mini-goal actor to `hermes` or `human`.
* [ ] Operators can provide per-goal title, `done_when`, estimate, and optional `full_prompt`.
* [ ] Manual creation rejects missing required fields, invalid actor values, out-of-range goal counts, and deadlines outside 7-42 days.
* [ ] Manual creation submits a `HermesMissionCreateRequest` with all mini-goals in deterministic order through `admin.missions.createMission`.
* [ ] Optimize renders a visible preview and does not invalidate or activate a mission until the operator commits.
* [ ] Preview commit calls `admin.missions.commitMission`, prevents duplicate triggers while pending, clears preview on success, and invalidates mission queries.
* [ ] Preview discard clears local preview state without bridge writes.
* [ ] Empty state exposes copy prompt, optimize from prompt, and create manually actions.
* [ ] No raw mission bridge fetches are introduced in the component.

### Testing Requirements

* [ ] Unit tests cover authoring draft defaults, add/remove bounds, validation errors, valid payload conversion, and preview actor-split projection.
* [ ] Component tests cover manual add/remove, actor selection, optional `full_prompt`, validation bounds, create payload, disabled gates, and duplicate-trigger prevention.
* [ ] Component tests cover optimize preview rendering, no invalidation on optimize, commit payload, query invalidation on commit, discard behavior, and reset on re-entry.
* [ ] Component tests confirm existing import, tick, clear, Hermes, and Claude Code presentation behavior still works.

### Non-Functional Requirements

* [ ] Admin gate strength is unchanged; writes remain loopback/token/admin-mode, non-demo, and hook-mediated.
* [ ] Mission reads refresh through TanStack Query invalidation only.
* [ ] UI remains dense, scannable, accessible, and consistent with Hermes Mission Control styling.
* [ ] Error feedback stays bounded and redacted for local paths, tokens, auth headers, and malformed bridge details.
* [ ] No new browser-visible secret, private path, or raw local file content is introduced.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Focused tests pass.
* [ ] `bun run typecheck` passes.
* [ ] `bun run lint` passes.

***

## 8. Implementation Notes

### Key Considerations

* The current component already has create, optimize, import, tick, clear, and refresh flows in one module. Keep the helper responsible for validation and projection so UI changes remain readable.
* The existing admin hook already prevents concurrent mission mutations. The UI should still disable relevant controls through `busyAction` to avoid repeated operator clicks.
* `commitMission` already invalidates missions in the hook, and the component has a local invalidation helper. The implementation should avoid replacing query invalidation with direct fetches or local active mission mutation.

### Potential Challenges

* Large component complexity: mitigate by moving draft validation/projection to `src/lib/hermes-mission-authoring.ts` and keeping row rendering focused.
* Validation drift with import flow: mitigate by reusing exported min/max goal and deadline constants or documenting any intentional manual-vs-import difference in implementation notes.
* Dense UI around create, optimize, import, active mission, and archive: mitigate by separating manual, optimize, import, preview, and active mission regions with existing Hermes primitives and compact headings.
* Preview and active mission both visible: mitigate with clear "Preview" labels, commit/discard controls, and no active-state mutation until query refresh.

### Relevant Considerations

* \[P04] **Hermes bridge guardrails must stay intact**: All writes must keep loopback, token, admin mode, non-demo mode, and hook-mediated paths.
* \[P17] **Reuse existing hook contracts for write surfaces**: Manual create and optimized commit should compose existing `useHermesAdmin` actions.
* \[P20] **Long-tail Hermes surfaces stay modular and prop-driven**: Keep Mission Control subviews focused and easy to test.
* \[P23] **Hermes hook reuse for related agent routes**: Hermes and Claude Code presentations should share the same contract behavior.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Duplicate manual create or preview commit while a mission mutation is pending.
* Preview silently acting like a persisted mission before explicit commit.
* Manual editor stale state surviving close, discard, demo-mode changes, or Hermes/Claude Code presentation changes.
* Contract drift between manual authoring, import validation, and bridge parsing.
* Disabled/demo/offline/token-failure states accidentally allowing a write.

***

## 9. Testing Strategy

### Unit Tests

* Test authoring draft defaults and stable row identifiers.
* Test add/remove lower and upper bounds.
* Test validation for required mission fields, required goal fields, actor values, deadline 7-42, and goal count 4-10.
* Test payload conversion preserves deterministic goal order and optional `full_prompt`.
* Test preview projection calculates actor counts and sorted goals.

### Integration Tests

* Component tests should use existing mocked `UseHermesAdminResult` fixtures.
* Test manual create submission payload and invalidation behavior.
* Test optimize preview render, commit, discard, duplicate-click prevention, and no invalidation on optimize success.
* Test admin-disabled, demo, offline, and token-failure gates.

### Manual Testing

* Open Mission Control with empty mission data.
* Open create manually, add 4 mixed-actor goals, submit, and verify success feedback plus refresh behavior.
* Open optimize from prompt, submit a prompt, verify preview appears, discard it, then repeat and commit it.
* Verify Hermes and Claude Code routes show equivalent behavior with only presentation copy changes.

### Edge Cases

* Removing goals down to the 4-goal minimum.
* Adding goals up to the 10-goal maximum.
* Closing and reopening create, optimize, import, and preview surfaces.
* Switching demo mode or `missionControlAgent` with dirty local drafts.
* Commit failure with local path, token-shaped, or header-shaped error text.
* Optimize returns null or malformed local action result.

***

## 10. Dependencies

### External Libraries

* React 19: component state and rendering.
* TanStack Query 5: mission query invalidation.
* Testing Library: component interaction coverage.
* Vitest 4.1.6: unit and component tests.
* lucide-react: icons already used in Mission Control controls.

### Internal Dependencies

* `src/components/hermes/hermes-mission-control.tsx` - primary UI surface.
* `src/hooks/use-hermes-admin.ts` - admin-gated create, optimize, commit, tick, and clear actions.
* `src/hooks/use-hermes.ts` - mission query keys and read state.
* `src/lib/hermes-admin-types.ts` - mission create, optimize, commit, and document contracts.
* `src/lib/hermes-mission-planning.ts` - finalized import goal and deadline limits.
* `src/components/hermes/__tests__/hermes-mission-control.test.tsx` - existing Mission Control behavior coverage.

### Other Sessions

* **Depends on**: Sessions 01, 02, and 03.
* **Enables**: Session 05 full-prompt drawers/copy, Session 06 active mission rail, Session 07 archive actions, and Session 08 Claude Code responsive/e2e parity.

***

## 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-session04-multi-goal-authoring-preview-ui/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.