# Unit of Work — continuum

**Project**: continuum
**Phase**: INCEPTION — Units Generation (Part 2)
**Date**: 2026-05-08

---

## 1. Decomposition Methodology

### 1.1 採用方針（質問回答に基づく確定方針）

| Q | 項目 | 選択 |
|---|---|---|
| Q1 | Unit 粒度 | 中粒度 10 Unit |
| Q2 | Frontend/Backend 統合 | 統合（垂直スライス） |
| Q3 | MACP 分割 | 2 Unit に分離（Phase 2 / Phase 3） |
| Q4 | WebSocket | 独立 Unit |
| Q5 | Demo Set Piece | 独立 Unit |
| Q6 | Monorepo 構造 | Layer-based |
| Q7 | CDK Stack | Layered Stacks |
| Q8 | 並列開発 | 並列最大化 |
| Q9 | 共有型 | 専用パッケージ（`shared/shared-types`） |
| Q10 | AgentCore 連携層 | ~~共有パッケージ（`shared/agentcore-client`）~~ → **2026-05-08 改訂で廃止 / 各 Lambda から AWS SDK 直呼び** |

### 1.2 Unit Boundaries の決定原則

- **垂直スライス**: 各 Unit は Frontend View + Backend Lambda + DynamoDB アクセスを統合し、独立にデモ可能なスコープを持つ
- **MACP は Phase 別 2 Unit**: 簡易シミュレーション（Phase 2）と Federated 本実装（Phase 3）で実装方法が大きく異なるため分離
- **Cross-cutting は独立 Unit**: WebSocket（U-9）と Demo Set Piece（U-10）は複数 Unit から利用される or 演出専用のため独立化
- **共有コードは Unit 化しない**: `shared/shared-types`（型定義）は **共有パッケージ** であり Unit ではない（依存関係マトリクスでは "共有資源" として扱う）。~~`shared/agentcore-client`~~ は 2026-05-08 改訂で**廃止**（各 Lambda から AWS SDK 直呼び）

---

## 2. Unit 一覧

> **🔄 SCOPE REVISION 2026-05-08T06:26:52Z**: デモ視点見直しにより Phase 配分を改訂。詳細は [`../plans/scope-revision-2026-05-08.md`](../plans/scope-revision-2026-05-08.md)。

合計 **10 Unit + 1 共有パッケージ**（agentcore-client 廃止 → SDK 直呼び）

### 2.1 Phase 2 Active Units（7 Unit + 1 共有パッケージ）

| Unit ID | 名称 | Phase | スコープ |
|---|---|---|---|
| **U-1** | Foundation | Phase 2 Must | 認証 + ユーザープロファイル（Communication Style 削除）+ PWA Shell |
| **U-2** | ContactMgmt | Phase 2 Must | コンタクト CRUD + Mock Social Feed（**3 コンタクト × 2 投稿に縮小**） |
| **U-3** | Inbound | Phase 2 Must | 受信応答エンジン（Bedrock 3案、**類似度検証廃止**）|
| **U-4** | Outbound | Phase 2 Must | Strategic Outreach + Signal Extraction（**3 ステップ圧縮**） |
| **U-5** | Maturity | Phase 2 Must | **Lv1 ↔ Lv4 切替集中**（Lv2/Lv3 stub、Lv5 Mock 表示のみ） |
| **U-6** | Dashboard | Phase 2 Must | KPI カード（US-6.1）+ 静的バッジ画像（US-6.2 の絵のみ） |
| **U-7** | MACP-Simulator | Phase 2 Must | Single-Tenant 簡易 MACP（**setTimeout/Polling 演出**） |
| _共有_ | shared/shared-types | — | 全 Unit 共通の TypeScript 型定義 |

### 2.2 Phase 3 Units（3 Unit）

| Unit ID | 名称 | Phase | スコープ |
|---|---|---|---|
| **U-8** | MACP-Federated | Phase 3 Must | AgentCore Identity/Gateway による Federated MACP |
| **U-9** | Realtime | **Phase 3 Must（Phase 2 から降格）** | WebSocket 基盤（決勝デモ用） |
| **U-10** | DemoSetPiece | Phase 3 Must | 決勝 Split-Screen 演出 + 統合シナリオ |

### 2.3 廃止された共有パッケージ

| パッケージ | 元 Phase | 状態 | 理由 |
|---|---|---|---|
| ~~shared/agentcore-client~~ | 全 Phase 共通 | **廃止** | 各 Lambda から AWS SDK 直呼び。抽象化レイヤーは過剰実装と判断（2026-05-08 改訂）|

---

## 3. Unit 詳細

### U-1: Foundation

#### 責務
- アプリ全体の起動・ユーザー登録・ログイン
- PWA Shell（Service Worker 登録、ナビゲーション、グローバル状態）
- Cognito User Pool 連携 + JWT 検証
- ユーザープロファイル（表示名・Default Communication Style）の CRUD
- 初期 Maturity Phase（Lv1）の設定

#### 含むコンポーネント
- **Frontend**: C-FE-01 WebApp Shell, C-FE-02 AuthUI
- **Backend**: C-BE-01 AuthHandler

#### 含むストーリー
- US-1.1: ユーザーサインアップ
- US-1.2: ユーザーログイン
- US-1.3: ユーザープロファイル設定

#### Phase スコープ
- **Phase 2 Must**: 全ストーリー実装

#### 依存
- なし（最上流）
- Cognito User Pool（外部）
- DynamoDB（PROFILE エンティティ）

---

### U-2: ContactMgmt

#### 責務
- コンタクトプロファイル CRUD
- Engagement Cadence の設定（関係 Tier からのデフォルト推定）
- Critical タグ管理
- Mock Social Feed のシードデータ投入（ハッカソンデモ用）

#### 含むコンポーネント
- **Backend**: C-BE-02 ContactHandler, C-BE-10 MockSocialFeedSeeder

#### 含むストーリー
- US-2.1: コンタクト追加
- US-2.2: Engagement Cadence 設定
- US-2.3: Critical タグ管理（Phase 3 Must）
- US-4.7: Mock Social Feed Setup

#### Phase スコープ
- **Phase 2 Must**: US-2.1, US-2.2, US-4.7
- **Phase 3 Must**: US-2.3

#### 依存
- U-1 Foundation（認証）
- DynamoDB（CONTACT, FEED, WINDOW エンティティ）

---

### U-3: Inbound

#### 責務
- 受信メッセージへの 3 バリエーション応答生成
- Relational Calibration（関係 Tier 別トーン）
- Plausibility Constraint（案間類似度 < 0.7）
- 受信ボックス UI + 案選択 + 編集 + 送信
- Maturity Phase 連動（Lv1: 全レビュー / Lv2: 確率的スキップ / Lv3: Critical のみ / Lv4-5: 全自動）

#### 含むコンポーネント
- **Frontend**: C-FE-03 InboxView
- **Backend**: C-BE-03 InboundResponseEngine

#### 含むストーリー
- US-3.1: 受信ボックスでメッセージ一覧
- US-3.2: 単一メッセージへの 3 案応答生成
- US-3.3: 案の手動編集と送信（Lv1限定）
- US-3.4: 案バリエーション生成エンジン
- US-3.5: Relational Calibration（Phase 2 Should）
- US-3.6: 応答送信完了後の状態管理（Phase 3 Stretch）

#### Phase スコープ
- **Phase 2 Must**: US-3.1, US-3.2, US-3.3, US-3.4
- **Phase 2 Should**: US-3.5
- **Phase 3 Stretch**: US-3.6

#### 依存
- U-1 Foundation（認証）
- U-2 ContactMgmt（コンタクトプロファイル取得）
- U-5 Maturity（フェーズ判定）
- shared/shared-types
- AWS SDK 直呼び（Bedrock Runtime / AgentCore Memory）— 2026-05-08 改訂で `shared/agentcore-client` 廃止

---

### U-4: Outbound

#### 責務
- Strategic Outreach Scheduling（不在 Window への誘い文生成）
- Engagement Heartbeat（Cadence 別の定期送信）
- Conflict Detection（Inbound-Outbound 整合性）
- Plausibility Engineering（時刻分散・文体学習・Context Echo）
- Mock Social Feed からの Signal 抽出パイプライン
- Outbound Pre-send Review UI

#### 含むコンポーネント
- **Frontend**: C-FE-04 OutboundReviewView
- **Backend**: C-BE-04 OutboundOrchestrator, C-BE-05 SignalExtractor

#### 含むストーリー
- US-4.1: Mock Social Feed からの不在シグナル抽出
- US-4.2: Strategic Outreach Window への誘い文生成
- US-4.3: Engagement Heartbeat（Phase 3 Stretch）
- US-4.4: Conflict Detection & Coherence Layer（Phase 3 Must）
- US-4.5: Plausibility Engineering（Phase 3 Must）
- US-4.6: Outbound 送信前レビュー（Phase 2 Should）

#### Phase スコープ
- **Phase 2 Must**: US-4.1, US-4.2
- **Phase 2 Should**: US-4.6
- **Phase 3 Must**: US-4.4, US-4.5
- **Phase 3 Stretch**: US-4.3

#### 依存
- U-1 Foundation（認証）
- U-2 ContactMgmt（コンタクト + Mock Feed）
- U-5 Maturity（フェーズ判定）
- U-7/U-8 MACP（Outbound 送信前 MACP 試行）
- shared/shared-types
- AWS SDK 直呼び（Bedrock Runtime）— 2026-05-08 改訂で `shared/agentcore-client` 廃止

---

### U-5: Maturity

#### 責務
- Lv1〜Lv5 のフェーズ状態管理
- フェーズ移行ロジック（手動切替 / Recommendation 表示 / Lv4 自己有効化 / Lv5 自動認定）
- 累計応答件数の追跡 + Recommendation トリガー判定
- Lv5 認定条件チェック（日次バッチ）
- フェーズ別の挙動判定 API（`shouldReviewInbound` / `shouldReviewOutbound`）

#### 含むコンポーネント
- **Frontend**: C-FE-06 MaturitySettingsView
- **Backend**: C-BE-06 MaturityPhaseManager

#### 含むストーリー
- US-5.1: Lv1 慎重期の動作
- US-5.2: Lv2 信頼期の確率的レビュースキップ
- US-5.3: Lv3 委任期での Critical タグ別動作
- US-5.4: Lv4 解脱期の自己有効化
- US-5.5: Lv5 涅槃期のシステム自動認定（Phase 3 Must）
- US-5.6: Maturity Recommendation バナー（Phase 2 Should）

#### Phase スコープ
- **Phase 2 Must**: US-5.1, US-5.2, US-5.3, US-5.4
- **Phase 2 Should**: US-5.6
- **Phase 3 Must**: US-5.5

#### 依存
- U-1 Foundation（認証）
- DynamoDB（MATURITY エンティティ）
- shared/shared-types

---

### U-6: Dashboard

#### 責務
- KPI 集計（Responses Delegated / Time Reclaimed / Streak / Score）
- Maturity Certification バッジ管理
- Outbound メトリクス（Optimal Window Hit Rate / Relationship Health Score / Engagement Coverage）
- Days in Nirvana 表示
- Productivity Analytics ダッシュボード UI（SaaS 標準クリーンデザイン）

#### 含むコンポーネント
- **Frontend**: C-FE-05 DashboardView
- **Backend**: C-BE-08 DashboardEngine

#### 含むストーリー
- US-6.1: KPI カード表示
- US-6.2: Maturity Certification バッジ表示（Phase 2 Should）
- US-6.3: Outbound メトリクスとリレーションシップヘルススコア（Phase 3 Must）
- US-6.4: Days in Nirvana 表示（Phase 3 Stretch）

#### Phase スコープ
- **Phase 2 Must**: US-6.1
- **Phase 2 Should**: US-6.2
- **Phase 3 Must**: US-6.3
- **Phase 3 Stretch**: US-6.4

#### 依存
- U-1 Foundation（認証）
- U-5 Maturity（バッジ・Recommendation との連携）
- shared/shared-types

---

### U-7: MACP-Simulator（Phase 2 簡易版）

#### 責務
- **Single-Tenant 簡易 MACP**: 同一 Continuum インスタンス内の 2 ユーザー（UserA / UserB）間で MACP の演出を実行
- Peer Discovery: 同一テナント内の他ユーザー検索（簡易）
- Inter-Agent Negotiation: Lambda 内で完結する合意形成（同一プロセス）
- Theatrical Performance: EventBridge で複数メッセージを順次配信
- Outcome Confirmation: 両ユーザーへバッジ付与

#### 含むコンポーネント
- **Backend**: C-BE-07 MACPCoordinator（Phase 2 簡易実装版）

#### 含むストーリー
- US-7.1: Peer Discovery（Single-Tenant 簡易シミュレーション版）

#### Phase スコープ
- **Phase 2 Must**: US-7.1（簡易版）

#### 依存
- U-1 Foundation
- U-2 ContactMgmt
- U-4 Outbound（送信前トリガー）
- U-9 Realtime（演出のリアルタイム配信）
- shared/shared-types

#### 注記
- 本 Unit は Phase 2 限定の **暫定実装**。Phase 3 の U-8 で Federated 本実装に置き換えられる
- AgentCore Identity / Gateway は使用しない（Phase 2 ではモック）

---

### U-8: MACP-Federated（Phase 3 本実装）

#### 責務
- **Federated MACP**: 別テナント間で AgentCore Gateway 経由の Inter-Agent Negotiation
- Peer Discovery: AgentCore Identity による Cross-Tenant Lookup（片方向ハッシュ）
- Inter-Agent Negotiation: AgentCore Gateway + mTLS で JSON プロトコル交換
- AgentCore Memory による交渉履歴の永続化（再交渉時の効率化）
- Failure Handling: タイムアウト・認証失敗時の Graceful Degradation

#### 含むコンポーネント
- **Backend**: C-BE-07 MACPCoordinator（Phase 3 完全実装版）

#### 含むストーリー
- US-7.1: Peer Discovery（Federated 本実装）
- US-7.2: Inter-Agent Negotiation
- US-7.3: Theatrical Performance Layer
- US-7.4: Outcome Confirmation
- US-7.5: MACP Failure Handling（Phase 3 Stretch）

#### Phase スコープ
- **Phase 3 Must**: US-7.1, US-7.2, US-7.3, US-7.4
- **Phase 3 Stretch**: US-7.5

#### 依存
- U-1 Foundation
- U-2 ContactMgmt
- U-4 Outbound（送信前トリガー）
- U-7 MACP-Simulator（既存の演出ロジックの拡張）
- U-9 Realtime（演出のリアルタイム配信）
- AgentCore Identity / Gateway / Memory（外部 — AWS SDK 直呼び）
- shared/shared-types

---

### U-9: Realtime

#### 責務
- API Gateway WebSocket API の接続管理
- 接続情報の DynamoDB 永続化（TTL 付き）
- ユーザー単位プッシュ + デモ用ブロードキャスト
- Frontend WebSocket Client ライブラリ提供

#### 含むコンポーネント
- **Frontend**: C-FE-08 WebSocketClient
- **Backend**: C-BE-09 WebSocketBroker

#### 含むストーリー
（直接対応するストーリーはなく、他 Unit から利用される基盤）
- 利用元: US-5.6（Recommendation バナー push）, US-6.2（バッジ獲得 push）, US-7.4（MACP 完了 push）, DS-3（Split-Screen リアルタイム）

#### Phase スコープ
- **Phase 2 Should**: 基盤実装 + 通知配信
- **Phase 3 Must**: 決勝デモ用の MACP リアルタイム配信

#### 依存
- U-1 Foundation（認証）
- shared/shared-types

---

### U-10: DemoSetPiece

#### 責務
- 決勝デモ用の **Split-Screen UI**（左: UserA / 右: UserB / 下: Negotiation Log）
- タイムラプス再生制御
- 締めナレーション + ロゴ演出
- デモ用 UserA / UserB の事前セットアップスクリプト

#### 含むコンポーネント
- **Frontend**: C-FE-07 DemoSetPieceView
- 統合シナリオ（U-7 + U-9 を組み合わせ）
- Demo Setup スクリプト（CLI）

#### 含むストーリー
- DS-1: Set Piece 全体ストーリー
- DS-2: Demo 用ユーザーセットアップ
- DS-3: スプリットスクリーン裏舞台演出
- DS-4: 締めナレーション・コピー演出

#### Phase スコープ
- **Phase 3 Must**: DS-1, DS-2, DS-3, DS-4

#### 依存
- U-7 MACP-Simulator（Phase 2 簡易版でも演出可能）+ U-8 MACP-Federated（Phase 3 本格演出）
- U-9 Realtime（リアルタイム配信）
- U-1〜U-6 すべての画面（統合シナリオで参照）

---

## 4. 共有パッケージ

### shared/shared-types

#### 責務
- Frontend / Backend / Infrastructure すべてで共通利用される TypeScript 型定義
- ドメインエンティティ型（User, Contact, InboxMessage, OutboundCandidate, MACPSession, Badge, AvailabilityWindow, etc.）
- API リクエスト・レスポンス型
- WebSocket イベント型

#### 含む型（一例）
```typescript
- UserProfile
- Contact + relationship enum
- InboxMessage + status enum
- ResponseVariation + style enum
- OutboundCandidate + type enum
- AvailabilityWindow + signal category enum
- MaturityState + phase enum
- MACPSession + agreement struct
- Badge
- WebSocketEvent (union type)
- DashboardKPI
```

#### 配置
```
shared/shared-types/
├── package.json
├── tsconfig.json
└── src/
    ├── index.ts
    ├── domain/
    │   ├── user.ts
    │   ├── contact.ts
    │   ├── inbox.ts
    │   ├── outbound.ts
    │   ├── maturity.ts
    │   ├── macp.ts
    │   └── badge.ts
    ├── api/
    │   ├── requests.ts
    │   └── responses.ts
    └── websocket/
        └── events.ts
```

---

### ~~shared/agentcore-client~~ — **廃止**

> **🔄 2026-05-08 改訂で廃止**: AgentCore SDK の抽象化レイヤーは過剰実装と判断。各 Lambda（U-3 Inbound / U-4 Outbound / U-8 MACP-Federated）から **AWS SDK を直接呼び出す** 方針に変更。
>
> **代替**:
> - **Bedrock Runtime**: `@aws-sdk/client-bedrock-runtime` を Lambda 内で直接 import
> - **AgentCore Memory / Identity / Gateway**: Phase 3 実装時に各 Lambda から直接 AgentCore SDK を呼び出す（リトライ・タイムアウトは AWS SDK 標準機構を利用）
>
> **影響**: U-3 / U-4 / U-8 の依存リストから削除。Phase 2 工数約 1 Unit 分の削減。

---

## 5. Code Organization Strategy（Layer-based Monorepo）

### 5.1 Top-level Directory Structure

```
continuum/
├── frontend/                    ← React PWA（Vite + Service Worker）
│   ├── package.json
│   ├── vite.config.ts
│   ├── public/
│   │   ├── manifest.json        ← PWA Manifest
│   │   └── sw.ts                ← Service Worker (Workbox)
│   └── src/
│       ├── main.tsx
│       ├── App.tsx
│       ├── views/
│       │   ├── Inbox/           ← U-3
│       │   ├── Outbound/        ← U-4
│       │   ├── Dashboard/       ← U-6
│       │   ├── Maturity/        ← U-5
│       │   ├── DemoSetPiece/    ← U-10
│       │   └── Auth/            ← U-1
│       ├── components/          ← 共通 UI コンポーネント
│       ├── hooks/
│       ├── services/            ← API client wrappers
│       └── ws/                  ← WebSocketClient (U-9)
│
├── backend/                     ← AWS Lambda Functions
│   ├── auth/                    ← U-1
│   ├── contact/                 ← U-2
│   ├── inbound/                 ← U-3
│   ├── outbound/                ← U-4
│   ├── signal-extractor/        ← U-4 内部（別 Lambda）
│   ├── maturity/                ← U-5
│   ├── macp-simulator/          ← U-7（Phase 2）
│   ├── macp-federated/          ← U-8（Phase 3）
│   ├── dashboard/               ← U-6
│   ├── websocket/               ← U-9
│   └── seeder/                  ← U-2 内部（CLI）
│
├── infrastructure/              ← AWS CDK (Layered Stacks)
│   ├── package.json
│   ├── cdk.json
│   ├── bin/
│   │   └── continuum.ts         ← CDK App エントリ
│   └── lib/
│       ├── stacks/
│       │   ├── foundation-stack.ts    ← Cognito + IAM + ACM (Q7=C)
│       │   ├── data-stack.ts          ← DynamoDB + Connection Table
│       │   └── application-stack.ts   ← Lambda + API Gateway + EventBridge
│       └── constructs/
│           ├── lambda-construct.ts
│           └── api-construct.ts
│
└── shared/                      ← 共有パッケージ (Q9, Q10)
    ├── shared-types/            ← TypeScript 型定義
    # agentcore-client/  ← 2026-05-08 改訂で廃止（各 Lambda から AWS SDK 直呼び）
```

### 5.2 Monorepo 管理ツール
- **pnpm workspace**（高速・ディスク効率）
- ルート `package.json` の `workspaces` フィールドに `frontend`, `backend/*`, `infrastructure`, `shared/*` を登録
- `pnpm-workspace.yaml`:
  ```yaml
  packages:
    - 'frontend'
    - 'backend/*'
    - 'infrastructure'
    - 'shared/*'
  ```

### 5.3 ビルド・デプロイ

| 操作 | コマンド |
|---|---|
| 全 install | `pnpm install` |
| 共有型ビルド | `pnpm --filter shared-types build` |
| Frontend dev | `pnpm --filter frontend dev` |
| Backend Lambda ビルド | `pnpm --filter ./backend/... build` |
| CDK Deploy | `pnpm --filter infrastructure cdk deploy --all` |
| 全 lint | `pnpm -r lint` |
| 全 test | `pnpm -r test` |

### 5.4 CDK Layered Stacks（Q7=C）

```
FoundationStack
├── Cognito User Pool + Client
├── IAM Roles（Lambda 実行ロール、API Gateway 認証ロール等）
├── ACM Certificate
└── Route 53 Hosted Zone

DataStack（FoundationStack 後にデプロイ）
├── DynamoDB Single-Table（PK/SK + GSI1, GSI2）
├── DynamoDB Connection Table（WebSocket 接続管理 + TTL）
└── Secrets Manager（Bedrock Model ID, AgentCore endpoints）

ApplicationStack（FoundationStack + DataStack 後）
├── Lambda Functions × 10
├── API Gateway REST API + Cognito Authorizer
├── API Gateway WebSocket API
├── EventBridge Custom Bus + Rules
├── CloudFront Distribution + S3 Bucket（Frontend）
└── X-Ray（Phase 3 のみ）
```

---

## 6. Phase Scope Summary

| Phase | 含む Unit + 含むストーリー数 |
|---|---|
| **Phase 2 Must（5/30 予選 MVP）** | U-1 (3) / U-2 (3) / U-3 (4) / U-4 (2) / U-5 (4) / U-6 (1) / U-7 (1) = **18 ストーリー** |
| **Phase 2 Should（余裕があれば）** | U-3 (1: US-3.5) / U-4 (1: US-4.6) / U-5 (1: US-5.6) / U-6 (1: US-6.2) / U-9 (基盤) = **3 ストーリー + U-9 基盤** |
| **Phase 3 Must（決勝 6/26）** | U-2 (1: US-2.3) / U-4 (2) / U-5 (1: US-5.5) / U-6 (1: US-6.3) / U-8 (4) / U-9 (本格運用) / U-10 (4) = **13 ストーリー** |
| **Phase 3 Stretch** | U-3 (1) / U-4 (1) / U-6 (1) / U-8 (1: US-7.5) = **4 ストーリー** |
| **総計** | **38 ストーリー** |

---