> 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/phase01-session01-event-ingest-contract-reconciliation/tasks.md).

# Task Checklist

**Session ID**: `phase01-session01-event-ingest-contract-reconciliation` **Total Tasks**: 24 **Estimated Duration**: 3-4 hours **Created**: 2026-05-29

***

## Legend

* `[x]` = Completed
* `[ ]` = Pending
* `[P]` = Parallelizable (can run with other \[P] tasks)
* `[SNNMM]` = Session reference (NN=phase number, MM=session number)
* `TNNN` = Task ID

***

## Progress Summary

| Category       | Total  | Done   | Remaining |
| -------------- | ------ | ------ | --------- |
| Setup          | 3      | 3      | 0         |
| Foundation     | 6      | 6      | 0         |
| Implementation | 11     | 11     | 0         |
| Testing        | 4      | 4      | 0         |
| **Total**      | **24** | **24** | **0**     |

***

## Setup (3 tasks)

Initial confirmation, fixture scaffolding, and test-project preparation.

* [x] T001 \[S0101] Review direct `EXAMPLES/` evidence and record the selected ingest vocabulary (`.spec_system/specs/phase01-session01-event-ingest-contract-reconciliation/implementation-notes.md`)
* [x] T002 \[S0101] Update node test project inclusion for hook fixture tests (`vitest.config.ts`)
* [x] T003 \[S0101] \[P] Create event-ingest fixture notes for Claude and OpenClaw payload families (`apps/server/tests/fixtures/event-ingest/README.md`)

***

## Foundation (6 tasks)

Shared contracts and server primitives that implementation tasks build on.

* [x] T004 \[S0101] \[P] Create typed ingest request and response contracts with exhaustive event-name and type-only unions (`packages/protocol/src/ingest.ts`)
* [x] T005 \[S0101] Add optional session alias fields to hero runtime and spawn contracts with types matching declared ingest behavior (`packages/protocol/src/heroes.ts`)
* [x] T006 \[S0101] Export ingest contracts from the protocol public entry point (`packages/protocol/src/index.ts`)
* [x] T007 \[S0101] \[P] Add protocol tests for supported ingest names, selected compatibility types, and unsupported vocabulary boundaries (`packages/protocol/tests/ingest.test.ts`)
* [x] T008 \[S0101] Create server ingest normalization helpers with schema-validated input and explicit fallback classification (`apps/server/src/lib/eventIngest.ts`)
* [x] T009 \[S0101] Extend hero roster lookup by session alias without breaking existing hero id lookups (`apps/server/src/managers/heroRoster.ts`)

***

## Implementation (11 tasks)

Route behavior, compatibility mapping, and documentation alignment.

* [x] T010 \[S0101] Refactor `/event` route to use the ingest normalizer with explicit error mapping for malformed bodies (`apps/server/src/routes/event.ts`)
* [x] T011 \[S0101] Implement `SessionStart` and `hero_active` hero materialization with duplicate-trigger prevention by session alias (`apps/server/src/routes/event.ts`)
* [x] T012 \[S0101] Implement `UserPromptSubmit`, `mission_start`, `Stop`, and `hero_idle` lifecycle mapping with session alias resolution (`apps/server/src/routes/event.ts`)
* [x] T013 \[S0101] Implement file and bash payload mapping to generic tool use plus first-class protocol events when an active mission exists (`apps/server/src/routes/event.ts`)
* [x] T014 \[S0101] Implement awaiting-input, input-received, and permission-request mapping with bounded detail fields and explicit missing-hero handling (`apps/server/src/routes/event.ts`)
* [x] T015 \[S0101] Preserve subagent, git guard, and unknown named payloads as bounded opaque mission events with deterministic mission id fallback (`apps/server/src/routes/event.ts`)
* [x] T016 \[S0101] \[P] Add hook fixture tests for emitted payload shapes, truncation, and selected handler mappings (`apps/hooks/tests/hookPayloads.test.js`)
* [x] T017 \[S0101] Update detailed event ingest contract docs for shipped, opaque, unsupported, and OpenClaw-compatible behavior (`docs/api/event-api-hook-contracts.md`)
* [x] T018 \[S0101] \[P] Update concise API docs to summarize the shipped ingest mapping (`docs/api/README_api.md`)
* [x] T019 \[S0101] \[P] Update hook README docs to distinguish first-class, generic tool, and opaque payload handling (`apps/hooks/README_hooks.md`)
* [x] T020 \[S0101] \[P] Update protocol README docs to identify ingest contract ownership (`packages/protocol/README_protocol.md`)

***

## Testing (4 tasks)

Focused validation and session closeout.

* [x] T021 \[S0101] Add server route tests for Claude hook lifecycle, type-only OpenClaw compatibility, missing dispatch keys, and unknown fallback (`apps/server/tests/eventIngest.test.ts`)
* [x] T022 \[S0101] Update existing REST lifecycle tests to assert session alias behavior and current response envelopes (`apps/server/tests/routes.test.ts`)
* [x] T023 \[S0101] Run focused protocol, server, and hook test commands and record results (`.spec_system/specs/phase01-session01-event-ingest-contract-reconciliation/implementation-notes.md`)
* [x] T024 \[S0101] Validate ASCII encoding and LF line endings for all session, source, test, and doc files touched (`.spec_system/specs/phase01-session01-event-ingest-contract-reconciliation/validation.md`)

***

## Completion Checklist

Before marking session complete:

* [x] All tasks marked `[x]`
* [x] All tests passing
* [x] All files ASCII-encoded
* [x] implementation-notes.md updated
* [x] Ready for the validate workflow step

***

## 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/phase01-session01-event-ingest-contract-reconciliation/tasks.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.