0cc7a1a426
Fold 27 issue-named installer/hooks/statusline/migration/reapply regression files into their canonical module suites (installer-migrations, installer-migration-report, gsd-statusline, reapply-verify-hunks, install-*, gsd-check-update-worker-platform-gate, etc.). Verbatim block-scoped describe wrappers; 276 subtests conserved 1:1. No new files. The one subdir origin (tests/installer-migrations/001-legacy-orphan-files) moved up one level into installer-migrations.test.cjs; its single ../../ module require corrected to ../ so it resolves from tests/ root (verified). Host-env pre-check: no CLI-receiving host sets a redirecting GSD_WORKSTREAM/GSD_PROJECT value. Regenerates regression-name allowlist (222->205), ratchets file-count allowlist (verify 11->8, validate entry removed), makes 16 relocated allow-test-rule exemptions issue-ref- compliant (ADR-456; prunes stale ids). Repoints 15 tests/ references across state-md.md (EN + ja/ko/pt/zh). lint:ci green. Part of epic #1969. Closes #1974. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
202 lines
14 KiB
Markdown
202 lines
14 KiB
Markdown
# 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/gsd-statusline.test.cjs` の `"scene priority"` スイートでカバーされています。
|
||
|
||
進捗バー（`[██░░░░░░░░] 20%`）はフロントマターに `progress.percent` が存在する場合のみマイルストーンセグメントに追加されます。不在の場合はバーは表示されません。
|
||
|
||
---
|
||
|
||
## フロントマターパースの制約
|
||
|
||
ステータスラインフックは正規表現ベースのパース（完全な YAML ライブラリを使用しない）を使用するため、以下の制約が適用されます。これらは `tests/gsd-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/gsd-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)
|