> 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-session03-safe-planning-prompt-authorized-write/spec.md).

# Session Specification

**Session ID**: `phase25-session03-safe-planning-prompt-authorized-write` **Phase**: 25 - Hermes Mission Control Activation **Status**: Not Started **Created**: 2026-06-08

***

## 1. Session Overview

This session restores the long-form Mission Control planning prompt from the Phase 25 comparison record while adapting its final write step to AI OS safety rules. The v2.3 prompt is the product contract for discovery, mission decomposition, actor assignment, `full_prompt` authoring, and human briefing quality, but its tokenless curl write is explicitly not portable into AI OS.

The implementation should use the existing AI OS Mission Control architecture: route files stay thin, prompt copy lives behind the Hermes/Claude Code presentation model, writes flow through `useHermesAdmin`, and persisted missions go through the Session 01 `commitMission` bridge path. The chosen MVP safe write mechanism is a UI-mediated import flow: the operator copies the planning prompt, gets agent-authored mission JSON, pastes it into Mission Control, and commits it through the already authorized admin hook.

This keeps the admin gate unchanged. No copied prompt may instruct a tokenless POST, no browser-visible flow should expose a real token or token-shaped value, and demo/offline/admin-disabled/token-failure states must remain explicit.

***

## 2. Objectives

1. Replace the short Mission Control starter prompt with versioned long-form prompts for Hermes and Claude Code that preserve Appendix A planning rules.
2. Re-point the old v2.3 Step 4 away from tokenless curl and toward an AI OS UI-mediated import plus admin-gated `commitMission` flow.
3. Add an agent-authored mission import surface that validates pasted mission JSON, handles errors safely, and commits only when the admin gate is ready.
4. Prove prompt safety, token redaction, duplicate-submit prevention, parser rejection, and successful authorized commit with focused tests.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase25-session01-mission-write-contract-preview-commit` - provides the explicit optimize preview and admin-gated commit endpoint.
* [x] `phase25-session02-mission-schema-version-legacy-compatibility` - provides current mission schema normalization and legacy-safe mission documents.

### Required Tools/Knowledge

* Bun 1.3.14 project toolchain.
* Vitest and Testing Library for lib, component, hook, and bridge coverage.
* Phase 25 Appendix A planning-prompt anatomy, especially discovery, actor rules, `full_prompt`, `/goal` prefix, human briefing, and old Step 4.
* Existing `useHermesAdmin().missions.commitMission` behavior and its duplicate in-flight protection.
* Existing redaction helpers in Mission Control and admin bridge tests.

### Environment Requirements

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

***

## 4. Scope

### In Scope (MVP)

* Operators can copy a long-form planning prompt for Hermes or Claude Code - implement versioned prompt constants with the Appendix A discovery, decomposition, actor, mini-goal, `full_prompt`, `/goal` , and human briefing rules.
* Copied prompts describe an AI OS-safe final step - replace the old tokenless curl instruction with "return mission JSON for Mission Control import" or an equivalent UI-mediated admin flow.
* Operators can import agent-authored mission JSON - add a bounded text input or dialog that validates JSON before calling `commitMission`.
* Mission import uses the existing admin gate - route all persistence through `admin.missions.commitMission` with duplicate-trigger prevention, disabled states, state reset on close, and query invalidation on success.
* Browser-visible errors are bounded and redacted - token-shaped values, local paths, headers, and raw bridge details do not leak through import or commit failures.
* Hermes and Claude Code presentation parity holds - the contract is shared and only agent-facing copy differs.

### Out of Scope (Deferred)

* Multi-goal manual editor controls - Reason: Session 04 owns manual authoring and optimized preview UI.
* Per-card `full_prompt` drawers and copy buttons - Reason: Session 05 owns mini-goal execution affordances.
* Token-bearing curl snippet generation - Reason: the MVP uses UI-mediated import to avoid exposing a token in copied prompts or browser diagnostics.
* Weakening or bypassing admin preflight - Reason: the Phase 25 guardrail requires loopback, valid token, admin mode, non-demo mode, and hook-mediated writes.
* Full responsive/e2e parity sweep - Reason: Session 08 owns cross-route responsive hardening.

***

## 5. Technical Approach

### Architecture

Create a small mission-planning utility under `src/lib/` for the long-form prompt contract and import validation. The utility should expose agent-keyed prompt builders and a parser that accepts JSON shaped like `HermesMissionCreateRequest`, applies bounded validation, and returns a `HermesMissionCommitRequest` candidate for the existing admin hook.

Update `src/components/hermes/hermes-mission-control.tsx` to consume the prompt builder through the existing `MissionControlPresentation` path. The component should keep its current state machine and add a focused import surface in the Mission writes area or empty-state actions. The import flow should be explicitly disabled in demo mode, offline mode, admin-disabled mode, and token-failure mode through the same `canEdit` boundary as create, optimize, tick, and clear.

The admin bridge should not gain a tokenless endpoint. Bridge changes are not expected unless tests expose a real redaction or rejection gap in `/__hermes_missions/commit`. If such a gap exists, fix it at the existing admin boundary and document it in implementation notes.

### Design Patterns

* Contract constants: keep prompt text versioned and testable outside the large component.
* UI-mediated write: operator imports agent output and the browser hook commits through the current admin path.
* Boundary validation: parse and reject malformed mission JSON before mutation, then rely on bridge validation as the authoritative server boundary.
* Duplicate-trigger prevention: reuse mission mutation in-flight guards and keep controls disabled while import commit is pending.
* Redacted feedback: route import and commit failures through bounded display helpers.
* Presentation parity: Hermes and Claude Code copy share the mission contract and differ only in self-address and presentation labels.

### Technology Stack

* TypeScript 6.0.3.
* React 19.
* TanStack Query 5 via existing `useHermesAdmin` invalidation behavior.
* Tailwind CSS 4 and existing local component conventions.
* Vitest 4.1.6 and Testing Library for focused tests.

***

## 6. Deliverables

### Files to Create

| File                                                                                                 | Purpose                                                                      | Est. Lines |
| ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------- |
| `src/lib/hermes-mission-planning.ts`                                                                 | Versioned prompt builders and agent-authored mission JSON import validation. | \~220      |
| `src/lib/__tests__/hermes-mission-planning.test.ts`                                                  | Prompt safety and import parser coverage.                                    | \~180      |
| `.spec_system/specs/phase25-session03-safe-planning-prompt-authorized-write/implementation-notes.md` | Implementation decisions, command output, and no-snippet rationale.          | \~80       |
| `.spec_system/specs/phase25-session03-safe-planning-prompt-authorized-write/security-compliance.md`  | Session security and compliance review for prompt/import write surface.      | \~80       |

### Files to Modify

| File                                                              | Changes                                                                                                     | Est. Lines |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------- |
| `src/components/hermes/hermes-mission-control.tsx`                | Use long-form prompt copy and add agent mission import/commit UI.                                           | \~260      |
| `src/components/hermes/__tests__/hermes-mission-control.test.tsx` | Cover prompt copy, import validation, commit success, disabled states, duplicate submit, and redaction.     | \~260      |
| `scripts/lib/__tests__/hermes-admin-bridge.test.ts`               | Add commit-boundary regression tests for admin gate and redacted agent-authored payload failures if needed. | \~80       |
| `src/hooks/__tests__/use-hermes-admin.test.tsx`                   | Extend commit coverage only if component work exposes a hook contract gap.                                  | \~40       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Hermes and Claude Code copied prompts include the Appendix A planning contract: discovery, actor rules, mini-goal limits, `full_prompt` requirements, `/goal` prefix rule, and human briefing guidance.
* [ ] Copied prompts do not contain the old tokenless v2.3 curl endpoint or tell an agent to bypass AI OS admin gating.
* [ ] Agent-authored mission JSON can be pasted into Mission Control and committed through `admin.missions.commitMission` when writes are ready.
* [ ] Demo mode, offline mode, admin-disabled mode, token-failure mode, and duplicate in-flight submits prevent import commits.
* [ ] Invalid JSON, malformed mission candidates, too many goals, unsupported actors, and missing required fields produce bounded browser-visible errors.
* [ ] Import surfaces reset or revalidate state on re-entry.
* [ ] Token-shaped values, token headers, local paths, and raw bridge details do not appear in copied prompts, browser-visible errors, or test snapshots.

### Testing Requirements

* [ ] Prompt utility tests prove required Appendix A sections exist and unsafe tokenless instructions are absent.
* [ ] Import parser tests cover valid mission JSON, malformed JSON, missing mission fields, too many goals, bad actor/status values, and bounded length behavior.
* [ ] Component tests cover Hermes and Claude Code prompt copy, clipboard fallback, import commit success, disabled states, duplicate-trigger prevention, state reset, and redacted errors.
* [ ] Admin bridge regression tests prove the existing commit endpoint rejects unauthorized agent-authored writes and does not echo token material.

### Non-Functional Requirements

* [ ] Admin gate strength is unchanged; no new tokenless write endpoint or direct component-level fetch bypass appears.
* [ ] New UI remains dense, scannable, accessible, and consistent with existing Mission Control controls.
* [ ] Long prompt/import text wraps without forcing layout shift inside the current Mission Control surface.
* [ ] No new dependency is introduced for prompt parsing or mission import.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Focused tests pass.
* [ ] `bun run typecheck` passes.
* [ ] `bun run typecheck:scripts` passes if bridge tests or bridge code change.

***

## 8. Implementation Notes

### Key Considerations

* Appendix A includes a v2.3 rule that the model should use only curl and print no JSON. That exact rule must be adapted: AI OS should not copy tokenless curl behavior, and the MVP safe path requires operator-visible mission JSON for UI import.
* Keep prompt constants testable outside `hermes-mission-control.tsx`; the component is already large and should not absorb another long literal without a focused reason.
* The commit endpoint already enforces loopback, token, admin mode, body-size, schema validation, and atomic store writes. Do not add a parallel write path.
* Existing Session 02 schema normalization means the import parser can be strict enough for browser ergonomics while still letting the bridge remain authoritative.
* The Phase 25 UX source is mostly PRD-side; apply the existing dashboard conventions for dense operational UI rather than introducing a marketing or hero-like surface.

### Potential Challenges

* Long prompt maintainability: isolate the text in a utility and test required phrases instead of scattering assertions through component tests.
* Safe Step 4 wording: make the import workflow clear enough for agents without suggesting a tokenless POST or exposing implementation-specific secrets.
* Parser overlap with admin types: avoid broad refactors; add a focused import parser that returns existing request shapes.
* Disabled-state clarity: reuse existing admin gate copy so the new import flow does not create a second gate model.
* Redaction drift: test token/header/local-path examples through the same error display path that users see.

### Relevant Considerations

* \[P04] **Hermes bridge guardrails must stay intact**: All writes stay behind loopback, token, no-clobber path safety, and disabled-by-default admin mode.
* \[P17] **Reuse existing hook contracts for write surfaces**: Compose `useHermesAdmin` and `commitMission` instead of adding component-level fetches.
* \[P20] **Long-tail Hermes surfaces stay modular and prop-driven**: Keep prompt and import logic focused so future Mission Control sessions can build on it.
* \[P21] **Token material stays script-only**: Token-shaped strings and headers must not reach browser state, logs, generated output, or copied prompts.
* \[P23] **Hermes hook reuse for related agent routes**: Hermes and Claude Code presentations share contracts and differ only in presentation copy.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Copied prompts accidentally preserve v2.3 tokenless curl language.
* Agent-authored imports bypass or visually confuse the existing admin gate.
* Malformed JSON or bridge errors leak token-shaped values or local paths.
* Duplicate import submits create multiple active missions or stale feedback.
* Long prompt/import text causes cramped controls or inaccessible focus order.

***

## 9. Testing Strategy

### Unit Tests

* Test prompt builders for Hermes and Claude Code required sections, version metadata, agent-specific self-address, and absence of tokenless curl strings.
* Test mission import parsing for accepted candidates, malformed JSON, missing required fields, actor/status handling, goal count limits, and bounded errors.

### Integration Tests

* Component-test the import flow against a mocked `useHermesAdmin` view: disabled gates, happy-path commit, duplicate submit, state reset, query invalidation, and redacted error display.
* Extend admin bridge tests only where needed to prove commit preflight still rejects non-loopback, bad token, admin-disabled, oversized, and malformed agent-authored payloads.

### Manual Testing

* Open `/agents/hermes` and `/agents/claude-code` in live and demo modes.
* Copy the long planning prompt for each presentation and inspect that it does not mention tokenless writes or expose token placeholders.
* Paste a valid mission JSON candidate into the import surface with admin ready and confirm it commits, refreshes, and clears local import state.
* Repeat in demo/admin-disabled/token-failure states and confirm commit controls stay blocked.

### Edge Cases

* Empty clipboard/clipboard-denied copy fallback.
* JSON wrapped in markdown fences or with extra agent explanation.
* Mission JSON with more than 10 mini-goals.
* Agent goals missing literal `/goal` in `full_prompt`.
* Human goals with missing or too-short briefing text.
* Duplicate goal IDs or invalid mission IDs.
* Error strings containing `/home/...`, `X-Claude-OS-Token`, or long token-shaped values.

***

## 10. Dependencies

### External Libraries

* None new.

### Other Sessions

* **Depends on**: `phase25-session01-mission-write-contract-preview-commit`, `phase25-session02-mission-schema-version-legacy-compatibility`.
* **Depended by**: `phase25-session08-claude-code-parity-responsive-e2e`, `phase25-session09-documentation-validation-release`.
* **Sequencing note**: Session 04 and Session 05 may reuse the prompt/import utility and presentation copy, but they own manual authoring and per-card execution affordances.

***

## 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-session03-safe-planning-prompt-authorized-write/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.