データモデル
Nolto ではリポジトリ内の .nolto/roadmaps/<slug>.json が進捗の正本です。slug はファイル名から決まり、1つのリポジトリに複数の roadmap を置けます。サーバーは同期されたスナップショット、集計値、関連文書、生成済みの表示用 artifact を保持します。
Project
project は roadmap の共有範囲と権限の単位です。
| field | 型 | 説明 |
|---|---|---|
id | UUID | Nolto project ID |
name | string | 表示名 |
repository_url | string? | Git repository URL |
org_id | UUID? | organization project の場合に設定 |
リポジトリ側の nolto.json が project ID を保持します。roadmap slug は .nolto/roadmaps/ 内の JSON ファイル名です。
Roadmap
{
"schemaVersion": 2,
"project": {
"id": "my-app",
"name": "My App",
"repository": "https://github.com/example/my-app"
},
"updatedAt": "2026-08-04T10:00:00Z",
"currentTaskId": "auth-2",
"summary": "認証改善を進行中",
"phases": []
}
| field | 型 | 説明 |
|---|---|---|
schemaVersion | 1 | 2 | 現行は 2。version 1 は次回更新時に移行対象 |
project | object | リポジトリ内で使う project metadata |
updatedAt | date-time | 競合判定に使う最終更新時刻 |
currentTaskId | string? | 現在進行中の task ID |
summary | string | リポジトリ側の短い説明 |
phases | Phase[] | phase の配列 |
サーバーは task_total、task_done、task_blocked を payload から再計算します。
Phase
| field | 型 | 説明 |
|---|---|---|
id | string | roadmap 内で一意の ID |
title | string | phase 名 |
status | RoadmapStatus | task 状態から導出される状態 |
plan | string? | repository-relative な Markdown path |
tasks | Task[] | task の配列 |
phase status は task から導出されます。すべて完了なら done、進行中があれば in-progress、blocked のみがあれば blocked、着手前なら todo です。
Task
| field | 型 | 説明 |
|---|---|---|
id | string | roadmap 内で一意の ID |
title | string | task 名 |
status | RoadmapStatus | 現在の状態 |
startedAt | date-time? | 着手時刻 |
completedAt | date-time? | 完了時刻 |
note | string? | 短いメモ |
dependsOn | string[]? | 依存 task ID |
plan | string? | repository-relative な Markdown path |
RoadmapStatus は todo、in-progress、done、blocked の4種類です。
Plan document
Phase または Task の plan が参照する Markdown を CLI が読み込み、roadmap と同時に同期します。
| field | 説明 |
|---|---|
path | repository-relative path |
task_id | 文書を参照した phase または task ID |
content | Markdown 本文 |
content_hash | sha256: 付き content hash |
render_status | 整形処理の状態（success / failed / 未生成） |
render_payload | 検証済みの Plan UI blocks JSON |
render_source_hash | artifact 生成時の content hash |
同じ path の content hash が変わると既存 artifact は無効化され、再生成対象になります。
プラン表示
worker は plan document を個別に claim し、最大3回まで整形を試みます。render_status が success で render_payload の検証に成功すると、プラン画面で整形ビューと Markdown を切り替えられます。処理中は生成中の案内を表示し、失敗または不正な artifact の場合は Markdown 原文を表示します。
Git 上の roadmap が正本です。Web UI は同期結果を表示し、リポジトリ側の進捗ファイルを書き戻しません。