@c-d-cc/reap 0.4.0 → 0.6.1

package/README.ja.md

@@ -1,3 +1,5 @@
+> [English](README.md) | [한국어](README.ko.md) | [简体中文](README.zh-CN.md)
+
 <p align="center">
   <img src="media/logo.png" alt="REAP" width="80" height="80" />
 </p>
@@ -9,8 +11,6 @@
   AIと人間がGenerationを重ねてソフトウェアを進化させる開発パイプライン。
 </p>
 
-> [English](README.md) | [한국어](README.ko.md) | [简体中文](README.zh-CN.md)
-
 <table align="center">
 <tr>
 <td align="center"><strong>Genome</strong><br><sub>設計とナレッジ</sub></td>
@@ -23,6 +23,22 @@
 
 REAPはアプリケーションの遺伝情報（Genome）を定義し、各世代で目標を設定して実装し、その過程で発見したGenomeの欠陥を次のステージにフィードバックします。世代を重ねるごとにGenomeが進化し、Source Code（Civilization）が成長します。
 
+## 目次
+
+- [なぜREAPか？](#なぜreapか)
+- [インストール](#インストール)
+- [クイックスタート](#クイックスタート)
+- [ライフサイクル](#ライフサイクル)
+- [コアコンセプト](#コアコンセプト)
+- [分散ワークフロー — 並行開発](#分散ワークフロー--並行開発)
+- [CLIコマンド](#cliコマンド)
+- [エージェント連携](#エージェント連携)
+- [`reap init`後のプロジェクト構造](#reap-init後のプロジェクト構造)
+- [系譜圧縮（Lineage Compression）](#系譜圧縮lineage-compression)
+- [進化フロー（Evolution Flow）](#進化フローevolution-flow)
+- [プリセット（Presets）](#プリセットpresets)
+- [エントリーモード（Entry Modes）](#エントリーモードentry-modes)
+
 ## なぜREAPか？
 
 AIエージェントと開発する際、こんな問題に遭遇したことはありませんか？
@@ -31,6 +47,7 @@ AIエージェントと開発する際、こんな問題に遭遇したことは
 - **散発的な開発** — 明確な目標なくあちこちのコードを修正
 - **設計とコードの乖離** — ドキュメントとコードが時間とともに離れていく
 - **教訓の忘却** — 苦労して得たインサイトが次の作業に反映されない
+- **コラボレーションの混乱** — 複数の開発者やエージェントが並行して作業すると、競合が頻発しマージが悪夢になる
 
 REAPは**世代ベースの進化モデル**でこれらの問題を解決します：
 
@@ -39,6 +56,7 @@ REAPは**世代ベースの進化モデル**でこれらの問題を解決しま
 - 実装中に発見した設計問題はbacklogに記録、Completionで反映
 - レトロスペクティブ（Completion）で導き出した教訓がGenomeに蓄積
 - 世代を重ねて繰り返される手作業を自動検出し、ユーザー確認の上でHookとして生成
+- ブランチ間の並行作業はgenome-firstマージワークフローで調整 — コードの競合の前に設計の競合を解決
 
 ## インストール
 
@@ -94,7 +112,7 @@ Objective → Planning → Implementation ⟷ Validation → Completion
 
 | ステージ | 内容 | 成果物 |
 |----------|------|--------|
-| **Objective** | 目標 + 要件 + 受入基準の定義 | `01-objective.md` |
+| **Objective** | 構造化ブレインストーミングによる目標・設計定義：明確化質問、アプローチ代案、セクション別設計、ビジュアルコンパニオン、Specレビュー | `01-objective.md` |
 | **Planning** | タスク分解、実装アプローチ、依存関係 | `02-planning.md` |
 | **Implementation** | AI+Human協力でコード実装 | `03-implementation.md` |
 | **Validation** | テスト実行、完了条件の確認 | `04-validation.md` |
@@ -146,6 +164,55 @@ Objective → Planning → Implementation ⟷ Validation → Completion
 └── lineage/       # 完了した世代のアーカイブ
 ```
 
+## 分散ワークフロー — 並行開発
+
+> **⚠ 初期段階** — 分散ワークフローにはさらなるテストが必要です。本番環境でのご使用にはご注意ください。フィードバックを収集しています — [Issueを登録](https://github.com/c-d-cc/reap/issues)。
+
+REAPは複数の開発者やAIエージェントが同一プロジェクトで並行して作業する分散コラボレーションをサポートします。中央サーバー不要で、Gitだけで動作します。
+
+### 動作の仕組み
+
+```
+Machine A: branch-a — gen-046-a (authentication)    → /reap.push
+Machine B: branch-b — gen-046-b (search)            → /reap.push
+
+Machine A:
+  /reap.pull branch-b   → Fetch + マージGeneration全ライフサイクルを実行
+```
+
+各マシンは自分のブランチとGenerationで独立して作業します。統合するタイミングで、REAPは**genome-first**戦略でマージを調整します（[詳しく見る](https://reap.cc/docs/merge-generation)）：
+
+1. **Detect** — リモートブランチのgenomeとlineageをgit refでスキャンし、分岐点を特定
+2. **Mate** — Genomeの競合を最初に解決（人間が判断）
+3. **Merge** — 確定したGenomeを基準にソースコードをマージ（`git merge --no-commit`）
+4. **Sync** — AIがGenomeとソースを比較して整合性を確認；不整合があればユーザーが確認
+5. **Validation** — 機械的テストを実行（bun test、tsc、build）— 通常のGenerationと同様
+6. **Completion** — マージ結果をコミットしてアーカイブ
+
+### 分散ワークフロー用スラッシュコマンド
+
+すべての分散操作はAIエージェントを通じて実行します：
+
+```bash
+/reap.pull <branch>        # Fetch + マージGeneration全体を実行（分散版 /reap.evolve）
+/reap.merge <branch>       # ローカルブランチのマージGeneration全体を実行（fetchなし）
+/reap.push                 # REAP状態を検証 + 現在のブランチをpush
+/reap.merge.start          # マージGenerationを開始（ステップバイステップ制御用）
+/reap.merge.detect         # 分岐を分析
+/reap.merge.mate           # Genomeの競合を解決
+/reap.merge.merge          # ソースコードをマージ
+/reap.merge.sync           # Genome-ソース間の整合性を検証
+/reap.merge.validation     # 機械的テストを実行（bun test、tsc、build）
+/reap.merge.evolve         # 現在のステージからマージライフサイクルを実行
+```
+
+### 基本原則
+
+- **Opt-in** — `git pull`/`push`は常にそのまま動作します。REAPコマンドは付加的なものです。
+- **Genome-first** — ソースマージの前にGenomeの競合を解決します。憲法を改正してから法律を更新するようなものです。
+- **サーバー不要** — すべてがローカル + Git。外部サービスは不要です。
+- **DAG lineage** — 各世代はハッシュベースのID（`gen-046-a3f8c2`）で親を参照し、有向非巡回グラフを形成するため、並行作業を自然にサポートします。
+
 ## CLIコマンド
 
 | コマンド | 説明 |
@@ -187,6 +254,16 @@ REAPはスラッシュコマンドとセッションフックを通じてAIエ
 | `/reap.help` | 24+トピックのcontextual AIヘルプ（workflow, genome, backlog, strict, agents, hooks, config, evolve, regression, authorおよび全コマンド名） |
 | `/reap.update` | REAPのアップデート確認と最新バージョンへのアップグレード |
 | **`/reap.evolve`** | **1つのGeneration全体を最初から最後まで実行（推奨）** |
+| **`/reap.pull <branch>`** | **Fetch + マージGeneration全体を実行（分散版 `/reap.evolve`）** |
+| **`/reap.merge <branch>`** | **ローカルブランチのマージGeneration全体を実行（fetchなし）** |
+| `/reap.push` | REAP状態を検証して現在のブランチをpush |
+| `/reap.merge.start` | 分岐ブランチを統合するマージGenerationを開始 |
+| `/reap.merge.detect` | ブランチ間の分岐を分析 |
+| `/reap.merge.mate` | ソースマージの前にGenomeの競合を解決 |
+| `/reap.merge.merge` | 解決済みGenomeを基準にソースコードをマージ |
+| `/reap.merge.sync` | Genome-ソース間の整合性を検証（AI比較、ユーザー確認） |
+| `/reap.merge.validation` | 機械的テストを実行（bun test、tsc、build） |
+| **`/reap.merge.evolve`** | **マージライフサイクル全体を自動実行** |
 
 ### SessionStart Hook
 
@@ -202,24 +279,30 @@ REAPはスラッシュコマンドとセッションフックを通じてAIエ
 
 ### Strictモード
 
-`.reap/config.yml`に`strict: true`を設定すると、AIエージェントがREAPワークフロー外でコードを変更することを制限します：
+Strictモードは、AIエージェントが許可される操作を制御します。2つの細かいオプションをサポートします：
 
 ```yaml
 # .reap/config.yml
-strict: true      # デフォルト: false
-language: korean  # 成果物とインタラクションの言語
-autoUpdate: true  # セッション開始時の自動アップデート
-agents:           # 検出されたエージェント（reap init/updateで管理）
-  - claude-code
-  - opencode
+strict: true              # 省略形：editとmerge両方を有効化
+
+# または細かい制御：
+strict:
+  edit: true              # コード変更をREAPライフサイクルに制限
+  merge: false            # raw git pull/push/mergeを制限
 ```
 
+**`strict.edit`** — コード変更制御：
+
 | 状況 | 動作 |
 |------|------|
 | アクティブGenerationなし / 実装ステージ外 | コード変更は完全にブロック |
 | Implementationステージ | `02-planning.md`の範囲内でのみ変更許可 |
 | エスケープハッチ | ユーザーが「override」「bypass strict」等を明示的に要求した場合に許可 |
 
+**`strict.merge`** — Gitコマンド制御：有効にすると`git pull`/`push`/`merge`の直接使用が制限されます。エージェントが`/reap.pull`、`/reap.push`、`/reap.merge`の使用を案内します。
+
+どちらもデフォルトで無効。`strict: true`は両方を有効にします。
+
 Strictモードはデフォルトで無効です（`strict: false`）。
 
 ### REAP Hooks
@@ -253,6 +336,9 @@ order: 10                     # 実行順序（小さいほど先に実行）
 | `onStageTransition` | `/reap.next`で次のステージに前進後 |
 | `onGenerationComplete` | `/reap.next`で完了したGenerationをアーカイブ後 |
 | `onRegression` | `/reap.back`で前のステージに回帰後 |
+| `onMergeStart` | `/reap.merge.start`でマージGeneration作成後 |
+| `onGenomeResolved` | マージ中にGenomeの競合が解決された後 |
+| `onMergeComplete` | マージGenerationがアーカイブされた後 |
 
 HookはAIエージェントがプロジェクトルートディレクトリで実行します。`onGenerationComplete` Hookには自動バージョンバンプ判定が含まれています — patchレベルは自動適用され、minor/majorバンプはユーザー確認が必要です。
 

package/README.ko.md

@@ -1,3 +1,5 @@
+> [English](README.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)
+
 <p align="center">
   <img src="media/logo.png" alt="REAP" width="80" height="80" />
 </p>
@@ -9,8 +11,6 @@
   AI와 인간이 세대(Generation)를 거듭하며 소프트웨어를 진화시키는 개발 파이프라인.
 </p>
 
-> [English](README.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)
-
 <table align="center">
 <tr>
 <td align="center"><strong>Genome</strong><br><sub>설계와 지식</sub></td>
@@ -23,6 +23,22 @@
 
 REAP은 Application의 유전 정보(Genome)를 정의하고, 각 세대에서 목표를 설정하여 구현하고, 그 과정에서 발견한 Genome 결함을 다음 단계에서 반영합니다. 세대를 거듭하며 Genome이 진화하고, Source Code(Civilization)가 성장합니다.
 
+## 목차
+
+- [Why REAP?](#why-reap)
+- [설치](#설치)
+- [빠른 시작](#빠른-시작)
+- [생애주기 (Life Cycle)](#생애주기-life-cycle)
+- [핵심 개념](#핵심-개념)
+- [분산 워크플로우 — 병렬 개발](#분산-워크플로우--병렬-개발)
+- [CLI 명령어](#cli-명령어)
+- [에이전트 연동](#에이전트-연동)
+- [`reap init` 후 프로젝트 구조](#reap-init-후-프로젝트-구조)
+- [계보 압축 (Lineage Compression)](#계보-압축-lineage-compression)
+- [진화 흐름 (Evolution Flow)](#진화-흐름-evolution-flow)
+- [프리셋 (Presets)](#프리셋-presets)
+- [진입 모드 (Entry Modes)](#진입-모드-entry-modes)
+
 ## Why REAP?
 
 AI 에이전트와 함께 개발할 때 이런 문제를 겪어본 적 있나요?
@@ -31,6 +47,7 @@ AI 에이전트와 함께 개발할 때 이런 문제를 겪어본 적 있나요
 - **산발적 개발** — 명확한 목표 없이 여기저기 코드를 수정
 - **설계와 코드의 괴리** — 문서는 따로, 코드는 따로 놀면서 점점 벌어짐
 - **교훈의 망각** — 삽질한 경험이 다음 작업에 반영되지 않음
+- **협업의 혼란** — 여러 개발자나 에이전트가 병렬로 작업하면 충돌이 빈발하고 머지가 악몽이 됨
 
 REAP은 **세대 기반 진화 모델**로 이 문제들을 해결합니다:
 
@@ -39,6 +56,7 @@ REAP은 **세대 기반 진화 모델**로 이 문제들을 해결합니다:
 - 구현 중 발견한 설계 문제는 backlog에 기록, Completion에서 반영
 - 회고(Completion)에서 도출한 교훈이 Genome에 축적
 - 세대를 거듭하며 반복되는 수작업을 자동 감지하고, 사용자 확인 후 Hook으로 생성
+- 브랜치 간 병렬 작업은 genome-first 머지 워크플로우로 조율 — 코드 충돌 전에 설계 충돌부터 해결
 
 ## 설치
 
@@ -94,7 +112,7 @@ Objective → Planning → Implementation ⟷ Validation → Completion
 
 | 단계 | 하는 일 | 산출물 |
 |------|---------|--------|
-| **Objective** | 목표 + 요구사항 + 수용기준 정의 | `01-objective.md` |
+| **Objective** | 구조화된 브레인스토밍으로 목표 및 설계 정의: 명확화 질문, 접근법 대안, 섹션별 설계, 비주얼 컴패니언, Spec 리뷰 | `01-objective.md` |
 | **Planning** | 태스크 분해, 구현 접근법, 의존관계 | `02-planning.md` |
 | **Implementation** | AI+Human 협업으로 코드 구현 | `03-implementation.md` |
 | **Validation** | 테스트 실행, 완료 조건 점검 | `04-validation.md` |
@@ -146,6 +164,55 @@ Application의 유전 정보 — 아키텍처 원칙, 비즈니스 규칙, 개
 └── lineage/       # 완료된 세대들의 아카이브
 ```
 
+## 분산 워크플로우 — 병렬 개발
+
+> **⚠ 초기 단계** — 분산 워크플로우는 추가 테스트가 필요합니다. 프로덕션 환경에서는 주의하여 사용하세요. 피드백을 수집하고 있습니다 — [이슈 등록](https://github.com/c-d-cc/reap/issues).
+
+REAP은 여러 개발자 또는 AI 에이전트가 동일 프로젝트에서 병렬로 작업하는 분산 협업을 지원합니다. 별도 서버 없이 Git만으로 동작합니다.
+
+### 동작 방식
+
+```
+Machine A: branch-a — gen-046-a (authentication)    → /reap.push
+Machine B: branch-b — gen-046-b (search)            → /reap.push
+
+Machine A:
+  /reap.pull branch-b   → Fetch + 전체 머지 Generation 라이프사이클 실행
+```
+
+각 머신은 자신의 브랜치와 Generation에서 독립적으로 작업합니다. 합칠 때가 되면 REAP이 **genome-first** 전략으로 머지를 조율합니다 ([자세히 보기](https://reap.cc/docs/merge-generation)):
+
+1. **Detect** — 원격 브랜치의 genome과 lineage를 git ref로 스캔하여 분기점을 파악
+2. **Mate** — Genome 충돌부터 해결 (사람이 판단)
+3. **Merge** — 확정된 Genome을 기준으로 소스 코드 머지 (`git merge --no-commit`)
+4. **Sync** — AI가 Genome과 소스를 비교하여 일관성 확인; 불일치 발견 시 사용자 확인
+5. **Validation** — 기계적 테스트 실행 (bun test, tsc, build) — 일반 Generation과 동일
+6. **Completion** — 머지 결과를 커밋하고 아카이빙
+
+### 분산 워크플로우 슬래시 커맨드
+
+모든 분산 작업은 AI 에이전트를 통해 실행합니다:
+
+```bash
+/reap.pull <branch>        # Fetch + 전체 머지 Generation 실행 (분산 /reap.evolve)
+/reap.merge <branch>       # 로컬 브랜치 전체 머지 Generation 실행 (fetch 없음)
+/reap.push                 # REAP 상태 검증 + 현재 브랜치 push
+/reap.merge.start          # 머지 Generation 시작 (단계별 제어용)
+/reap.merge.detect         # 분기 분석
+/reap.merge.mate           # Genome 충돌 해결
+/reap.merge.merge          # 소스 코드 머지
+/reap.merge.sync           # Genome-소스 일관성 검증
+/reap.merge.validation     # 기계적 테스트 실행 (bun test, tsc, build)
+/reap.merge.evolve         # 현재 stage부터 머지 라이프사이클 실행
+```
+
+### 핵심 원칙
+
+- **Opt-in** — `git pull`/`push`는 항상 그대로 동작합니다. REAP 커맨드는 부가적입니다.
+- **Genome-first** — 소스 머지 전에 Genome 충돌을 먼저 해결합니다. 헌법을 개정한 뒤 법률을 수정하는 것과 같습니다.
+- **서버 불필요** — 모든 것이 로컬 + Git. 외부 서비스가 필요 없습니다.
+- **DAG lineage** — 각 세대는 해시 기반 ID(`gen-046-a3f8c2`)로 부모를 참조하여 방향 비순환 그래프를 형성하므로, 병렬 작업을 자연스럽게 지원합니다.
+
 ## CLI 명령어
 
 | 명령어 | 설명 |
@@ -187,6 +254,16 @@ Slash command가 `.claude/commands/`에 설치되어 전체 워크플로우를
 | `/reap.help` | 24+ 주제의 contextual AI 도움말 (workflow, genome, backlog, strict, agents, hooks, config, evolve, regression, author 및 모든 커맨드 이름) |
 | `/reap.update` | REAP 업데이트 확인 및 최신 버전으로 업그레이드 |
 | **`/reap.evolve`** | **한 Generation 전체를 처음부터 끝까지 실행 (권장)** |
+| **`/reap.pull <branch>`** | **Fetch + 전체 머지 Generation 실행 (분산 `/reap.evolve`)** |
+| **`/reap.merge <branch>`** | **로컬 브랜치 전체 머지 Generation 실행 (fetch 없음)** |
+| `/reap.push` | REAP 상태 검증 후 현재 브랜치 push |
+| `/reap.merge.start` | 분기 브랜치를 결합하는 머지 Generation 시작 |
+| `/reap.merge.detect` | 브랜치 간 분기 분석 |
+| `/reap.merge.mate` | 소스 머지 전 Genome 충돌 해결 |
+| `/reap.merge.merge` | 해결된 Genome을 기준으로 소스 코드 머지 |
+| `/reap.merge.sync` | Genome-소스 간 일관성 검증 (AI 비교, 사용자 확인) |
+| `/reap.merge.validation` | 기계적 테스트 실행 (bun test, tsc, build) |
+| **`/reap.merge.evolve`** | **전체 머지 라이프사이클 자동 실행** |
 
 ### SessionStart Hook
 
@@ -202,24 +279,30 @@ Slash command가 `.claude/commands/`에 설치되어 전체 워크플로우를
 
 ### Strict 모드
 
-`.reap/config.yml`에 `strict: true`를 설정하면 AI 에이전트가 REAP 워크플로우 외부에서 코드를 수정하는 것을 제한합니다:
+Strict 모드는 AI 에이전트가 할 수 있는 것을 제어합니다. 두 가지 세분화 옵션을 지원합니다:
 
 ```yaml
 # .reap/config.yml
-strict: true      # 기본값: false
-language: korean  # 산출물 및 상호작용 언어
-autoUpdate: true  # 세션 시작 시 자동 업데이트
-agents:           # 감지된 에이전트 (reap init/update에서 관리)
-  - claude-code
-  - opencode
+strict: true              # 단축형: edit과 merge 모두 활성화
+
+# 또는 세분화 제어:
+strict:
+  edit: true              # 코드 수정을 REAP lifecycle으로 제한
+  merge: false            # raw git pull/push/merge 제한
 ```
 
+**`strict.edit`** — 코드 수정 제어:
+
 | 상황 | 동작 |
 |------|------|
 | 활성 Generation 없음 / 구현 단계 외 | 코드 수정 완전 차단 |
 | Implementation 단계 | `02-planning.md` 범위 내에서만 수정 허용 |
 | Escape hatch | 사용자가 "override", "bypass strict" 등 명시적 요청 시 허용 |
 
+**`strict.merge`** — Git 명령 제어: 활성화 시 `git pull`/`push`/`merge` 직접 사용이 제한됩니다. 에이전트가 `/reap.pull`, `/reap.push`, `/reap.merge` 사용을 안내합니다.
+
+두 옵션 모두 기본 비활성화. `strict: true`는 둘 다 활성화합니다.
+
 Strict 모드는 기본적으로 비활성화되어 있습니다 (`strict: false`).
 
 ### REAP Hooks
@@ -253,6 +336,9 @@ order: 10                     # 실행 순서 (낮을수록 먼저 실행)
 | `onStageTransition` | `/reap.next`로 다음 stage 전진 후 |
 | `onGenerationComplete` | `/reap.next`로 완료된 Generation 아카이빙 후 |
 | `onRegression` | `/reap.back`으로 이전 stage 복귀 후 |
+| `onMergeStart` | `/reap.merge.start`로 머지 Generation 생성 후 |
+| `onGenomeResolved` | 머지 중 Genome 충돌 해결 완료 후 |
+| `onMergeComplete` | 머지 Generation 아카이빙 후 |
 
 Hook은 AI 에이전트가 프로젝트 루트 디렉토리에서 실행합니다. `onGenerationComplete` Hook에는 자동 버전 범프 판단이 포함되어 있습니다 — patch 수준은 자동으로 적용되고, minor/major 범프는 사용자 확인을 거칩니다.
 

package/README.md

@@ -1,3 +1,5 @@
+> [한국어](README.ko.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)
+
 <p align="center">
   <img src="media/logo.png" alt="REAP" width="80" height="80" />
 </p>
@@ -9,8 +11,6 @@
   A development pipeline where AI and humans evolve software across generations.
 </p>
 
-> [한국어](README.ko.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)
-
 <table align="center">
 <tr>
 <td align="center"><strong>Genome</strong><br><sub>Design & Knowledge</sub></td>
@@ -23,6 +23,22 @@
 
 REAP defines an application's genetic information (Genome), sets objectives for each generation to implement, and feeds back any Genome defects discovered along the way into subsequent stages. As generations accumulate, the Genome evolves and the Source Code (Civilization) grows.
 
+## Table of Contents
+
+- [Why REAP?](#why-reap)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Life Cycle](#life-cycle)
+- [Core Concepts](#core-concepts)
+- [Distributed Workflow for Parallel Development](#distributed-workflow-for-parallel-development)
+- [CLI Commands](#cli-commands)
+- [Agent Integration](#agent-integration)
+- [Project Structure](#project-structure-after-reap-init)
+- [Lineage Compression](#lineage-compression)
+- [Evolution Flow](#evolution-flow)
+- [Presets](#presets)
+- [Entry Modes](#entry-modes)
+
 ## Why REAP?
 
 Have you ever run into these problems when developing with AI agents?
@@ -31,6 +47,7 @@ Have you ever run into these problems when developing with AI agents?
 - **Scattered development** — Code gets modified here and there with no clear goal
 - **Design–code drift** — Documentation and code diverge over time
 - **Forgotten lessons** — Hard-won insights from past struggles never carry forward
+- **Collaboration chaos** — Multiple developers or agents working in parallel leads to conflicting changes and merge nightmares
 
 REAP solves these with a **generation-based evolution model**:
 
@@ -39,6 +56,7 @@ REAP solves these with a **generation-based evolution model**:
 - Design issues discovered during implementation are logged in the backlog and addressed at Completion
 - Lessons drawn from retrospectives (Completion) accumulate in the Genome
 - Repeated manual tasks are automatically detected across generations, with user-confirmed hook creation
+- Parallel work across branches is reconciled through a genome-first merge workflow — design conflicts are resolved before code conflicts
 
 ## Installation
 
@@ -93,7 +111,7 @@ Objective → Planning → Implementation ⟷ Validation → Completion
 
 | Stage | What happens | Artifact |
 |-------|-------------|----------|
-| **Objective** | Define goal, requirements, and acceptance criteria | `01-objective.md` |
+| **Objective** | Define goal through structured brainstorming: clarifying questions, 2-3 approach alternatives, sectional design approval, optional visual companion, and spec review loop | `01-objective.md` |
 | **Planning** | Break down tasks, choose approach, map dependencies | `02-planning.md` |
 | **Implementation** | Build with AI + human collaboration | `03-implementation.md` |
 | **Validation** | Run tests, verify completion criteria | `04-validation.md` |
@@ -145,6 +163,55 @@ At archiving time (`/reap.next` from Completion), `consumed` items move to linea
 └── lineage/       # Archive of completed generations
 ```
 
+## Distributed Workflow for Parallel Development
+
+> **⚠ Early Stage** — The distributed workflow requires further testing. Use with caution in production. We're collecting feedback — [open an issue](https://github.com/c-d-cc/reap/issues).
+
+REAP supports a distributed workflow for collaboration environments where multiple developers or AI agents work on the same project in parallel — without a central server. Git is the only transport layer.
+
+### How It Works
+
+```
+Machine A: branch-a — gen-046-a (authentication)    → /reap.push
+Machine B: branch-b — gen-046-b (search)            → /reap.push
+
+Machine A:
+  /reap.pull branch-b   → Fetch + full merge generation lifecycle
+```
+
+Each machine works independently on its own branch and generation. When it's time to combine, REAP orchestrates the merge with a **genome-first** strategy ([learn more](https://reap.cc/docs/merge-generation)):
+
+1. **Detect** — Identify divergence by scanning the remote branch's genome and lineage via git refs
+2. **Mate** — Resolve genome conflicts first (human decides)
+3. **Merge** — Merge source code guided by the finalized genome (`git merge --no-commit`)
+4. **Sync** — AI compares genome and source for consistency; user confirms any inconsistencies
+5. **Validation** — Run mechanical testing (bun test, tsc, build) — same as normal generation
+6. **Completion** — Commit the merged result and archive
+
+### Slash Commands for Distributed Workflow
+
+All distributed operations run through your AI agent:
+
+```bash
+/reap.pull <branch>        # Fetch + run full merge generation (the distributed /reap.evolve)
+/reap.merge <branch>       # Run full merge generation for a local branch (no fetch)
+/reap.push                 # Validate REAP state + push current branch
+/reap.merge.start          # Start a merge generation (for step-by-step control)
+/reap.merge.detect         # Analyze divergence
+/reap.merge.mate           # Resolve genome conflicts
+/reap.merge.merge          # Merge source code
+/reap.merge.sync           # Verify genome–source consistency
+/reap.merge.validation     # Run mechanical testing (bun test, tsc, build)
+/reap.merge.evolve         # Run merge lifecycle from current stage
+```
+
+### Key Principles
+
+- **Opt-in** — `git pull`/`push` always work normally. REAP commands are additive.
+- **Genome-first** — Genome conflicts are resolved before source merge. Like amending the constitution before updating the laws.
+- **No server** — Everything is local + Git. No external services.
+- **DAG lineage** — Each generation references its parents via a hash-based ID (`gen-046-a3f8c2`), forming a directed acyclic graph that naturally supports parallel work.
+
 ## CLI Commands
 
 | Command | Description |
@@ -186,6 +253,16 @@ Slash commands are installed in `.claude/commands/` and drive the entire workflo
 | `/reap.help` | Contextual AI help with 24+ topics (workflow, genome, backlog, strict, agents, hooks, config, evolve, regression, author, and all command names) |
 | `/reap.update` | Check for REAP updates and upgrade to the latest version |
 | **`/reap.evolve`** | **Run an entire generation from start to finish (recommended)** |
+| **`/reap.pull <branch>`** | **Fetch + run full merge generation (distributed `/reap.evolve`)** |
+| **`/reap.merge <branch>`** | **Run full merge generation for a local branch (no fetch)** |
+| `/reap.push` | Validate REAP state and push current branch |
+| `/reap.merge.start` | Start a merge generation to combine divergent branches |
+| `/reap.merge.detect` | Analyze divergence between branches |
+| `/reap.merge.mate` | Resolve genome conflicts before source merge |
+| `/reap.merge.merge` | Merge source code with resolved genome as guide |
+| `/reap.merge.sync` | Verify genome–source consistency (AI compares, user confirms) |
+| `/reap.merge.validation` | Run mechanical testing (bun test, tsc, build) |
+| **`/reap.merge.evolve`** | **Run the full merge lifecycle automatically** |
 
 ### SessionStart Hook
 
@@ -201,24 +278,30 @@ This ensures the agent immediately understands the project context even in a bra
 
 ### Strict Mode
 
-When `strict: true` is set in `.reap/config.yml`, the AI agent is restricted from modifying code outside the REAP workflow:
+Strict mode controls what the AI agent is allowed to do. It supports two granular options:
 
 ```yaml
 # .reap/config.yml
-strict: true      # default: false
-language: korean  # language for artifacts and interactions
-autoUpdate: true  # auto-update REAP on session start
-agents:           # detected agents (managed by reap init/update)
-  - claude-code
-  - opencode
+strict: true              # shorthand: enables both edit and merge
+
+# Or granular control:
+strict:
+  edit: true              # restrict code changes to REAP lifecycle
+  merge: false            # restrict raw git pull/push/merge
 ```
 
+**`strict.edit`** — Code modification control:
+
 | Context | Behavior |
 |---------|----------|
 | No active generation / non-implementation stage | Code modifications are fully blocked |
 | Implementation stage | Only modifications within the scope of `02-planning.md` are allowed |
 | Escape hatch | User explicitly requests "override" or "bypass strict" to allow modifications |
 
+**`strict.merge`** — Git command control: when enabled, direct `git pull`/`push`/`merge` are restricted. The agent guides users to use `/reap.pull`, `/reap.push`, `/reap.merge` instead.
+
+Both are disabled by default. `strict: true` enables both.
+
 Strict mode is disabled by default (`strict: false`).
 
 ### REAP Hooks
@@ -252,6 +335,9 @@ order: 10                     # execution order (lower runs first)
 | `onStageTransition` | After `/reap.next` advances to the next stage |
 | `onGenerationComplete` | After `/reap.next` archives a completed generation |
 | `onRegression` | After `/reap.back` returns to a previous stage |
+| `onMergeStart` | After `/reap.merge.start` creates a merge generation |
+| `onGenomeResolved` | After genome conflicts are resolved in a merge |
+| `onMergeComplete` | After a merge generation is archived |
 
 Hooks are executed by the AI agent in the project root directory. The `onGenerationComplete` hooks include automatic version bump judgment — patch-level bumps are applied automatically, while minor/major bumps require user confirmation.