> 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-session06-active-mission-rail-progress/spec.md). # Session Specification **Session ID**: `phase25-session06-active-mission-rail-progress` **Phase**: 25 - Hermes Mission Control Activation **Status**: Not Started **Created**: 2026-06-08 *** ## 1. Session Overview This session upgrades the active Mission Control view from a set of useful mini-goal cards into a focused execution surface. Sessions 04 and 05 already made multi-goal missions authorable and gave every goal actionable prompt or briefing copy. The next gap is hierarchy: the operator should immediately know which goal is current, how far the mission has advanced, and how to move through the work without losing the full scan view. The implementation adds a one-goal rail over the active mission, keeps the existing full mini-goal grid available below it, and replaces rounded progress geometry with exact-decimal fill math so the bar ends under the correct milestone tick. It ports the relevant v2.3 interaction ideas into the AI OS component structure rather than copying the reference file wholesale. This is presentation-only work. Mission documents, read contracts, admin write endpoints, tick/clear semantics, demo behavior, and Hermes/Claude Code contract parity stay unchanged. The session must preserve reduced-motion-safe confetti, route-scoped Hermes styling, bounded text, keyboard reachability, and focused component coverage. *** ## 2. Objectives 1. Add a one-goal-at-a-time active mission rail that spotlights the current actionable mini-goal while preserving scan access to every mini-goal. 2. Implement exact-decimal mission progress helpers and a milestone-aligned gradient progress bar whose visual fill is not rounded. 3. Add keyboard, scroll, responsive, and reduced-motion behavior for the rail without weakening existing detail, copy, tick, or clear actions. 4. Prove progress geometry, rail navigation, current-goal hierarchy, reduced-motion behavior, and Hermes/Claude Code parity with focused tests. *** ## 3. Prerequisites ### Required Sessions * [x] `phase25-session05-full-prompt-drawer-copy-briefings` - provides active mission cards, detail/copy affordances, and active mission prompt projection. ### Required Tools/Knowledge * Bun 1.3.14 project toolchain. * React 19, TypeScript 6, TanStack Query, Tailwind CSS 4, and local Hermes page primitives. * Existing `HermesMissionSummary` and `HermesMissionGoal` contracts. * Existing Mission Control copy, detail, tick, clear, confetti, and admin-gate behavior. * Testing Library and Vitest component-test conventions. * Route-scoped Hermes styling in `src/styles.css`. ### Environment Requirements * Work from the repository root. * No live Hermes credentials are required; tests should use mocked mission data and existing admin fixtures. * Generated private Hermes data, `.env*`, logs, real tokens, and local mission files remain out of git. *** ## 4. Scope ### In Scope (MVP) * Operators can see the current actionable mini-goal first - add a focused rail or stage over the active mission that defaults to the first queued goal and can move between goals. * Operators can still scan the complete mission - keep the existing full mini-goal grid available below the rail and do not remove detail/copy/tick actions from the grid. * Operators can trust progress geometry - calculate exact progress as `(done / total) * 100` for CSS fill width, round only display labels, and align milestone ticks at exact per-goal intervals. * Operators can navigate the rail by keyboard and pointer - include prev/next controls, direct goal selection, focus labels, and cleanup for any keydown, scroll, or resize listeners. * Operators with reduced-motion preferences receive static-safe presentation - disable flowing gradient animation and preserve the existing confetti guard. * Hermes and Claude Code routes share the same rail behavior - differences are presentation copy and actor labels only. ### Out of Scope (Deferred) * Contract changes - Reason: Session 06 is presentation-only and consumes the existing typed mission shape. * New write endpoints or changed write semantics - Reason: tick and clear stay on the existing admin hook. * Mission archive reactivation or set-active actions - Reason: Session 07 owns archive actions. * Route-wide responsive/e2e parity sweep - Reason: Session 08 owns responsive and e2e closeout; this session adds focused component coverage. * Documentation and release closeout - Reason: Session 09 owns final docs and validation release work. *** ## 5. Technical Approach ### Architecture Create a small pure progress helper under `src/lib/` for exact mission progress math, current-goal selection, and milestone projection. This keeps geometry rules testable outside React and prevents rounded display values from leaking into CSS widths. Create a focused `HermesMissionGoalRail` component under `src/components/hermes/`. It should receive sorted goals, actor labels, current mission context, and existing action callbacks from `HermesMissionControl`. The rail owns local focus/selection state, scroll bookkeeping, keyboard handlers, and presentational progress rendering. It should not fetch data, parse bridge payloads, call admin hooks directly, or duplicate prompt-copy builders. Update `src/components/hermes/hermes-mission-control.tsx` to render the rail above the existing full grid, pass the same detail/copy/tick callbacks used by goal cards, and keep Mission Metrics accurate with the new exact progress helper. Add route-scoped CSS in `src/styles.css` for the rail, progress fill, milestone ticks, scrollbar styling, responsive card sizing, and reduced-motion fallbacks. ### Design Patterns * Pure helper first: progress and current-goal selection stay deterministic and unit-testable. * Presentation component: the rail receives typed props and emits existing callbacks rather than touching query or admin state. * Shared action path: rail, grid, and detail sheet use the same copy, detail, and tick handlers. * Exact geometry: CSS fill width uses the exact decimal; only user-visible text rounds percentages. * Re-entry revalidation: the selected rail goal resets or revalidates when the active mission changes. * Cleanup-first effects: keydown, scroll, resize, or observer listeners are removed on scope exit. * Route-scoped styling: rail CSS stays under `.hermes-agent-route` and respects `.claude-code-agent-route` token overrides. ### Technology Stack * TypeScript 6.0.3. * React 19. * TanStack Query 5 through existing mission query invalidation. * Tailwind CSS 4 plus route-scoped CSS in `src/styles.css`. * Lucide React icons already present in the project. * Vitest 4.1.6 and Testing Library. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------- | | `src/lib/hermes-mission-progress.ts` | Exact mission progress math, milestone positions, display rounding, and current-goal selection helpers. | \~120 | | `src/lib/__tests__/hermes-mission-progress.test.ts` | Unit tests for exact decimal widths, milestone positions, empty missions, sorted goals, and current-goal selection. | \~140 | | `src/components/hermes/hermes-mission-goal-rail.tsx` | Focused active-goal rail with progress bar, goal navigation, existing actions, keyboard support, and responsive markup. | \~320 | | `.spec_system/specs/phase25-session06-active-mission-rail-progress/implementation-notes.md` | Implementation decisions, command output, manual checks, and known follow-ups. | \~80 | | `.spec_system/specs/phase25-session06-active-mission-rail-progress/security-compliance.md` | Session security review for presentation-only mission projection and unchanged admin-gated writes. | \~80 | ### Files to Modify | File | Changes | Est. Lines | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `src/components/hermes/hermes-mission-control.tsx` | Use exact progress helper, render the rail above the existing grid, pass existing action callbacks, and preserve detail/copy/tick/clear behavior. | \~220 | | `src/components/hermes/__tests__/hermes-mission-control.test.tsx` | Cover rail rendering, progress geometry, navigation, current-goal hierarchy, reduced-motion behavior, and Claude Code parity. | \~240 | | `src/styles.css` | Add route-scoped rail, progress, milestone, scrollbar, responsive, and reduced-motion styles. | \~120 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Active Mission Control renders a rail/focus surface above the full mini-goal grid. * [ ] The rail defaults to the first queued goal, or the final goal when every goal is done. * [ ] Operators can move through rail goals using prev/next controls and keyboard input without focus loss. * [ ] Rail cards expose the same detail, copy, and tick actions as the grid and keep duplicate-trigger prevention while actions are in flight. * [ ] The full mini-goal grid remains visible and scannable after the rail is added. * [ ] Progress fill uses exact decimal geometry and aligns with milestone ticks at representative ratios such as 1/3, 2/3, 1/4, and complete. * [ ] Display labels can round percentages, but CSS geometry does not use the rounded value. * [ ] Reduced-motion users do not receive flowing progress animation or motion-heavy effects. * [ ] Existing create, optimize, import, detail, copy, tick, clear, refresh, admin-gate, demo, error, offline, and token-failure behavior remains unchanged. ### Testing Requirements * [ ] Unit tests cover exact progress ratios, display labels, milestone tick positions, empty missions, all-done missions, and current-goal selection. * [ ] Component tests cover rail rendering above the grid. * [ ] Component tests cover progress geometry at representative completion ratios. * [ ] Component tests cover prev/next and keyboard navigation. * [ ] Component tests cover rail detail, copy, and tick actions using existing callbacks and duplicate-trigger prevention. * [ ] Component tests cover reduced-motion behavior and confetti staying gated. * [ ] Component tests cover Hermes and Claude Code presentation parity. ### Non-Functional Requirements * [ ] No new bridge endpoint, storage path, or mission contract field is introduced. * [ ] Admin gate strength is unchanged; tick/clear writes remain loopback, token, admin-mode, non-demo, and hook-mediated. * [ ] Browser-visible rail state contains no token, auth header, local path, or raw bridge error detail. * [ ] Rail CSS stays scoped to Hermes/Claude Code route skins. * [ ] UI remains dense, scannable, keyboard reachable, touch friendly, and consistent with the local-agent operator console. * [ ] Rail text wraps or truncates deliberately and cannot create document-level horizontal overflow on mobile or desktop. ### 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 existing `missionProgress` helper rounds its percentage. That is acceptable for labels but not for visual fill width. Add a helper that returns both exact and rounded values so the implementation cannot mix them. * The active rail should not replace the full grid. The session objective is a focused execution surface plus preserved scan mode. * `HermesMissionControl` is already large. Keep progress math and rail markup outside the file where practical, and preserve the existing handler boundaries for admin mutations and copy behavior. * The rail should use existing `GoalCard` behavior as a guide, but it can use a rail-specific presentational card if that keeps stage sizing and keyboard behavior simpler. ### Potential Challenges * Progress drift: Use exact helper values in CSS custom properties and assert the raw decimal in tests, not only visible text. * Keyboard conflicts: Ignore key handlers when focus is inside inputs, textareas, selects, buttons, or content-editable nodes unless the event originates inside the rail control. * Layout growth: Give the rail stage stable responsive dimensions and keep long titles/done-when text bounded with wrapping or line clamps. * Reduced-motion regressions: Put flowing-gradient animation behind route-scoped CSS and disable it through the existing `prefers-reduced-motion: reduce` media rules. ### Relevant Considerations * \[P04] **Hermes bridge guardrails must stay intact**: This session must not add bridge endpoints, bypass hooks, or weaken token/admin checks. * \[P20] **Long-tail Hermes surfaces stay modular and prop-driven**: The rail should be a focused prop-driven component rather than more ad hoc markup in the main Mission Control component. * \[P23] **Hermes hook reuse for related agent routes**: Hermes and Claude Code should share the rail behavior with presentation-label differences only. * \[P17] **Reuse existing hook contracts for write surfaces**: Rail tick actions must reuse existing `useHermesAdmin` callbacks through Mission Control. * \[P23] **Reduced-motion-safe CSS overlays**: Decorative animation should be disabled under reduced-motion preferences. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Progress labels passing while visual geometry is off by rounded percentages. * Rail keyboard shortcuts interfering with text entry or dialog controls. * Rail action buttons duplicating existing write/copy behavior and drifting from admin-gate, copy, and duplicate-trigger protections. * Motion-heavy progress effects ignoring reduced-motion preferences. * Adding a focus rail that hides or removes the full grid needed for scanning. *** ## 9. Testing Strategy ### Unit Tests * Test exact progress helper output for 0/0, 0/4, 1/3, 2/3, 3/4, and 4/4. * Test milestone tick positions for 3, 4, and 5 goal missions. * Test first queued goal selection, all-done fallback, and deterministic sort behavior. ### Integration Tests * Extend Mission Control component tests to render the rail with active mission fixtures. * Assert the rail appears before the full mini-goal grid and both surfaces expose expected actions. * Assert progress geometry values use exact percentages while labels use rounded percentages. * Assert rail prev/next and keyboard navigation update the focused goal. * Assert rail tick/copy/detail actions call the same admin and clipboard paths already covered for grid cards. * Assert Claude Code presentation labels remain correct through the shared component. ### Manual Testing * Run `/agents/hermes` and `/agents/claude-code` in demo and live-unavailable modes to inspect rail hierarchy, grid preservation, keyboard focus, and mobile wrapping. * Toggle reduced-motion in the browser or mock media query behavior to confirm progress animation stops and confetti remains gated. ### Edge Cases * Empty mission, null active mission, and all goals done. * One-goal mission with no milestone ticks. * Long mission titles, long goal titles, and long done-when text. * Rapid prev/next clicks, repeated tick/copy clicks while an action is in-flight, and mission changes while a rail goal is focused. * Offline, token-failure, demo mode, and admin-disabled states. *** ## 10. Dependencies ### External Libraries * None new. ### Internal Dependencies * `src/components/hermes/hermes-mission-control.tsx` * `src/components/hermes/hermes-mission-goal-detail.tsx` * `src/lib/hermes-types.ts` * `src/lib/hermes-mission-briefings.ts` * `src/hooks/use-hermes.ts` * `src/hooks/use-hermes-admin.ts` * `src/styles.css` ### Other Sessions * **Depends on**: `phase25-session05-full-prompt-drawer-copy-briefings` * **Depended by**: `phase25-session07-mission-archive-actions`, `phase25-session08-claude-code-parity-responsive-e2e`, `phase25-session09-documentation-validation-release` *** ## 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-session06-active-mission-rail-progress/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.