golem15/msd-core
4
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rebrand to GSD Core and restructure docs with Diataxis (#605)

Browse Source 
* chore: wire docs/agents config into AGENTS.md Agent skills section

Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: rebrand to GSD Core and restructure docs with Diataxis

Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: backfill changeset PR number (#605)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-06-02 08:13:09 -04:00
committed by GitHub
parent 8c47dcb1c1
commit 3bb2f8f1c5
200 changed files with 46813 additions and 8415 deletions
Download Patch File Download Diff File Expand all files Collapse all files

148
docs/ja-JP/reference/context-md.md Normal file
View File

@@ -0,0 +1,148 @@
# CONTEXT.md スキーマリファレンス
フェーズごとの `CONTEXT.md` は、`/gsd:discuss-phase` 中に収集された実装上の意思決定を格納する GSD Core のキャリアファイルです。リサーチエージェントとプランニングエージェントの両方にとって主要な上流インプットです。このページではそのスキーマを説明します。[ドキュメントインデックス](../../README.md) も参照してください。
---
## 概要
ディスカッションワークフローを経たすべてのフェーズは、以下のパスに `CONTEXT.md` を1つ生成します：
```
.planning/phases/<NN>-<slug>/<NN>-CONTEXT.md
```
例: `.planning/phases/03-post-feed/03-CONTEXT.md`
このファイルは `get-shit-done/workflows/discuss-phase.md` の `write_context`（または PRD / ADR インジェストのエクスプレスパス）によって生成されます。通常の運用中は手動で編集されません — discuss-phase ワークフローが書き込み、下流エージェントが封印された信頼できる情報源として読み取ります。
---
## フロントマター
`CONTEXT.md` は YAML フロントマターを持ちません。メタデータは本文の先頭にインラインで記述されます：
```markdown
# Phase [X]: [Name] - Context
**Gathered:** [ISO date]
**Status:** Ready for planning
```
`Status` フィールドはファイル初回書き込み時に常に `Ready for planning` です。作成後は更新されません。
---
## ブロック構造
本文は名前付きの XML スタイルブロックに分割されています。ブロックは固定の順序で登場し、下流エージェントは行番号ではなくブロック名で読み取ります。
| ブロック | 用途 | 設定元 | 参照先 |
|---|---|---|---|
| `<domain>` | フェーズの境界を示します — このフェーズが何を提供し、何が明示的にスコープ外かを述べます。プランニングと実行を通じてスコープガードレールを固定します。 | `discuss-phase`（ROADMAP.md のフェーズゴールから） | `gsd-planner`、`gsd-plan-checker`（スコープ準拠） |
| `<spec_lock>` | `check_spec` ステップが `*-SPEC.md` を発見した場合のみ存在します。ロックされた要件数とスコープ境界をリストします。エージェントは完全な要件を得るために直接 `SPEC.md` を読むよう指示されます。 | `discuss-phase`（条件付き） | `gsd-planner`（要件をここで再読みせず SPEC.md を読む） |
| `<decisions>` | ディスカッションから収集された実装上の意思決定。`D-NN` 識別子でキー付け。カテゴリは固定の分類ではなく実際に議論された内容から生まれます。ユーザーが委任した領域のための `Claude's Discretion` サブセクションを含みます。 | `discuss-phase`（インタラクティブなディスカッション） | `gsd-planner`（ロックされた決定は必ず実装する）、`gsd-plan-checker`（ディメンション7準拠） |
| `<canonical_refs>` | このフェーズに関連するすべての仕様、ADR、機能ドキュメント、設計ドキュメントへの完全な相対パス。必須 — すべての CONTEXT.md にこのセクションが必要です。エージェントはプランニングまたは実装の前にリストされたファイルを読む必要があります。 | `discuss-phase`（ROADMAP.md の参照 + ディスカッション中のユーザー参照 + コードベーススカウトから集積） | `gsd-phase-researcher`、`gsd-planner` |
| `<code_context>` | `scout_codebase` ステップで発見された再利用可能なアセット、確立されたパターン、統合ポイント。エージェントを再実装ではなく既存コードに向けるためのガイダンス。 | `discuss-phase`（コードベーススカウト） | `gsd-planner`、`gsd-phase-researcher` |
| `<specifics>` | ディスカッション中に verbatim で収集された「こんな感じにしたい」という具体的な参照、製品比較、特定の例。 | `discuss-phase`（自由形式のユーザー入力） | `gsd-planner` |
| `<deferred>` | ディスカッション中に浮上したが別のフェーズに属するアイデア。失われないよう保存されます。Todos がレビューされたがスコープに含まれなかった場合は `Reviewed Todos` サブセクションを含みます。 | `discuss-phase`（スコープクリープのリダイレクト） | 自動化されたエージェントには使用されない; 人間の参照のみ |
---
## 意思決定識別子フォーマット
`<decisions>` 内のすべての意思決定は連番の `D-NN` 識別子を持ちます：
```markdown
### Layout style
- **D-01:** Card-based layout, not timeline or list
- **D-02:** Each card shows: author avatar, name, timestamp, full post content, reaction counts
```
識別子はフェーズにスコープされます。フェーズ3の `D-01` はフェーズ7の `D-01` とは無関係です。プランチェッカー（ディメンション7）は、すべての `D-NN` が生成されたプランの少なくとも1つのタスクアクションによって対処されていることを検証します。
---
## Canonical references
`<canonical_refs>` ブロックは **必須** です。不在の場合、エージェントは CONTEXT.md が不完全であるとみなし警告を表示します。エントリはトピックごとにグループ化され、完全な相対パスとファイルが決定または定義する内容の簡単な説明を含みます：
```markdown
<canonical_refs>
## Canonical References
**Downstream agents MUST read these before planning or implementing.**
### Feed display
- `docs/features/social-feed.md` — Feed requirements, post card fields, engagement display rules
- `docs/decisions/adr-012-infinite-scroll.md` — Scroll strategy decision, virtualisation requirements
### Empty states
- `docs/design/empty-states.md` — Empty state patterns, illustration guidelines
</canonical_refs>
```
プロジェクトに外部仕様がない場合は、このセクションでそれを明示します：
```
No external specs — requirements fully captured in decisions above
```
`<decisions>` 内に散在する「ADR-019 を参照」などのインラインメンションは不十分です。エージェントには専用セクションに完全なパスが必要です。
---
## Decision Coverage Gate との関係
プランチェッカーの **ディメンション7: Context Compliance** はプランニング後にカバレッジゲートを強制します：
1. `<decisions>` 内のすべての `D-NN` 識別子は、少なくとも1つのプランタスクの `<action>` または根拠に登場する必要があります。
2. `<deferred>` にリストされているものをタスクが実装してはなりません（スコープクリープ）。
3. `Claude's Discretion` 領域はこのチェックから免除されます — プランナーは自由に選択できます。
意思決定がプランに反映されている CONTEXT.md は準拠とみなされます。意思決定が暗黙的に削除されたり部分的にしか実現されていない CONTEXT.md は **ディメンション7b: Scope Reduction Detection** をトリガーし、常に BLOCKER となります。
---
## SPEC.md との統合
フェーズをディスカッションする前に `/gsd:spec-phase` が実行された場合、`check_spec` ステップが `*-SPEC.md` ファイルを見つけ `<spec_lock>` を有効にします：
```markdown
<spec_lock>
## Requirements (locked via SPEC.md)
**12 requirements are locked.** See `03-SPEC.md` for full requirements, boundaries, and acceptance criteria.
Downstream agents MUST read `03-SPEC.md` before planning or implementing. Requirements are not duplicated here.
**In scope (from SPEC.md):** [copied from SPEC.md Boundaries]
**Out of scope (from SPEC.md):** [copied from SPEC.md Boundaries]
</spec_lock>
```
`<spec_lock>` が存在する場合、`<decisions>` にはディスカッションからの実装上の意思決定のみが含まれます — 「何を作るか」ではなく「どのように作るか」です。要件は2つのファイル間で重複しません。
---
## フッター
すべての CONTEXT.md はアイデンティティフッターで終わります：
```markdown
---
*Phase: XX-name*
*Context gathered: [date]*
```
---
## Related
- [PLAN.md スキーマ](plan-md.md)
- [Planning artifacts](planning-artifacts.md)
- [Discuss modes](../../workflow-discuss-mode.md)
- [docs index](../../README.md)

249
docs/ja-JP/reference/plan-md.md Normal file
View File

@@ -0,0 +1,249 @@
# PLAN.md スキーマリファレンス
フェーズごとの `PLAN.md` は GSD Core の実行可能な作業単位です — エグゼキューターエージェントに何を構築し、正しく構築されたことをどのように検証するかを正確に伝える構造化ドキュメントです。このページではそのスキーマを説明します。[ドキュメントインデックス](../../README.md) も参照してください。
---
## 概要
プランはフェーズディレクトリ内の以下のパスに保存されます：
```
.planning/phases/<NN>-<slug>/<NN>-<PP>-PLAN.md
```
例: `.planning/phases/03-post-feed/03-02-PLAN.md`（フェーズ3、プラン2）。
プランは `gsd-planner` エージェント（`/gsd:plan-phase` によって起動）が生成し、`execute-phase` が使用します。通常、フェーズには1〜4つのプランが含まれます。フェーズ内のプランは実行ウェーブに割り当てられ、独立した作業が並行して実行されます。
---
## YAML フロントマター
すべての PLAN.md は `---` デリミタの間にある YAML フロントマターブロックで始まります。
### 注釈付きサンプル
```yaml
---
phase: 03-post-feed
plan: 02
type: execute
wave: 2
depends_on: ["03-01"]
files_modified:
- src/components/PostFeed.tsx
- src/components/PostCard.tsx
- src/app/feed/page.tsx
autonomous: true
requirements: ["FEED-01", "FEED-03"]
user_setup: []
must_haves:
truths:
- "User can scroll through posts from followed accounts"
- "Each post shows author avatar, name, timestamp, and content"
- "Empty state appears when no posts exist"
artifacts:
- path: "src/components/PostFeed.tsx"
provides: "Scrollable post list"
min_lines: 40
- path: "src/components/PostCard.tsx"
provides: "Individual post card"
exports: ["PostCard"]
key_links:
- from: "src/components/PostFeed.tsx"
to: "/api/feed"
via: "fetch in useEffect"
pattern: "fetch.*api/feed"
---
```
### フロントマターフィールドリファレンス
| フィールド | 必須 | 型 | 用途 |
|---|---|---|---|
| `phase` | はい | string | フェーズ識別子。例: `03-post-feed`。 |
| `plan` | はい | string | フェーズ内のプラン番号。例: `02`。 |
| `type` | はい | `execute` または `tdd` | 標準プランは `execute`; テスト駆動プラン（実装前にテストを書く）は `tdd`。 |
| `wave` | はい | integer | 実行ウェーブ。ウェーブ1のプランは並行実行されます（依存なし）。ウェーブ2以降のプランは前のウェーブのすべてのプランが完了するまで待機します。`gsd-planner` がプランニング時に事前計算します。 |
| `depends_on` | はい | プラン ID の配列 | このプランが待機する必要があるプランの一覧。空配列 = ウェーブ1。例: `["03-01"]` はこのプランがフェーズ3のプラン01の後に実行されることを意味します。 |
| `files_modified` | はい | パスの配列 | このプランが作成または変更するすべてのファイル。プランチェッカーが同一ウェーブのファイル競合を検出するため、および execute-phase がマージ追跡のために使用します。 |
| `autonomous` | はい | boolean | すべてのタスクが `auto` タイプの場合に `true`。プランに人間の操作が必要な `checkpoint:*` タスクが含まれる場合は `false`。 |
| `requirements` | はい | ID の配列 | このプランが対処する ROADMAP.md の要件 ID。すべてのフェーズ要件 ID は少なくとも1つのプランの `requirements` フィールドに登場する必要があります。空配列は BLOCKER です。 |
| `user_setup` | いいえ | オブジェクトの配列 | Claude が自動化できない外部サービスのセットアップ手順（アカウント作成、シークレット取得、ダッシュボード設定など）。存在する場合、execute-phase は開発者向けに `USER-SETUP.md` チェックリストを生成します。 |
| `must_haves` | はい | object | ゴール逆引き型の検証基準。以下を参照。 |
---
## `must_haves` フィールド
`must_haves` はフェーズゴールを達成するために観察可能に真でなければならないことを記録します。プランニング中に導出され、実行後に `gsd-verifier` エージェントによって検証されます。
### サブフィールド
| サブフィールド | 型 | 用途 |
|---|---|---|
| `truths` | 文字列の配列 | ユーザーの視点からの観察可能な動作。それぞれが検証可能でなければなりません。例: `"User can send a message"`（`"WebSocket library installed"` は不可）。 |
| `artifacts` | オブジェクトの配列 | 実質的な実装（スタブではなく）で存在しなければならないファイル。 |
| `artifacts[].path` | string | プロジェクトルートからの相対ファイルパス。 |
| `artifacts[].provides` | string | このファイルが提供する機能。 |
| `artifacts[].min_lines` | integer（オプション） | スタブではないとみなす最小行数。 |
| `artifacts[].exports` | 文字列の配列（オプション） | 検証すべき期待される名前付きエクスポート。 |
| `artifacts[].contains` | string（オプション） | ファイルに存在しなければならない正規表現またはリテラルパターン。 |
| `key_links` | オブジェクトの配列 | アーティファクト間の重要な接続 — システムをエンドツーエンドで機能させる配線。 |
| `key_links[].from` | string | ソースファイルまたはコンポーネント。 |
| `key_links[].to` | string | ターゲットファイル、エンドポイント、またはモジュール。 |
| `key_links[].via` | string | 接続方法の説明（例: `fetch in useEffect`、`Prisma query`、`import`）。 |
| `key_links[].pattern` | string（オプション） | ソース内に接続が存在することを検証する正規表現。 |
---
## 本文構造
フロントマターの後、プラン本文はエグゼキューターエージェントが読み取る名前付き XML スタイルブロックを使用します。
### `<objective>`
プランが提供するものとプロジェクトにとっての重要性を述べます：
```xml
<objective>
Implement the post feed as a scrollable card list.
Purpose: Core display feature for the social feed phase.
Output: PostFeed and PostCard components wired to /api/feed.
</objective>
```
### `<execution_context>`
エグゼキューターが開始前に読むワークフローファイルの一覧。常に execute-plan ワークフローを含み、プランにチェックポイントタスクがある場合はチェックポイントリファレンスを追加します：
```xml
<execution_context>
@~/.claude/get-shit-done/workflows/execute-plan.md
@~/.claude/get-shit-done/templates/summary.md
</execution_context>
```
### `<context>`
エグゼキューターが読む必要があるソースファイルの参照。プロジェクトレベルのプランニングドキュメントと、プランが複製しなければならないパターンや型を持つすべてのソースファイルを含みます。同じフェーズの以前のプランの `SUMMARY.md` は、型や共有された意思決定への真の依存がある場合のみ含めます — 反射的には含めません：
```xml
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@src/components/UserCard.tsx
</context>
```
### `<tasks>`
1つ以上の `<task>` 要素を含みます。`type="auto"` タスクのすべてのタスク要素には `<name>`、`<files>`、`<read_first>`、`<action>`、`<verify>`、`<acceptance_criteria>`、`<done>` が必要です。
---
## タスクタイプ
| タイプ | 用途 | 自律性 |
|---|---|---|
| `auto` | エグゼキューターが独立して実行できるすべて。 | 完全自律。 |
| `checkpoint:human-verify` | 人間が実行中の UI やサービスを確認する必要があるビジュアルまたは機能的な検証。 | 実行を一時停止して開発者に提示; 承認後に再開。 |
| `checkpoint:decision` | 実行中に浮上し開発者の入力が必要な実装上の選択。 | 実行を一時停止してオプションを提示; 選択後に再開。 |
| `checkpoint:human-action` | 真に避けられない手動ステップ（アカウント作成、ハードウェア操作）。控えめに使用。 | 実行を一時停止して確認後に再開。 |
チェックポイントタスクが含まれるプランはフロントマターに `autonomous: false` を設定する必要があります。
---
## `auto` タスク構造
```xml
<task type="auto">
<name>Task 1: Create PostCard component</name>
<files>src/components/PostCard.tsx</files>
<read_first>src/components/UserCard.tsx, src/types/post.ts</read_first>
<action>Create PostCard component accepting a Post prop (id, authorId, content, createdAt,
reactionCount). Render author avatar using UserAvatar from UserCard pattern. Show timestamp
using date-fns formatDistanceToNow. Export as named export PostCard.</action>
<verify>npx tsc --noEmit</verify>
<acceptance_criteria>
- src/components/PostCard.tsx exports named export PostCard
- PostCard.tsx contains "reactionCount" prop usage
- npx tsc --noEmit exits 0
</acceptance_criteria>
<done>PostCard renders post content with author and timestamp</done>
</task>
```
### `auto` タスクの必須フィールド
| フィールド | ルール |
|---|---|
| `<files>` | タスクが作成または変更するすべてのファイル。エグゼキューターはこれらのファイルのみを書き込みます。 |
| `<read_first>` | エグゼキューターが何かに触れる前に読まなければならないファイル — 変更するファイル、信頼できる参照パターンファイル、型や規則を複製しなければならないすべてのファイル。 |
| `<action>` | 正確な識別子、ファイルパス、関数シグネチャ、期待される値を含む具体的な指示。ターゲット状態を指定せずに「X を Y に合わせる」とは言いません。フェンスされたコードブロックや完全な実装を含みません。 |
| `<verify>` | タスクが成功したことを証明する実行可能なコマンドまたはチェック。合格と不合格を区別できなければなりません — `echo "done"` は無効です。 |
| `<acceptance_criteria>` | 検証可能な条件: grep で検証可能な文字列、コマンドの終了コード、観察可能な動作。主観的な言語（「正しく見える」、「適切に設定されている」）は使用しません。 |
| `<done>` | 完了した成果の短い測定可能な説明。 |
---
## プラン品質ディメンション
`gsd-plan-checker` エージェントは実行開始前に12のディメンションにわたってすべての PLAN.md をレビューします。BLOCKER 深刻度のチェックに失敗したプランは `gsd-planner` に差し戻されます（最大3回のイテレーション）：
| ディメンション | チェック内容 |
|---|---|
| **1 — Requirement Coverage** | ROADMAP.md からのすべてのフェーズ要件 ID が少なくとも1つのプランの `requirements` フロントマターフィールドに登場し、対応するタスクがある。 |
| **2 — Task Completeness** | すべての `auto` タスクが必須フィールド（`<files>`、`<action>`、`<verify>`、`<acceptance_criteria>`、`<done>`）を持つ。曖昧なフィールドや空のフィールドがない。 |
| **3 — Dependency Correctness** | `depends_on` の参照が有効で非循環かつウェーブ番号と整合している。ウェーブ N のプランはウェーブ < N のプランのみに依存する。 |
| **4 — Key Links Planned** | `must_haves.key_links` のアーティファクトに、アーティファクトの作成だけでなく配線を実装する対応するタスクがある。 |
| **5 — Scope Sanity** | プランはコンテキスト予算内に収まる: プランあたり2〜3タスク（4 = 警告、5以上 = BLOCKER）、プランあたり8〜10ファイル以下（15以上 = BLOCKER）。 |
| **6 — Verification Derivation** | `must_haves.truths` は実装の詳細ではなくユーザー観察可能な動作。アーティファクトが truths にマッピングされる。key links が重要な配線をカバーする。 |
| **7 — Context Compliance** | CONTEXT.md のすべての `D-NN` 決定が少なくとも1つのタスクによって対処されている。`<deferred>` にあるものをタスクが実装していない。 |
| **7b — Scope Reduction Detection** | タスクアクションが、完全な決定スコープを提供せずにロックされた決定を暗黙的に「v1」、「スタブ」、または「将来の強化」に縮小していない。発見された場合は常に BLOCKER。 |
| **7c — Architectural Tier Compliance** | タスクが RESEARCH.md の Architectural Responsibility Map（存在する場合）に従って正しいティアに機能を割り当てている。誤ったティアのセキュリティ機密機能は BLOCKER。 |
| **8 — Nyquist Compliance** | `workflow.nyquist_validation` が有効で RESEARCH.md が存在する場合、すべてのタスクに `<automated>` 検証コマンドがあり、連続する3タスクのウィンドウにカバレッジがなく、VALIDATION.md が存在する。 |
| **9 — Cross-Plan Data Contracts** | プランがデータパイプラインを共有する場合、それらの変換が互換性を持つ — 別のプランが元の形式で必要とするデータをプランが削除しない。 |
| **10 — CLAUDE.md Compliance** | プランが `./CLAUDE.md` のプロジェクト固有の規則、禁止パターン、必須ツール、セキュリティ要件を遵守している。 |
| **11 — Research Resolution** | RESEARCH.md が存在する場合、プランニングを進める前にその `## Open Questions` セクションが `(RESOLVED)` とマークされている。 |
| **12 — Pattern Compliance** | PATTERNS.md が存在する場合、タスクが新規または変更される各ファイルに対して正しいアナログパターンを参照している。 |
---
## ウェーブ実行モデル
ウェーブ番号はプランニング中に事前計算されます。Execute-phase はウェーブ番号でプランをグループ化し、各ウェーブのプランを並行して実行します：
```
Wave 1: Plan 01, Plan 02, Plan 03 (すべて同時実行 — 依存なし)
Wave 2: Plan 04 (Wave 1 完了を待機)
Wave 3: Plan 05 (Wave 2 完了を待機)
```
同一ウェーブ内で重複するファイルを変更するプランは同じウェーブに入れてはなりません — プランチェッカーのディメンション3がこれを BLOCKER としてフラグします。
---
## プラン出力
プランが正常に実行された後、エグゼキューターは以下のパスに SUMMARY.md を書き込みます：
```
.planning/phases/<NN>-<slug>/<NN>-<PP>-SUMMARY.md
```
SUMMARY.md は何が構築されたかの正規の記録です。同じフェーズの後続プランは、型や意思決定への真の依存がある場合にのみそれを参照できます。
---
## Related
- [CONTEXT.md スキーマ](context-md.md)
- [Planning artifacts](planning-artifacts.md)
- [Features](../../FEATURES.md)
- [docs index](../../README.md)

225
docs/ja-JP/reference/planning-artifacts.md Normal file
View File

@@ -0,0 +1,225 @@
# プランニングアーティファクト リファレンス
`.planning/` ディレクトリはプロジェクトの GSD Core 共有メモリです。すべてのワークフローはここから読み取り、書き込み、意思決定の監査可能な証跡を残します。このページではすべてのファイル、その目的、どのコマンドが生成・使用するかをマッピングします。[ドキュメントインデックス](../../README.md) も参照してください。
---
## ディレクトリ構造
```
.planning/
├── PROJECT.md # プロジェクトのアイデンティティとコアバリュー
├── ROADMAP.md # マイルストーン + フェーズ一覧とゴール
├── REQUIREMENTS.md # 番号付きの受け入れ基準
├── STATE.md # 現在地を追跡するリビングドキュメント
├── config.json # ワークフローとモデルの設定
├── MILESTONES.md # マイルストーンアーカイブ（オプション）
├── BACKLOG.md # 延期および将来の作業（オプション）
├── LEARNINGS.md # 蓄積されたフェーズ横断の学習（オプション）
├── DECISIONS-INDEX.md # 過去の意思決定のローリングサマリー（オプション）
├── METHODOLOGY.md # 再利用可能な解釈フレームワーク（オプション）
├── HANDOFF.json # 機械可読な一時停止状態（一時的）
├── codebase/ # コードベースマップ（オプション）
│ ├── architecture.md
│ ├── stack.md
│ └── ...
├── intel/ # クエリ可能なシンボルインデックス（オプション、intel.enabled）
│ └── API-SURFACE.md
└── phases/
└── <NN>-<slug>/ # フェーズごとに1ディレクトリ
├── <NN>-CONTEXT.md # 実装上の意思決定（discuss-phase）
├── <NN>-DISCUSSION-LOG.md # 人間可読なディスカッション監査（discuss-phase）
├── <NN>-RESEARCH.md # 技術リサーチの所見（plan-phase）
├── <NN>-VALIDATION.md # Nyquist テストカバレッジ戦略（plan-phase）
├── <NN>-PATTERNS.md # コードベースアナログマップ（plan-phase、オプション）
├── <NN>-<PP>-PLAN.md # 実行可能プラン（plan-phase、プランごとに1つ）
├── <NN>-<PP>-SUMMARY.md # 実行記録（execute-phase、プランごとに1つ）
├── <NN>-VERIFICATION.md # フェーズゴール検証レポート（verify-phase）
├── <NN>-UAT.md # 永続的な UAT セッション状態（execute-phase）
└── .continue-here.md # 一時停止後の再開指示（pause-work）
```
---
## ルートレベルのアーティファクト
### `PROJECT.md`
| | |
|---|---|
| **用途** | プロジェクトの正規アイデンティティ: 概要、対象ユーザー、コアバリュー、要件、制約、主要な意思決定。プロダクトの進化に伴いプロジェクトライフサイクル全体を通じて更新されます。 |
| **生成元** | `/gsd-new-project`（初回作成）; 意思決定が検証されると `/gsd-complete-milestone` によって更新されます。 |
| **参照先** | すべてのプランニングワークフロー; `gsd-phase-researcher`、`gsd-planner`（コンテキスト）; `discuss-phase`（過去の意思決定）; `gsd-plan-checker`（プロジェクト制約）。 |
### `ROADMAP.md`
| | |
|---|---|
| **用途** | マイルストーンおよびフェーズ一覧。ゴール、要件 ID、成功基準、フェーズごとの正規リファレンスを含みます。プロジェクトが何をどの順序で構築するかに関する唯一の信頼できる情報源です。 |
| **生成元** | `/gsd-new-project`（初回作成）; `/gsd-phase --insert` および `/gsd-complete-milestone` によって更新されます。 |
| **参照先** | `/gsd-discuss-phase`、`/gsd-plan-phase`、`/gsd-execute-phase`; フェーズ情報を必要とするすべてのオーケストレーションコマンド; `gsd-planner`、`gsd-plan-checker`、`gsd-phase-researcher`。 |
### `REQUIREMENTS.md`
| | |
|---|---|
| **用途** | 番号付きのチェック可能な受け入れ基準。各要件はロードマップフェーズにマッピングされる ID（例: `AUTH-01`）を持ちます。フェーズが実行されると要件を完了済みとしてマークします。 |
| **生成元** | `/gsd-new-project`（初回作成）; `execute-phase` によって要件が完了済みとしてマークされます。 |
| **参照先** | `gsd-planner`（プランはすべてのフェーズ要件 ID に対処しなければならない）; `gsd-plan-checker` ディメンション1（要件カバレッジ）; `discuss-phase`（過去の要件）。 |
### `STATE.md`
| | |
|---|---|
| **用途** | 現在地を追跡するリビングドキュメント — 現在のフェーズとプラン、進捗指標、蓄積された意思決定、セッション継続性ノート。すべてのワークフロー実行の開始時に読み込まれます。重要なアクションのたびに更新されます。 |
| **生成元** | `/gsd-new-project`（初回作成）; すべてのフェーズワークフロー、`/gsd-pause-work`、`/gsd-resume-work` によって継続的に更新されます。 |
| **参照先** | すべてのオーケストレーションワークフロー; `/gsd-progress`; `/gsd-quick` 経由のアドホックタスク実行; `gsd-planner` および `gsd-phase-researcher`（プロジェクトの意思決定）。 |
完全なフィールドリファレンスは [STATE.md スキーマ](state-md.md) を参照してください。
### `config.json`
| | |
|---|---|
| **用途** | ワークフロー設定: モデルプロファイル、リサーチおよびプランチェッカーのトグル、Git ブランチング戦略、Nyquist バリデーション、並列化設定、エージェントごとのモデルオーバーライド。 |
| **生成元** | `/gsd-new-project`（初回作成）; `/gsd-settings`（インタラクティブ編集）。 |
| **参照先** | すべてのワークフローとサブエージェント — `gsd-tools query config-get` 経由で初期化時に読み込まれます。 |
完全なスキーマは [CONFIGURATION](../../CONFIGURATION.md) を参照してください。
### `MILESTONES.md`（オプション）
| | |
|---|---|
| **用途** | 完了したマイルストーンの履歴記録。各マイルストーンのクローズ時に追記されます。何がいつリリースされたかのアーカイブスナップショットを提供します。 |
| **生成元** | `/gsd-complete-milestone`。 |
| **参照先** | `/gsd-audit-milestone`; 人間によるレビュー。 |
### `DECISIONS-INDEX.md`（オプション）
| | |
|---|---|
| **用途** | 過去のフェーズの CONTEXT.md ファイルに記録された意思決定の有界ローリングサマリー。存在する場合、`discuss-phase` は最大3つの過去 CONTEXT.md ファイルを個別に読む代わりにこの単一ファイルを読み取り、コンテキスト予算を節約します。 |
| **生成元** | 過去フェーズの数がローリング読み取り閾値を超えたときに生成されます。 |
| **参照先** | `discuss-phase`（`load_prior_context` ステップ）。 |
### `HANDOFF.json`（一時的）
| | |
|---|---|
| **用途** | 作業が中断されたときに書き込まれる機械可読な一時停止状態。再開ポイント、進行中のコンテキスト、継続指示を含みます。再開時に一度だけ使用されます。 |
| **生成元** | `/gsd-pause-work`。 |
| **参照先** | `/gsd-resume-work`。 |
---
## フェーズごとのアーティファクト
すべてのフェーズごとのファイルは `.planning/phases/<NN>-<slug>/` 以下に配置されます。`NN` はゼロパディングされたフェーズ番号、`slug` はハイフン区切りのフェーズ名です。
### `<NN>-CONTEXT.md`
| | |
|---|---|
| **用途** | プランニング開始前に収集された実装上の意思決定。フェーズ境界（`<domain>`）、`D-NN` 識別子付きのロックされた意思決定（`<decisions>`）、正規のドキュメント参照（`<canonical_refs>`）、既存のコードのインサイト（`<code_context>`）、具体的な参考例（`<specifics>`）、延期されたアイデア（`<deferred>`）を含みます。 |
| **生成元** | `/gsd-discuss-phase`（インタラクティブなディスカッションまたは PRD/ADR エクスプレスパス）。 |
| **参照先** | `gsd-phase-researcher`（調査すべき内容）; `gsd-planner`（ロックされた意思決定）; `gsd-plan-checker` ディメンション7（コンテキスト準拠）。 |
完全なフィールドリファレンスは [CONTEXT.md スキーマ](context-md.md) を参照してください。
### `<NN>-DISCUSSION-LOG.md`
| | |
|---|---|
| **用途** | discuss-phase セッションの人間可読な監査証跡: 議論された領域、提示されたオプション、行われた選択、延期されたアイデア、Claude の裁量に任せられた項目。自動化されたワークフローには使用されません。 |
| **生成元** | `/gsd-discuss-phase`（`git_commit` ステップ）。 |
| **参照先** | 人間によるレビュー; 振り返り。 |
### `<NN>-RESEARCH.md`
| | |
|---|---|
| **用途** | プランニング前に生成される技術リサーチの所見。「このフェーズをうまくプランニングするために何を知る必要があるか？」という問いに答えます — ドメイン分析、パターン、リスク、Architectural Responsibility Map、Validation Architecture セクション（Nyquist ゲートで使用）をカバーします。 |
| **生成元** | `/gsd-plan-phase`（`gsd-phase-researcher` エージェント経由）。 |
| **参照先** | `gsd-planner`（プランニングインプット）; `gsd-plan-checker` ディメンション7c（ティア準拠）、ディメンション8（Nyquist）、ディメンション11（リサーチ解決）; `gsd-pattern-mapper`（ファイルリストのソース）。 |
### `<NN>-VALIDATION.md`
| | |
|---|---|
| **用途** | RESEARCH.md の `## Validation Architecture` セクションから導出された Nyquist インスパイアのバリデーション戦略。プランが遵守しなければならない自動テストカバレッジ要件を指定します。 |
| **生成元** | `/gsd-plan-phase`（ステップ5.5、`workflow.nyquist_validation` が有効で RESEARCH.md に Validation Architecture セクションが含まれる場合）。 |
| **参照先** | `gsd-plan-checker` ディメンション8（チェック8e ゲート — Nyquist チェック進行前に存在しなければならない）; `gsd-verifier`。 |
### `<NN>-PATTERNS.md`
| | |
|---|---|
| **用途** | `gsd-pattern-mapper` によって生成されたコードベースアナログマップ。このフェーズで作成または変更される各ファイルに対して、最も近い既存のアナログを特定し、ファイルの役割とデータフローを分類し、具体的なコード抜粋を抽出します。プランナーを一貫したパターンに向けます。 |
| **生成元** | `/gsd-plan-phase`（`gsd-pattern-mapper` エージェント経由、オプション; `workflow.pattern_mapper: false` の場合はスキップ）。 |
| **参照先** | `gsd-planner`（パターンガイダンス）; `gsd-plan-checker` ディメンション12（パターン準拠）。 |
### `<NN>-<PP>-PLAN.md`
| | |
|---|---|
| **用途** | フェーズ内の単一作業単位の実行可能プラン。YAML フロントマター（ウェーブ、依存関係、ファイル、要件、`must_haves`）、目的、コンテキスト参照、`<read_first>`、`<action>`、`<verify>`、`<acceptance_criteria>` フィールドを持つ XML 構造化タスク、検証基準を含みます。 |
| **生成元** | `/gsd-plan-phase`（`gsd-planner` エージェント経由）。プランごとに1ファイル — 例: `03-02-PLAN.md` はフェーズ3、プラン2。 |
| **参照先** | `/gsd-execute-phase`（エグゼキューターエージェントがプランを読んでタスクを実行）; `gsd-plan-checker`（実行前の品質レビュー）; `gsd-verifier`（実行後の検証のために `must_haves` を読む）。 |
完全なフィールドリファレンスは [PLAN.md スキーマ](plan-md.md) を参照してください。
### `<NN>-<PP>-SUMMARY.md`
| | |
|---|---|
| **用途** | プラン完了後に書き込まれる実行記録。構築された内容、プランからの逸脱、受け入れ基準に対するセルフチェック、フェーズの依存グラフを記録します。 |
| **生成元** | `execute-phase` エグゼキューターエージェント（各プランの実行終了時に書き込まれます）。 |
| **参照先** | `/gsd-progress`（フェーズステータス）; `gsd-planner`（後続のプランが以前のプラン出力への真の依存を持つ場合）; `milestone-summary`。 |
### `<NN>-VERIFICATION.md`
| | |
|---|---|
| **用途** | フェーズゴール検証レポート。実行後に実際のコードベースに対してすべてのプランの `must_haves.truths`、`must_haves.artifacts`、`must_haves.key_links` を確認します。`status: passed | gaps_found | human_needed` を記録します。 |
| **生成元** | `/gsd-verify-work`（または `/gsd-execute-phase` 内の検証ステップ）。 |
| **参照先** | `plan-phase` クローズドフェーズゲート（`status: passed` の VERIFICATION.md はフェーズを `Complete` としてマークし、`--force` なしの再プランニングをブロックする）; `/gsd-progress`; 人間によるレビュー。 |
### `<NN>-UAT.md`
| | |
|---|---|
| **用途** | 永続的な UAT セッション追跡。ライブ UAT セッション全体を通じて各テストケース、期待される観察可能な動作、結果、開発者のレスポンスを記録します。YAML フロントマター（`status`、`phase`、`source`、タイムスタンプ）を持ちます。 |
| **生成元** | `/gsd-audit-uat`（インタラクティブな UAT セッション）。 |
| **参照先** | `/gsd-audit-uat`（以前の UAT セッションの再開）。 |
### `.continue-here.md`
| | |
|---|---|
| **用途** | フェーズの作業が一時停止されたときに書き込まれる人間可読な再開指示。再開エージェントのためのコンテキストを含みます: 重要なアンチパターン、ブロッキング問題、必要な参照、再開するための正確なコマンド。 |
| **生成元** | `/gsd-pause-work`。 |
| **参照先** | フェーズで開始するすべてのワークフロー — `discuss-phase` と `plan-phase` は両方ともエントリ時にこのファイルを確認し、処理を進める前にエージェントが `blocking` アンチパターンへの理解を示すことを要求します。 |
---
## 命名規則
| セグメント | フォーマット | 例 |
|---|---|---|
| フェーズディレクトリ | `<NN>-<slug>` | `03-post-feed` |
| フェーズレベルファイル | `<NN>-<ARTIFACT>.md` | `03-CONTEXT.md` |
| プランレベルファイル | `<NN>-<PP>-<ARTIFACT>.md` | `03-02-PLAN.md` |
| `NN` | ゼロパディングされたフェーズ番号 | フェーズ3は `03` |
| `PP` | フェーズ内のゼロパディングされたプラン番号 | プラン2は `02` |
`config.json` に `project_code` が設定されている場合、フェーズディレクトリはプロジェクトコードをプレフィックスとして使用します: プロジェクトコード `CK`、フェーズ3の場合は `CK-03-post-feed`。
---
## Related
- [STATE.md スキーマ](state-md.md)
- [CONTEXT.md スキーマ](context-md.md)
- [PLAN.md スキーマ](plan-md.md)
- [docs index](../../README.md)

201
docs/ja-JP/reference/state-md.md Normal file
View File

@@ -0,0 +1,201 @@
# STATE.md スキーマリファレンス
`STATE.md` は GSD Core のプロジェクト記憶ファイルです — プロジェクトの現在地、直近の作業内容、次に実行すべきコマンドを記録する単一の Markdown ドキュメントです。このページではそのスキーマを説明します。[ドキュメントインデックス](../../README.md) も参照してください。
---
## 概要
GSD Core で管理するプロジェクトはすべて `.planning/STATE.md` に `STATE.md` を1つ保持します。このファイルはすべてのワークフロー開始時に読み込まれ、重要なアクションのたびに書き込まれます。ファイルは以下を組み合わせた構成です：
- **YAML フロントマター** — ステータスラインフック（`parseStateMd`）および `gsd-tools state` コマンドが読み取る機械可読フィールド。
- **Markdown 本文** — 現在の進捗、蓄積されたコンテキスト、セッション継続性、パフォーマンス指標を記述する人間可読なセクション。
ファイルは意図的にコンパクトに保たれています（目標: 100行以内）。プロジェクト状態のダイジェストであり、アーカイブではありません。
---
## YAML フロントマター
フロントマターはファイルの先頭にある `---` デリミタの間に記述します。`gsd_state_version` と `status` 以外のフィールドはすべてオプションで、データが未取得の場合は省略できます。
### 注釈付きサンプル
```yaml
---
gsd_state_version: '1.0'
milestone: v2.0
milestone_name: Code Quality
status: executing
# フェーズライフサイクルフィールド — すべてオプション (v1.40.0, issue #2833 で追加)
active_phase: "4.5"
next_action: execute-phase
next_phases: ["4.5"]
progress:
total_phases: 17
completed_phases: 10
total_plans: 84
completed_plans: 47
percent: 59
# syncStateFrontmatter が書き込む追加フィールド
current_phase: "4"
current_phase_name: Observability
current_plan: "3"
last_updated: "2026-06-01T12:34:56.789Z"
last_activity: "2026-06-01"
stopped_at: "Phase 4 P3 execution complete"
paused_at: null
---
```
### フィールドリファレンス
| フィールド | 型 | 設定タイミング | 用途 |
|---|---|---|---|
| `gsd_state_version` | string (`'1.0'`) | 常時 | スキーマバージョン。`syncStateFrontmatter` が最初の `state.*` 呼び出し時に書き込む。 |
| `milestone` | string (例: `v2.0`) | マイルストーン設定時 | 現在のマイルストーンバージョン。プロジェクト設定から読み取る。 |
| `milestone_name` | string | マイルストーン設定時 | 人間可読なマイルストーンラベル (例: `Code Quality`)。 |
| `status` | string | 常時 | 現在のライフサイクルステージ。`normalizeStateStatus()` によって正規化される — [ステータス値](#ステータス値) 参照。 |
| `active_phase` | string (例: `"4.5"`) | このフェーズでオーケストレーターコマンドが実行中の場合 | 現在処理中のフェーズ番号。フェーズ間は `null` に設定。 |
| `next_action` | string | アイドル中で推奨コマンドがある場合 | 次に実行するスラッシュコマンド: `discuss-phase`、`plan-phase`、`execute-phase`、`verify-phase`。オーケストレーターが実行中または推奨なしの場合は `null` に設定。 |
| `next_phases` | YAML フロー配列 (例: `["4.5"]`) | `next_action` と対応して | `next_action` が適用されるフェーズ ID（通常1〜2件）。`next_action` と同条件で `null` に設定。 |
| `progress.total_phases` | integer | フェーズデータ取得済みの場合 | 現在のマイルストーンにおける総フェーズ数。ROADMAP.md とフェーズディレクトリから算出。 |
| `progress.completed_phases` | integer | フェーズデータ取得済みの場合 | すべてのプランサマリーがディスク上に存在するフェーズ数（すなわちすべてのプランが完了したもの）。 |
| `progress.total_plans` | integer | プランファイルが存在する場合 | 現在のマイルストーンの全フェーズにわたるプランファイルの合計数。 |
| `progress.completed_plans` | integer | サマリーファイルが存在する場合 | 完了したプランサマリーの合計数（実行済みプランごとに1つの SUMMARY.md）。 |
| `progress.percent` | integer 0–100 | 進捗データ取得済みの場合 | **フェーズ次元** でのマイルストーン進捗（`min(completed_plans/total_plans, completed_phases/total_phases)`）。このフィールドが存在するときのみステータスラインの進捗バーが描画されます — 不在の場合はバーが非表示になります。 |
| `current_phase` | string | フェーズ実行中 | 本文の `Current Phase:` フィールドから抽出したフェーズ番号。 |
| `current_phase_name` | string | フェーズに名前がある場合 | 本文の `Current Phase Name:` フィールドから抽出したフェーズ名。 |
| `current_plan` | string | プランが進行中の場合 | 本文の `Current Plan:` フィールドから抽出したプラン番号。 |
| `last_updated` | ISO-8601 タイムスタンプ | 書き込み時に常時 | 最後の `syncStateFrontmatter` 呼び出しのタイムスタンプ。`realClock.nowIso()` によって書き込まれる。 |
| `last_activity` | string | 本文に設定されている場合 | 本文の `Last Activity:` フィールドから抽出した最終活動日。 |
| `stopped_at` | string | 停止ポイントが記録された場合 | 最後に完了したアクションの説明。アーカイブの文章とのマッチを避けるため `## Session` 本文セクションにスコープを限定。 |
| `paused_at` | string | プロジェクトが一時停止中の場合 | 一時停止ポイントの自由形式の説明。一時停止していない場合は省略または `null`。 |
### ステータス値
`get-shit-done/bin/lib/state-document.cjs` の `normalizeStateStatus()` が本文の生テキストを以下の正規値にマッピングします：
| 正規値 | マッチするテキスト（大文字小文字不問） |
|---|---|
| `discussing` | `discussing` を含む |
| `planning` | `planning` または `ready to plan` を含む |
| `executing` | `executing`、`in progress`、または `ready to execute` を含む |
| `verifying` | `verif` を含む |
| `completed` | `complete` または `done` を含む |
| `paused` | `paused` または `stopped` を含む、または `paused_at` が存在する |
| `unknown` | 上記のいずれにも該当しない |
オーケストレーターコマンドが実行中の場合、慣例（issue #2833）として `status` にライフサイクルステージを直接書き込みます：
| コマンド | 実行中の `status` |
|---|---|
| `/gsd-discuss-phase` | `discussing` |
| `/gsd-plan-phase` | `planning` |
| `/gsd-execute-phase` | `executing` |
| `/gsd-verify-work` | `verifying` |
---
## ステータスライン描画シーン
`hooks/gsd-statusline.js` の `formatGsdState()` がパース済みフロントマターを読み取り、**最初にマッチしたシーン** を出力します。新しいライフサイクルフィールドが適用されない場合は、v1.38.x から一切変更なくオリジナルのフォーマットにフォールスルーします。
| シーン | トリガー | 表示例 |
|---|---|---|
| **1. フェーズアクティブ** | `active_phase` が設定されている | `v2.0 [██░░░░░░░░] 20% · Phase 4.5 executing` |
| **2. アイドル・次のアクション推奨** | `active_phase` が null かつ `next_action` と `next_phases` の両方が設定されている | `v2.0 [██░░░░░░░░] 20% · next execute-phase 4.5` |
| **3. マイルストーン完了** | `percent` が `100` または `completed_phases == total_phases` | `v2.0 [██████████] 100% · milestone complete` |
| **4. デフォルトフォールバック** | 上記のいずれにも該当しない | `v1.9 Code Quality · executing · ph 1/5`（既存フォーマット） |
**シーン優先度:** `active_phase` と `next_action` が両方設定されている場合、シーン1が優先されます — オーケストレーターが実行中であるため「次の推奨」は誤解を招くためです。この優先度は `formatGsdState()` のチェック順序によって強制され、`tests/enh-2833-phase-lifecycle-statusline.test.cjs` の `"scene priority"` スイートでカバーされています。
進捗バー（`[██░░░░░░░░] 20%`）はフロントマターに `progress.percent` が存在する場合のみマイルストーンセグメントに追加されます。不在の場合はバーは表示されません。
---
## フロントマターパースの制約
ステータスラインフックは正規表現ベースのパース（完全な YAML ライブラリを使用しない）を使用するため、以下の制約が適用されます。これらは `tests/enh-2833-phase-lifecycle-statusline.test.cjs` でテストされています。
1. **フロントマターはファイルの先頭文字から始まる必要があります。** コメントを含む何かが開始 `---` の前にあると、マッチが無効になります。開始 `---` 行は末尾のスペースなしで正確にそれだけである必要があります。
2. **ネストされたブロック内のコメントはサポートされていません。** `progress:` ブロックパーサーは次の行が `[ \t]+\w+:` であることを要求します。`progress:` と最初のキーの間に `# comment` を挿入するとマッチが壊れてバーが消えます。ドキュメントはフロントマターブロック内ではなく `STATE.md` 本文に記載してください。
3. **`next_phases` の主形式は単一行フローです。** パーサーは最初に `next_phases: ["4.5", "4.6"]` を試みます。ブロックシーケンス（`- 4.5\n- 4.6`）もパースされますが、ステータスライン描画の信頼性は低下します。正規表現ベースのパーサーを予測可能に保つため、`next_phases` には単一行フローを使用してください。多数の候補フェーズをドキュメント目的で記録する必要がある場合は `STATE.md` 本文に格納してください。
将来的に正規表現パーサーを完全な YAML ライブラリに置き換えた場合は、これらの制約を緩和しテストを更新できます。
---
## Markdown 本文セクション
本文（末尾の `---` 以降のすべて）は `get-shit-done/templates/state.md` のテンプレートに従います。標準セクションは以下の通りです：
### Project Reference
`.planning/PROJECT.md` へのポインタです。以下を含みます：
- **Core value** — `PROJECT.md` の Core Value セクションの一行説明。
- **Current focus** — アクティブなフェーズ。
### Current Position
プロジェクトの現在の状況：
| フィールド | フォーマット |
|---|---|
| `Phase:` | `X of Y (Phase name)` |
| `Plan:` | `A of B in current phase` |
| `Status:` | 自由テキスト。例: `Ready to execute`、`Executing Phase 4`、`Phase complete — ready for verification` |
| `Last activity:` | ハンドラー書き込み時は ISO 日付（`YYYY-MM-DD`）; エグゼキューター作成時はナラティブ文章 |
| `Progress:` | ビジュアルバー。例: `[████░░░░░░] 40%` |
このセクションの `Status:` および `Last activity:` フィールドは、既存の値が既知のテンプレートデフォルト値の場合に GSD ハンドラーによって更新されます（クヌース不変式: エグゼキューター作成値は保存されます）。既知のハンドラーデフォルト値の完全なリストは `get-shit-done/bin/lib/state-document.cjs` の `KNOWN_TEMPLATE_DEFAULTS` に記載されています。
### Performance Metrics
実行速度の追跡：
- 完了した総プラン数、プランあたりの平均所要時間。
- フェーズごとの内訳テーブル（`Phase | Plans | Total | Avg/Plan`）。
- 最近のトレンド: Improving / Stable / Degrading。
各プラン完了後に更新されます。
### Accumulated Context
**Decisions** — 現在の作業に影響する最近の意思決定のサマリー（完全なログは `PROJECT.md` に保存）。`gsd-tools state add-decision` で追加。
**Pending Todos** — 件数と `.planning/todos/pending/` への参照。`/gsd-capture` で取得。
**Blockers/Concerns** — 今後の作業に影響する課題。起点フェーズのプレフィックス付き。`gsd-tools state add-blocker` で追加し、`gsd-tools state resolve-blocker` で解決。
### Session Continuity
即座のセッション再開を可能にします：
- `Last session:` — 最後のセッションの ISO-8601 タイムスタンプ。
- `Stopped at:` — 最後に完了したアクションの説明。
- `Resume file:` — `.continue-here*.md` ファイルが存在する場合はそのパス、存在しない場合は `None`。
---
## 後方互換性
フェーズライフサイクルフィールド（`active_phase`、`next_action`、`next_phases`、バー用の `progress.percent`）は **追加式でプロジェクトごとにオプトイン** です：
- ライフサイクルフィールドが一切設定されていない `STATE.md` は v1.38.x 以前と **バイト単位で同一** に描画されます。
- ライフサイクルフィールドの追加はオプトインです — フィールドが不在の場合レンダラーはグレースフルに縮退します。
- 進捗バーは `progress` ブロックが存在する場合でもオプトインです: バーをトリガーするのは `progress.percent` のみで、`total_phases` と `completed_phases` だけではトリガーされません。
`tests/enh-2833-phase-lifecycle-statusline.test.cjs` の `formatGsdState #2833 backward compatibility` テストスイートがこの保証を固定しています。レガシー `STATE.md` 描画を壊す変更があればスイートが失敗します。
---
## Related
- [Planning artifacts](planning-artifacts.md)
- [Configuration](../../CONFIGURATION.md)
- [The phase loop](../../explanation/the-phase-loop.md)
- [docs index](../../README.md)