> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase02-session03-hero-and-mission-workflow-completion/spec.md).

# Session Specification

**Session ID**: `phase02-session03-hero-and-mission-workflow-completion` **Phase**: 02 - Product Surface and 2D Battlefield Completion **Status**: Not Started **Created**: 2026-05-29 **Package**: apps/web **Package Stack**: React 18.3.1, Vite 6.4.2, TypeScript 5.9.3, Tailwind CSS 3.4.6, Zustand 4.5.4

***

## 1. Session Overview

This session completes the web cockpit workflow that starts with selecting a hero, narrows mission context, opens mission detail, and resolves pending permission or plan decisions. It builds on the Session 02 shell work by keeping visible controls, drawers, dialogs, and overlay entry points aligned with the same local-first product surface.

The work stays inside `apps/web` unless a genuine shared contract gap is found. Current protocol and server docs already define hero, mission, permission, and plan shapes, so this plan assumes no new protocol package work unless implementation proves otherwise.

The outcome should make live, replayed, seed, sparse, and empty data paths understandable without implying autonomous orchestration, inbound chat commands, hosted identity, or web-to-Worker federation. Permission and plan surfaces should explain the requester, action, rationale, pending state, and result while preventing duplicate user decisions.

***

## 2. Objectives

1. Keep hero and mission selection synchronized across roster cards, battlefield state, hero detail, mission log rows, mission detail, and existing analytics drilldowns.
2. Make mission filtering, hero scoping, empty states, and detail handoffs clear for live, replayed, synthetic, and sparse data.
3. Improve permission and plan context surfaces with accessible dialogs, pending or resolved states, duplicate-trigger prevention, and local-runtime boundary copy.
4. Add focused tests and package documentation for critical workflow paths without expanding into agent orchestration or deferred hosted surfaces.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase01-session07-runtime-contract-documentation` - Provides stable local runtime and API documentation.
* [x] `phase02-session01-product-surface-requirements-reconciliation` - Provides Phase 02 PRD, UX PRD, and product surface gap matrix.
* [x] `phase02-session02-cockpit-shell-and-navigation-cohesion` - Provides coherent shell controls, local-server state treatment, and War Room boundary copy.

### Required Tools/Knowledge

* Node.js 20 and npm workspace commands.
* React 18, Testing Library, happy-dom, Vitest, Tailwind CSS, and Zustand.
* Current `apps/web` workflow files: `HeroRoster.tsx`, `HeroCard.tsx`, `HeroDetailDrawer.tsx`, `MissionLog.tsx`, `MissionDetailDrawer.tsx`, `MissionTimeline.tsx`, `PermissionModal.tsx`, `PlanWorkpad.tsx`, and `useGameStore.ts`.
* Current local runtime behavior for `permission_response` and `plan_approval_response` in `docs/api/README_api.md`.

### Environment Requirements

* Dependencies installed from the workspace lockfile.
* Existing `apps/web` hero, mission, command, and shell tests can run before edits.
* Local server availability is optional; disconnected, seed-data, and empty-data workflow paths must be testable without a running server.

***

## 4. Scope

### In Scope (MVP)

* Developer can select a hero and inspect related missions consistently - Use shared workflow actions so mission openings preserve or revalidate hero context.
* Developer can filter missions and understand why rows are visible or empty - Add explicit active filter summary, hero-scope clearing, and empty-state copy.
* Developer can move from hero detail or mission log into mission detail without losing context - Align drawer handoffs and accessible labels.
* Developer can evaluate permission requests safely - Show requester, tool, rationale, expiry, pending state, and disable duplicate approve or deny triggers.
* Developer can evaluate generated plans safely - Show plan steps, prompt context, budget, pending state, and disable duplicate approve or reject triggers.
* Maintainer can verify workflow behavior - Add focused unit and component tests for selection sync, filters, drawer or dialog accessibility, and duplicate-response guards.

### Out of Scope (Deferred)

* Agent orchestration commands such as spawn, resume, stop, fork, handoff, or task queue management - Reason: Phase 03 owns orchestration.
* Inbound chat or webhook commands - Reason: Current adapters are outbound-only and need a later permission and audit model.
* Web-to-Worker War Room federation - Reason: Phase 05 owns real federation and participant relay.
* Battlefield state and interaction polish - Reason: Session 04 owns 2D battlefield interaction and reduced-motion validation.
* Settings, replay, notification, export, and scan UX redesign - Reason: Session 06 owns those detailed workflows.
* Hosted auth, hosted storage, analytics dashboards, public replay hosting, or hosted collaboration - Reason: Later phases own hosted-service guardrails.

***

## 5. Technical Approach

### Architecture

Keep the workflow source of truth in the existing Zustand game store. Add narrow workflow actions for opening hero and mission detail so callers can synchronize `selectedHeroId` and `selectedMissionId` through one path instead of duplicating local assumptions in each component.

Use a small pure helper module for workflow copy and state derivation. The helper should format selection labels, filter summaries, permission expiry state, plan step status, and empty-state reasons from existing protocol shapes. Components can stay focused on rendering while tests lock the workflow contract without broad app setup.

Permission and plan UI remains local-runtime UI, not orchestration. The web app can optimistically close resolved items after a local resolution event, but the user-facing state should prevent duplicate clicks and avoid implying inbound remote control or autonomous execution.

### Design Patterns

* Shared workflow actions: Keep hero and mission selection synchronized from roster, drawers, mission log, and analytics entries.
* Pure helper plus component tests: Make labels, empty-state reasons, pending states, and status copy testable without full app rendering.
* Controlled dialog state: Disable approve or reject actions while a local response is in-flight and reset that transient state when a new request or plan opens.
* Local-first copy at action boundaries: Explain permission and plan decisions as local runtime decisions without hosted account, federation, or remote command claims.

### Technology Stack

* React 18.3.1
* Vite 6.4.2
* TypeScript 5.9.3
* Tailwind CSS 3.4.6
* Zustand 4.5.4
* Vitest 4.1.7, Testing Library, happy-dom

***

## 6. Deliverables

### Files to Create

| File                                                                                                | Purpose                                                                     | Est. Lines |
| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------- |
| `.spec_system/specs/phase02-session03-hero-and-mission-workflow-completion/implementation-notes.md` | Implementation evidence, decisions, and validation notes                    | \~90       |
| `apps/web/src/lib/workflowContext.ts`                                                               | Pure workflow state, copy, and status helpers                               | \~180      |
| `apps/web/tests/workflowContext.test.ts`                                                            | Unit coverage for workflow helper decisions                                 | \~180      |
| `apps/web/tests/HeroMissionWorkflow.test.tsx`                                                       | Component coverage for selection, filter, and drawer handoff behavior       | \~220      |
| `apps/web/tests/PermissionModal.test.tsx`                                                           | Component coverage for permission context and duplicate-response prevention | \~170      |
| `apps/web/tests/PlanWorkpad.test.tsx`                                                               | Component coverage for plan context and duplicate-response prevention       | \~170      |
| `apps/web/tests/workflowFixtures.ts`                                                                | Shared workflow fixtures for focused web tests                              | \~140      |

### Files to Modify

| File                                              | Changes                                                                                                     | Est. Lines |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------- |
| `apps/web/src/store/useGameStore.ts`              | Add synchronized workflow actions and harden permission or plan resolution guards                           | \~120      |
| `apps/web/src/components/HeroCard.tsx`            | Add accessible selected state, active mission context, and shared hero opener                               | \~80       |
| `apps/web/src/components/HeroRoster.tsx`          | Add selected-scope summary and clear affordance for mission filtering context                               | \~70       |
| `apps/web/src/components/HeroDetailDrawer.tsx`    | Use shared mission opener for active and recent missions, improve empty and missing-data copy               | \~120      |
| `apps/web/src/components/MissionLog.tsx`          | Add active filter summary, hero-scope clear, deterministic empty states, and shared mission opener          | \~140      |
| `apps/web/src/components/MissionDetailDrawer.tsx` | Add hero context handoff, plan/status context, and missing metric fallbacks                                 | \~120      |
| `apps/web/src/components/MissionTimeline.tsx`     | Add text summary and accessible labels for mission-history context                                          | \~60       |
| `apps/web/src/components/PermissionModal.tsx`     | Add dialog semantics, expiry state, duplicate-trigger prevention, and result feedback                       | \~130      |
| `apps/web/src/components/PlanWorkpad.tsx`         | Add accessible drawer semantics, step status clarity, duplicate-trigger prevention, and local boundary copy | \~140      |
| `apps/web/src/components/Leaderboard.tsx`         | Route existing hero drilldown through shared workflow action and preserve selection context                 | \~30       |
| `apps/web/README_web.md`                          | Document completed hero, mission, permission, and plan workflow behavior                                    | \~45       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Selecting a hero from roster, battlefield, hero detail context, or analytics entry produces consistent `selectedHeroId` and visible selected state.
* [ ] Opening a mission from mission log or hero detail opens mission detail and revalidates the associated hero context.
* [ ] Mission filters expose active state, hero scope, tag scope, search scope, clear affordances, and useful empty-state copy.
* [ ] Mission detail shows prompt, state, hero, timing, tool usage, tokens, costs or fallback values, plan context, and redacted or bounded text surfaces without layout breakage.
* [ ] Permission and plan dialogs show requester, action, rationale, pending or expiry state, accepted or rejected outcome handling, and no duplicate decision triggers.

### Testing Requirements

* [ ] Unit tests cover workflow helper status, filter summary, permission expiry, and plan status decisions.
* [ ] Component tests cover hero-to-mission selection sync, mission filtering, drawer handoffs, permission dialog behavior, and plan workpad behavior.
* [ ] Existing hero, mission, keyboard, command, and shell tests remain passing.
* [ ] Manual workflow checks are recorded for live seed data, no-server state, empty collections, and replayed events.

### Non-Functional Requirements

* [ ] Local-first privacy posture is preserved; no hosted account, hosted storage, analytics, public replay, or federation claim is introduced.
* [ ] Interactive controls have accessible names, visible focus treatment, keyboard paths, and selected-state semantics.
* [ ] Reopenable drawers and dialogs reset or revalidate transient pending state on re-entry.
* [ ] User-facing errors and fallbacks avoid raw stack traces, tokens, provider errors, or broad absolute-path exposure.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Focused tests and `npm --workspace apps/web run typecheck` pass.

***

## 8. Implementation Notes

### Key Considerations

* `MissionLog` currently filters by `selectedHeroId`, but opening a mission does not consistently reselect its hero. A shared mission opener should fix that drift.
* `HeroCard` is a native button but does not yet expose a selected state through `aria-pressed` or a full accessible label with faction, state, and active mission context.
* `PermissionModal` and `PlanWorkpad` currently remove local pending items immediately. This session should keep duplicate-trigger guards and clear user feedback without pretending the web app owns orchestration.
* Existing analytics overlays already include some hero drilldowns. They should use the same selection helper when touched so context stays predictable.

### Potential Challenges

* Store action churn: Keep the new workflow actions narrow and avoid changing event ingest semantics.
* Drawer z-index and Escape behavior: Preserve current shell and overlay dismissal behavior while adding pending-state resets.
* Test setup repetition: Use a small shared fixture file for workflow tests instead of duplicating large hero and mission builders.
* Scope bleed into Session 04 or Session 06: Do not redesign battlefield interaction, replay, notification, export, or scan-root flows.

### Relevant Considerations

* \[P00-apps/web] **Responsive and accessibility debt**: This session must improve focus, labels, selected state, and non-overlap for workflow surfaces.
* \[P01] **Local-first boundary is architectural**: Hero, mission, permission, and plan surfaces must degrade cleanly without hosted services, API keys, or remote relays.
* \[P01] **Redaction is boundary-specific**: Mission detail, permission detail, and plan prompt surfaces should preserve the current local redaction posture and avoid broad data-transfer claims.
* \[P01-packages/protocol] **Protocol leads cross-package work**: If implementation discovers a required shared shape, add it in `packages/protocol` before web-specific use.
* \[P01] **Stable docs are the current contract**: Use README files, `docs/api/`, architecture, privacy, release, and legacy-consolidation docs as current truth.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Reopenable drawers and dialogs can keep stale selected hero, selected mission, or pending decision state after close and reopen.
* State-mutating approve or reject actions can be triggered twice by rapid clicks or repeated keyboard activation.
* Mission filters can hide all rows without explaining which filter or selected hero caused the empty state.
* Permission and plan surfaces can imply agent orchestration or remote collaboration that Phase 02 explicitly defers.

***

## 9. Testing Strategy

### Unit Tests

* Test workflow helper output for selected hero labels, selected mission labels, active filter summaries, empty-state reasons, permission expiry states, and plan task statuses.
* Test store workflow actions for hero selection, mission selection, missing mission handling, missing hero handling, duplicate permission resolution, and duplicate plan resolution.

### Integration Tests

* Render hero roster, mission log, hero detail, mission detail, permission modal, and plan workpad with seeded store data.
* Verify pointer and keyboard paths open the expected drawer or dialog, preserve or clear selection deliberately, and avoid duplicate state changes.
* Verify active filters and hero scope display clear, reversible state.

### Manual Testing

* Start the web app without the local server and confirm seed-data hero and mission workflows remain understandable.
* Select a hero from roster and battlefield, open recent missions, clear filters, and reopen drawers with keyboard and pointer paths.
* Trigger or seed permission and plan requests, then approve and reject once while confirming duplicate actions are disabled.

### Edge Cases

* Missing hero record for a mission.
* Selected hero with no missions.
* Mission with no tools, no summary, no ended timestamp, invalid timestamps, or missing metrics.
* Permission request with expired timestamp or missing hero.
* Plan with no tasks, mixed task states, large budget value, or repeated approve and reject attempts.
* Replayed events that reopen drawers after previous transient state was closed.

***

## 10. Dependencies

### External Libraries

* No new external libraries planned.

### Other Sessions

* **Depends on**: `phase02-session01-product-surface-requirements-reconciliation`, `phase02-session02-cockpit-shell-and-navigation-cohesion`
* **Depended by**: `phase02-session04-battlefield-state-and-interaction-polish`, `phase02-session06-settings-replay-notifications-and-scan-ux`, `phase02-session07-product-surface-validation-and-documentation-closeout`

***

## 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://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase02-session03-hero-and-mission-workflow-completion/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.