> 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/phase19-session10-mission-artifacts/spec.md).

# Session Specification

**Session ID**: `phase19-session10-mission-artifacts` **Phase**: 19 - Orchestration Command Center Execution **Status**: Not Started **Created**: 2026-06-26 **Package**: null **Package Stack**: mixed

***

## 1. Session Overview

This session brings mission artifacts into the active Orchestration command center. It turns the existing scaffolded workpad, evidence, verification, and review-gate DTOs into usable server-owned records, write routes, event updates, and web detail surfaces tied to plans, tasks, queue entries, missions, and execution runs.

It is next because Phase 19 Sessions 04 through 06 completed the campaign, attention, permission, and executor registry foundations, and Session 09 completed the hero and lineage links that mission artifact records need. Session 10 can now add artifact metadata, progress chips, review decisions, verification retries, and attention triggers without skipping prerequisites.

The session keeps the local-first boundary intact. Broad Orchestration rows and panels show metadata, safe labels, links, counts, and bounded summaries only; raw evidence file contents, terminal output, diffs, prompts, transcripts, and hosted transfer remain out of scope.

***

## 2. Objectives

1. Add server-owned mission artifact behavior for workpads, evidence metadata, verification attempts, and review gates with revision checks, idempotency, and retry limits.
2. Wire local REST and WebSocket mutation paths for workpads, evidence, verification retry/skip, and review decisions with validated input and compact error envelopes.
3. Add a web Mission Artifacts panel and drawer details with progress chips, linked records, loading/empty/error/offline states, and product-facing copy only.
4. Cover manager behavior, routes, store reducers, UI rendering, and documentation updates with focused tests and validation commands.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase19-session04-campaign-workbench` - campaign and queue workbench controls
* [x] `phase19-session05-attention-and-permissions` - attention records and permission decision audit flow
* [x] `phase19-session06-executor-registry` - executor capability and run history boundaries
* [x] `phase19-session09-heroes-and-lineage` - mission graph and lineage roster links

### Required Tools Or Knowledge

* Node 26.2.0+ and npm workspaces
* Vitest root test runner
* Existing command-center protocol contracts in `packages/protocol/src/orchestrationCommandCenter.ts`
* Existing server command-center manager and route patterns
* Existing web command-center Zustand store and Orchestration components

### Environment Requirements

* Local workspace dependencies installed with `npm install`
* No database, hosted account, provider credential, War Room Worker, or remote executor required

***

## 4. Scope

### In Scope (MVP)

* Operators can see mission progress chips for objective count, verification state, elapsed time, token/cost estimate, line-change estimate, last tool family, stalls, and escalations - derived from safe command-center metadata.
* Operators can create and update workpad records, evidence artifact metadata, verification attempts, and review gates through local command-center routes with idempotency protection, transaction-like manager boundaries, and explicit error mapping.
* Operators can retry or skip verification and decide review gates with duplicate-trigger prevention, stale-revision handling, and bounded attention item creation for failed verification, stall, escalation, budget, and review states.
* Operators can inspect linked artifacts across plans, tasks, queue entries, missions, and execution runs in the web Orchestration surface with loading, empty, error, offline, and disconnected states.
* Tests cover manager metadata, route validation, verification retries, review transitions, attention creation, store event reducers, mission chips, and product-facing UI copy.

### Out Of Scope (Deferred)

* Raw evidence file content display - Reason: the Phase 19 stub explicitly excludes raw content in broad Orchestration rows and the privacy boundary blocks diffs, prompts, terminal output, transcripts, and file contents.
* Full Mission Control replacement - Reason: this session adds artifact metadata inside Orchestration details only.
* New protocol family redesign - Reason: Phase 19 Session 01 already added workpad, evidence, verification, review-gate, and update-event contracts; this session consumes them unless implementation finds a blocking parser defect.
* Cross-restart artifact blob storage - Reason: the current repo has no database configured and existing Phase 19 managers use local runtime state; persistent artifact storage needs a separate data retention and erasure design.
* Hosted transfer or external collaboration of artifacts - Reason: War Room, hosted services, and inbound channel claims remain separately gated.

***

## 5. Technical Approach

### Architecture

The server will keep mission artifact ownership inside the command-center manager boundary. A small mission artifact helper will derive safe progress chips, normalize links, enforce retry limits, and decide when artifact states should create attention items. The route layer will expose write routes for workpads and evidence, plus specific verification and review decision actions, using the existing validation and mutation response patterns.

The web app will consume the existing command-center snapshots and events through `orchestrationApi.ts` and `useGameStore.ts`. A dedicated Mission Artifacts panel will render the artifact families as product surfaces, with raw-content categories shown as blocked labels rather than displayed. Drawer details will add linked artifact context while preserving the existing focus, escape, and stale-selection behavior.

### Design Patterns

* Manager-owned state: keeps filtering, idempotency, revision checks, and WebSocket updates aligned in one boundary.
* Protocol-first consumption: uses existing shared DTO parsers before server and web behavior duplicate vocabulary.
* Pure normalization before store mutation: keeps malformed frames from blanking the cockpit.
* Product-surface UI: visible copy describes operator state and next actions, not debug internals.

***

## 6. Deliverables

### Files To Create

| File                                                              | Purpose                                                                                              | Est. Lines |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------- |
| `apps/server/src/lib/missionArtifacts.ts`                         | Safe mission artifact derivation, link normalization, retry policy, and attention trigger helpers    | \~220      |
| `apps/web/src/lib/missionArtifacts.ts`                            | Web view models for progress chips, linked records, safe summaries, and blocked payload labels       | \~180      |
| `apps/web/src/components/orchestration/MissionArtifactsPanel.tsx` | Product-facing artifact panel for workpads, evidence, verification, and review gates                 | \~260      |
| `apps/server/tests/commandCenterMissionArtifacts.test.ts`         | Manager and route coverage for artifact records, retries, review transitions, and attention creation | \~260      |
| `apps/web/tests/missionArtifacts.test.ts`                         | Web helper and store coverage for chips, links, reducer normalization, and raw evidence blocking     | \~200      |

### Files To Modify

| File                                                            | Changes                                                                                         | Est. Lines |
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------- |
| `apps/server/src/managers/orchestrationCommandCenter.ts`        | Add mission artifact write helpers, retry/skip/review decision behavior, and attention creation | \~160      |
| `apps/server/src/routes/commandCenter.ts`                       | Add workpad/evidence mutations and verification/review action routes                            | \~100      |
| `apps/server/src/lib/commandCenterValidation.ts`                | Add bounded parsers for artifact action bodies when existing parsers are insufficient           | \~80       |
| `apps/web/src/lib/orchestrationApi.ts`                          | Add artifact mutation clients with duplicate-trigger prevention while in-flight                 | \~130      |
| `apps/web/src/store/useGameStore.ts`                            | Reconcile artifact updates, linked review gates, and stale drawer selections                    | \~60       |
| `apps/web/src/components/orchestration/CommandCenterPanes.tsx`  | Wire the Mission Artifacts panel into Orchestration views                                       | \~70       |
| `apps/web/src/components/orchestration/OrchestrationDrawer.tsx` | Render linked artifact details without raw evidence content                                     | \~90       |
| `apps/web/tests/OrchestrationPanel.test.tsx`                    | Cover mission artifact panel UI states and product-facing copy                                  | \~180      |
| `apps/web/tests/commandCenterStore.test.ts`                     | Extend reducer coverage for artifact and review-gate event reconciliation                       | \~80       |
| `docs/api/README_api.md`                                        | Document artifact mutation routes, retry/skip, review decisions, and blocked raw content        | \~40       |
| `apps/server/README_server.md`                                  | Document server artifact ownership and route behavior                                           | \~30       |
| `apps/web/README_web.md`                                        | Document web artifact panel behavior and privacy boundary                                       | \~30       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Each plan or task can show linked workpad, evidence, verification history, and review state in Orchestration.
* [ ] Workpad and evidence write routes accept valid metadata, reject raw blocked payload fields, and emit compact command-center update frames.
* [ ] Verification retry and skip actions enforce retry limits, stale revisions, and duplicate-trigger protection.
* [ ] Review-gate decisions update review state, raise or resolve attention items, and do not run unsupported merge or executor behavior.
* [ ] Mission progress chips surface safe metadata and never show raw evidence contents.

### Testing Requirements

* [ ] Unit tests written and passing for server helper and manager behavior.
* [ ] REST/WebSocket route tests written and passing for artifact writes and review transitions.
* [ ] Web helper, store, and UI tests written and passing for artifact rendering and reducer behavior.
* [ ] Verification scenarios completed for loading, empty, offline, error, duplicate, stale revision, retry-limit, and blocked-payload states.

### Non-Functional Requirements

* [ ] Raw prompts, command bodies, diffs, terminal output, file contents, transcripts, tokens, secrets, broad absolute paths, logs, replay buffers, and export payloads stay blocked from broad artifact surfaces.
* [ ] Local-server routes keep validation, rate-limit inheritance, auth inheritance, compact errors, and no-store safe behavior where applicable.
* [ ] UI controls have accessible names, focus behavior, and keyboard support matching existing Orchestration components.

### Quality Gates

* [ ] All files ASCII-encoded
* [ ] Unix LF line endings
* [ ] Code follows project conventions
* [ ] Primary user-facing surfaces contain product-facing copy only
* [ ] Focused server and web tests pass
* [ ] Workspace typecheck passes
* [ ] Root format check passes

***

## 8. Implementation Notes

### Working Assumptions

* Cross-package session scope: The analysis script reports the selected candidate package as `null`, while the stub names `apps/server` and `apps/web`; planning can proceed with `Package: null` because the session intentionally spans both packages and all task paths are repo-root-relative.
* Existing protocol contracts are sufficient for the MVP: `packages/protocol/src/orchestrationCommandCenter.ts` already defines workpad, evidence, verification attempt, review-gate, REST list, parser, and WebSocket update shapes; planning can proceed by consuming those contracts instead of adding a protocol redesign.
* Durable artifact records mean manager-owned command-center records for the current local runtime: `CONVENTIONS.md` says no database is configured and current Phase 19 command-center state lives in server managers, so this session will not claim cross-restart artifact blob persistence.

### Conflict Resolutions

* Stub wording says "durable workpad records" while the current architecture has no database and existing command-center managers are in-memory. The chosen interpretation is revisioned, idempotent, manager-owned local records with safe metadata; raw artifact storage and persistent blob retention are deferred because they require retention and erasure design.
* The source study says execution is in scope for executor-ready families, while review gates include a merge action. The chosen interpretation is that review decisions can record approval and link to existing Git workbench execution metadata, but must not run unsupported merge behavior or imply remote/hosted execution.

### Key Considerations

* Workpad, evidence, verification, and review-gate records should share the existing command-center response envelope and WebSocket event style.
* Attention items created by this session must stay bounded to safe metadata and should reuse the existing attention decision path.
* Evidence artifacts should carry `sourcePath` or `sourceLabel` only when safe and repo-relative; raw files are never read for broad panel display.

### Potential Challenges

* Review and verification actions can race with WebSocket updates: use expected revisions and idempotency keys on each action.
* Artifact links can drift across plans, tasks, missions, queue entries, and runs: normalize target ids and labels in one helper before route handlers save records.
* The UI can become cluttered: keep progress chips compact and move detail rows into the drawer.

### Relevant Considerations

* \[P03] **Real executors remain unimplemented by design**: Merge and review actions must not bypass capability, permission, audit, and existing Git workbench boundaries.
* \[P03-packages/protocol] **Protocol leads cross-package work**: Consume existing protocol contracts and only add protocol changes if an implementation-blocking contract gap is proven.
* \[P03-apps/server] **Local server boundary must stay conservative**: New routes need validation, auth/rate-limit inheritance, compact error mapping, and safe unavailable behavior.
* \[P07] **Redaction is boundary-specific**: Evidence metadata must block raw prompts, command bodies, diffs, terminal output, file contents, transcripts, tokens, logs, replay buffers, and export payloads at each boundary.
* \[P18-apps/server] **Manager-owned persistence and snapshot emission**: Keep filtering, state, and broadcasts aligned behind one server manager boundary.
* \[P18-apps/web] **Pure normalization before store mutation**: Normalize artifact snapshots and event records before updating Zustand state.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Duplicate review, skip, retry, or artifact write actions could create conflicting audit state.
* Stale revisions or retry-limit races could let operators see incorrect review status.
* Raw evidence content or unsafe paths could leak into broad Orchestration views.
* Offline, disconnected, empty, loading, and malformed-event states could blank the artifact panel.

***

## 9. Testing Strategy

### Unit Tests

* Server helper tests for safe target links, progress chip derivation, retry-limit decisions, and blocked payload categories.
* Manager tests for idempotent workpad/evidence writes, stale revisions, verification retry/skip, review decisions, and attention item creation.
* Web helper tests for progress chip labels, linked record grouping, blocked raw-content labels, and deterministic ordering.

### Integration Tests

* REST route tests for `/command-center/workpads`, `/command-center/evidence`, `/command-center/verification`, verification retry/skip, `/command-center/review-gates`, and review decisions.
* WebSocket tests for `command_center_workpad_update`, `command_center_evidence_update`, and `command_center_verification_update` reconciliation.
* Orchestration panel tests for artifact panel rendering, drawer details, duplicate in-flight controls, and product-facing copy only.

### Runtime Verification

* Create sample workpad, evidence, verification, and review-gate records through local routes and confirm Orchestration shows safe metadata.
* Exercise duplicate idempotency keys, stale expected revisions, retry limit exceeded, skip verification, and review decision flows.
* Toggle disconnected/offline test states and confirm the artifact panel remains readable.

### Edge Cases

* Missing target record
* Evidence with blocked raw field names
* Absolute or traversal source paths
* Duplicate idempotency key
* Stale expected revision
* Review gate already decided
* Verification retry count exhausted
* Malformed WebSocket update
* Empty artifact collections

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase19-session04-campaign-workbench`, `phase19-session05-attention-and-permissions`, `phase19-session06-executor-registry`, `phase19-session09-heroes-and-lineage`
* Depended by: `phase19-session11-templates-and-planning-context`, `phase19-session12-terminal-and-containers`, `phase19-session13-collaboration-and-handoff`, `phase19-session15-metrics-and-notifications`, `phase19-session16-ergonomics-and-documentation`

***

## Next Steps

Run the `implement` workflow step to begin 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/phase19-session10-mission-artifacts/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.