> 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/phase17-session01-protocol-notice-contract-parity/spec.md).

# Session Specification

**Session ID**: `phase17-session01-protocol-notice-contract-parity` **Phase**: 17 - Notice Board Coordination Parity **Status**: Not Started **Created**: 2026-06-05 **Package**: packages/protocol **Package Stack**: TypeScript

***

## 1. Session Overview

This session defines the shared Notice Board protocol contract that every later Phase 17 package will consume. The current protocol notice shape is limited to `body`, `targets`, `severity`, and posting metadata. Phase 17 requires the recovered coordination model with canonical notice types, priorities, author metadata, targeting, room scope, related files, resolution fields, and compatibility aliases.

The work stays in `packages/protocol` and its focused tests. It does not add server persistence, Express routes, WebSocket handlers, CLI commands, hook fetching, War Room relay behavior, or web rendering. Those packages depend on this contract being clear and compile-safe first.

The implementation must treat `EXAMPLES/` as quarantined reference evidence only. Behavior may be studied and represented in current source, but historical source is not copied blindly and no new path may weaken local-first privacy boundaries.

***

## 2. Objectives

1. Expand the shared `Notice` model to include canonical Notice Board fields while preserving existing compatibility aliases.
2. Define notice vocabularies, request types, response types, and event payload shapes for canonical `/notice-board` routes and compatibility `/notice` routes.
3. Add validation and normalization helpers for notice type, priority, author type, severity, targets, related files, and compatibility payloads.
4. Add focused protocol tests that prove canonical fields, compatibility aliases, invalid values, event shapes, and helper behavior.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase16-session05-launch-review-and-documentation-handoff` - closes the prior public website phase and allows Phase 17 runtime work to begin.

### Required Tools/Knowledge

* Node 26.2.0 or newer with npm workspaces.
* TypeScript contract editing in `packages/protocol`.
* Vitest test style used by existing protocol tests.
* Phase 17 Notice Board PRD and Session 01 stub.
* Historical Notice Board evidence in quarantined `EXAMPLES/` files.

### Environment Requirements

* Work from the repository root.
* Use package-relative monorepo paths from the repo root.
* Keep all generated and edited files ASCII-only with Unix LF line endings.

***

## 4. Scope

### In Scope (MVP)

* Protocol consumers can import canonical notice vocabularies, types, and guards from `packages/protocol/src/notices.ts` - expand the current model without breaking compatibility fields.
* Server and web packages can type canonical Notice Board route contracts - define list, context, create, resolve, and compatibility request and response shapes.
* WebSocket consumers can type hydrate, message, and resolution frames - update event payload interfaces to accept canonical and compatibility keys.
* Later packages can fail closed on invalid notice values - add pure helpers and tests for type, priority, author type, severity, targets, related files, and payload compatibility.
* Existing clients can continue compiling against `body`, `targets`, `postedAt`, and `severity` - preserve aliases during migration.

### Out of Scope (Deferred)

* Server notice manager persistence - Reason: Session 02 owns state storage, pruning, filtering, context cache, and auto-post behavior.
* Express route implementation - Reason: Session 03 owns runtime route validation and handlers.
* Web cockpit rendering - Reason: Session 04 owns UI and store behavior.
* CLI and hook access - Reason: Sessions 05 and 06 own command and hook implementation.
* War Room relay and catch-up - Reason: Sessions 07 and 08 own Worker and local bridge behavior.
* Automatic mission lifecycle posts - Reason: Session 09 owns runtime auto-post integration.

***

## 5. Technical Approach

### Architecture

Keep `packages/protocol` as the source of truth for cross-package Notice Board contracts. `notices.ts` should own the notice vocabularies, expanded `Notice` shape, canonical and compatibility REST contracts, pure type guards, bounded normalization helpers, and severity derivation helper. `events.ts` should consume those types and describe canonical plus compatibility event payloads. `rest.ts` should keep the existing REST export surface aligned with the new contracts.

The helper surface should be pure and deterministic so server, web, CLI, hooks, and Worker code can reuse it without pulling runtime dependencies into the protocol package. Validation should fail closed for unknown enum values and bounded arrays should reject or trim unsafe shapes according to the contract.

### Design Patterns

* Protocol-first contracts: shared types land before package-specific runtime behavior.
* Compatibility aliases: keep old clients compiling while canonical fields become the preferred shape.
* Pure helpers: avoid server or browser dependencies in protocol code.
* Explicit enum vocabularies: exported `as const` arrays keep tests and consumers synchronized.
* Fail-closed validation: unknown values do not silently become trusted notice payloads.

### Technology Stack

* TypeScript in `packages/protocol`.
* Vitest for focused root test runs.
* Package typecheck through `npm --workspace packages/protocol run typecheck`.
* Biome formatting and linting through root workspace commands.

***

## 6. Deliverables

### Files to Create

| File                                      | Purpose                                   | Est. Lines |
| ----------------------------------------- | ----------------------------------------- | ---------- |
| `packages/protocol/tests/notices.test.ts` | Notice Board contract and helper coverage | \~220      |

### Files to Modify

| File                                     | Changes                                                                                      | Est. Lines |
| ---------------------------------------- | -------------------------------------------------------------------------------------------- | ---------- |
| `packages/protocol/src/notices.ts`       | Expanded notice model, vocabularies, REST shapes, guards, helpers                            | \~260      |
| `packages/protocol/src/events.ts`        | Canonical and compatibility Notice Board event and client message contracts                  | \~40       |
| `packages/protocol/src/rest.ts`          | Re-export or alias canonical Notice Board REST contracts and compatibility `/notice` request | \~35       |
| `packages/protocol/tests/events.test.ts` | Event compatibility and client message tests                                                 | \~50       |
| `packages/protocol/tests/rest.test.ts`   | REST contract type tests for canonical and compatibility routes                              | \~45       |
| `packages/protocol/README_protocol.md`   | Notice Board protocol ownership and privacy boundary notes                                   | \~35       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `Notice` includes all recovered canonical fields and current aliases.
* [ ] Canonical notice types are `status`, `question`, `review`, `announcement`, `conflict`, `completion`, and `human`.
* [ ] Canonical priorities are `normal`, `low`, and `critical`.
* [ ] Compatibility aliases `body`, `targets`, `postedAt`, and `severity` remain typed for existing consumers.
* [ ] `notice_board_hydrate`, `notice_board_message`, and `notice_resolved` support expanded notices and compatibility payload keys.
* [ ] Invalid notice types, priorities, author types, target arrays, related file arrays, and compatibility event payloads fail closed.

### Testing Requirements

* [ ] Focused notice tests written and passing.
* [ ] Existing events and REST protocol tests updated and passing.
* [ ] Package typecheck passing.

### Non-Functional Requirements

* [ ] No helper or contract implies hosted identity, public collaboration safety, production auditability, full trusted erasure, or real executors.
* [ ] Notice Board contracts preserve the privacy boundary for prompts, transcripts, terminal output, file contents, secrets, command bodies, absolute paths, logs, exports, replay buffers, scans, media drafts, diagnostics, backups, and quarantined historical content.
* [ ] Protocol helpers remain dependency-free and reusable by server, web, CLI, hooks, and Worker packages.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.

***

## 8. Implementation Notes

### Key Considerations

* `packages/protocol/src/index.ts` already exports `notices.ts`, `events.ts`, and `rest.ts`; a barrel update is not expected unless new files are added.
* The protocol package has only a `typecheck` script. Focused runtime tests run through the root Vitest command.
* `relatedFiles` path safety in protocol should stay contract-level. Full repository/worktree boundary checks belong to the server route session.

### Potential Challenges

* Compatibility breakage: Preserve existing fields and update tests around old `ClientPostNotice`, `/notice`, and `notice` payload consumers.
* Over-validating in protocol: Keep helpers pure and bounded, but leave runtime path ownership and active room behavior to later server sessions.
* Cross-package drift: Export constants and helpers so downstream packages do not duplicate notice vocabularies.

### Relevant Considerations

* \[P03-packages/protocol] **Protocol leads cross-package work**: Notice Board types and event contracts must land in `packages/protocol` before server, web, CLI, hooks, or Worker behavior changes.
* \[P06-apps/warroom+apps/web] **War Room federation is optional and redacted**: Notice Board relay may share coordination messages only and must not imply hosted identity, public collaboration safety, production auditability, certification, or full erasure.
* \[P07] **Redaction is boundary-specific**: REST, WebSocket, Worker, CLI, hook, replay, export, log, and diagnostic boundaries need explicit minimization.
* \[P03] **Stable docs are the current contract**: Current docs and code become source of truth after this phase; `EXAMPLES/` remains evidence only.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Compatibility aliases compile but runtime payloads drift across packages.
* Invalid enum values are accepted and later interpreted as trusted notices.
* Protocol helpers accidentally imply stronger privacy, hosted identity, or erasure guarantees than the product currently ships.

***

## 9. Testing Strategy

### Unit Tests

* Test exported notice vocabularies and canonical type unions.
* Test `Notice` canonical fields and compatibility alias typing.
* Test guards for valid and invalid notice types, priorities, author types, and severity values.
* Test bounded targets, tags, and related file helper behavior.
* Test severity derivation across type and priority combinations.

### Integration Tests

* Update event tests so `notice_board_hydrate`, `notice_board_message`, `notice_resolved`, and `post_notice` accept canonical and compatibility shapes.
* Update REST contract tests for canonical `/notice-board` request and response shapes plus compatibility `/notice` request shape.

### Manual Testing

* Review generated TypeScript contracts against the Phase 17 PRD and Session 01 stub.
* Confirm no Session 02-10 runtime behavior was implemented in this session.

### Edge Cases

* Unknown notice type, priority, author type, or severity.
* Empty or non-array target and related file values.
* Over-limit target, tag, and related file arrays.
* Compatibility payload using `message` instead of `notice`.
* Compatibility payload using `body` instead of `content`.
* `critical` priority overriding normal type-based severity.

***

## 10. Dependencies

### External Libraries

* None expected.

### Other Sessions

* **Depends on**: `phase16-session05-launch-review-and-documentation-handoff`
* **Depended by**: `phase17-session02-server-notice-manager-persistence-and-context`, `phase17-session03-server-routes-and-websocket-parity`, `phase17-session04-web-store-and-cockpit-notice-board`, `phase17-session05-cli-notice-commands`, `phase17-session06-hook-context-and-provider-skill-parity`, `phase17-session07-war-room-worker-relay-and-catchup`, `phase17-session08-local-war-room-bridge-and-room-notice-convergence`, `phase17-session09-automatic-mission-lifecycle-posts`, and `phase17-session10-validation-documentation-and-handoff`.

***

## 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/phase17-session01-protocol-notice-contract-parity/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.