Merge pull request #190 from BlueEventHorizon/feature/167-structured-findings

[Feature] Structured finding output (ADR-033, Issue #167)

Author: BlueEventHorizon

.claude/.doc-advisor/toc/forge-rules-ca07acbf88c2/.toc_checksums.yaml

@@ -1,6 +1,6 @@
 # ToC checksums for key: forge-rules
 # Auto-generated - do not edit
-generated_at: 2026-07-07T06:52:31Z
+generated_at: 2026-07-07T17:15:54Z
 file_count: 38
 checksums:
   plugins/forge/docs/additive_development_spec.md: ff45c1401227966ba98bab5f10bb40d3c5ff09a536aa3e79857f879974e3421f
@@ -16,7 +16,7 @@ checksums:
   plugins/forge/docs/requirement_format.md: 400ae580d36cec62c77cbba3255f26bba329e8b21cbf9dacbac53d6cff0f58ff
   plugins/forge/docs/review_priorities_spec.md: 797518b97a8dca2002639fa2afe0727c0ef1b30ae8eec2c24b4c73b5e1ee4119
   plugins/forge/docs/scope_proportionality_spec.md: d32e77754e8d2d06a2cbafda52e745e95baec08b89be34ff56604e7aabb3ab9b
-  plugins/forge/docs/session_format.md: d72e91360fcd54d4a76bf6e9d7203eb46d681ee60b43cf84bb31a0b7e56dbf1d
+  plugins/forge/docs/session_format.md: 243774d3781d27f30ec3eb39a3fccb8c2c2baa127e47b81a6a2920a857b4399c
   plugins/forge/docs/spec_design_boundary_spec.md: 1f093536ab2bc660de69f33ea5d0b5024c1d77ed69133ff7fb404729d49cfde4
   plugins/forge/docs/spec_format.md: a764056bd3dc434db6e0cc3a18761503aa89b463623c7ceb938354e589cd6b6d
   plugins/forge/docs/spec_priorities_spec.md: 9ccba91f19c15cd8613d6ed5bca58fd5bd3f6679ac38f80294540d5918a1abac

.claude/.doc-advisor/toc/forge-rules-ca07acbf88c2/toc.yaml

@@ -5,7 +5,7 @@
 metadata:
   name: Document Search Index (forge-rules)
   key: forge-rules
-  generated_at: 2026-07-07T06:52:31Z
+  generated_at: 2026-07-07T17:15:54Z
   file_count: 38
 
 docs:
@@ -382,37 +382,32 @@ docs:
       - false positive
   plugins/forge/docs/session_format.md:
     title: Session Directory Specification
-    purpose: Defines the common specification for session working directories used by forge orchestrator skills to pass data between phases via files. Covers directory structure, lifecycle, session.yaml format, and file operations.
+    purpose: Defines the common temporary directory specification for forge orchestrator skills to pass inter-phase data through files, including lifecycle management and schema definitions
     content_details:
-      - Session concept and use cases for review pipeline
-      - Directory structure at .claude/.temp/{skill_name}-{random6}/
-      - session.yaml common fields (skill, started_at, last_updated, status)
-      - Review skill-specific fields (review_type, engine, auto_count, current_cycle, files)
-      - Lifecycle stages (probe, init, resume, finish, complete, cleanup) and status transitions
-      - session_manager.py CLI commands and subcommands
-      - refs/ directory schema for context collection results
-      - review-specific files (refs.yaml, review_<type>.md, review.md, plan.yaml)
-      - plan.yaml schema with items, status values, and recommendation logic
-      - Session YAML operation scripts (write_refs.py, update_plan.py, write_interpretation.py, read_session.py)
+      - Session lifecycle management (probe, init, resume, finish operations)
+      - Directory structure with reserved refs/ subdirectory
+      - session.yaml metadata schema with common and skill-specific fields
+      - session_manager.py CLI commands for creation, detection, and cleanup
+      - review-specific files (refs.yaml, findings_<type>.json, review.md, findings_state.yaml)
+      - File writer responsibility boundaries for review pipeline
+      - findings_state.yaml status tracking and state transitions
+      - Session YAML operation scripts (write_refs.py, update_plan.py, apply_eval.py, read_session.py)
     applicable_tasks:
-      - Implementing forge orchestrator skills that use sessions
-      - Session lifecycle management (create, resume, complete, cleanup)
-      - Review pipeline workflow orchestration
-      - Writing refs.yaml for context collection
-      - Updating plan.yaml status across review cycles
-      - Session debugging and state inspection
-      - Session resumption from interrupted states
-      - Batch updating plan items
+      - Forge orchestrator skill development
+      - Review skill implementation and debugging
+      - Session creation and lifecycle management
+      - Finding state tracking and updates
+      - Integration with reviewer/evaluator/fixer agents
+      - Writing session operation scripts
+      - Session resumption and recovery logic
     keywords:
-      - session directory
-      - session.yaml
       - session_manager.py
-      - review pipeline
+      - findings_state.yaml
       - refs.yaml
-      - plan.yaml
-      - orchestrator
-      - patch_result.json
-      - cleanup-stale
+      - findings_<type>.json
+      - recommendation
+      - session lifecycle
+      - review pipeline
       - atomic operations
   plugins/forge/docs/spec_design_boundary_spec.md:
     title: Specification and Design Document Boundary Guide

README.md

@@ -127,6 +127,7 @@ flowchart LR
 | [**create-pr**](docs/readme/guide_anvil_ja.md#create-pr) | GitHub PR をドラフト作成。コミット差分からタイトル/本文を自動生成                      | `"PR を作成"`                       |
 | **create-issue**                                         | 問題・背景・原因を整理して GitHub Issue を作成（解決策は impl-issue が担当）           | `"issue を作成"`                    |
 | **impl-issue**                                           | GitHub Issue から実装計画策定→ブランチ作成→実装→PR 作成までを一貫実行（UI Issue 対応） | `"この issue を実装"`               |
+| **triage-issue**（試作）                                 | GitHub Issue を軽量実装で進めるか forge SDD フローに委ねるかを判定（read-only）        | `"このIssueをトリアージして"`       |
 | **capture-emulator-screen**                              | Android Emulator / iOS Simulator 上で実装済みアプリ画面を起動・操作・キャプチャ        | ※ sync-screen-design 等から呼び出し |
 | **sync-screen-design**                                   | 画面設計書・Figma・実装キャプチャの三点突合で実装画面を仕様とデザインに同期            | `"Figma 通りに直して"`              |
 | _figma-mcp-guide_                                        | Figma MCP サーバーの公式知識ベース。get_design_context / get_screenshot 等のツール仕様 | ※ 他スキルが参照                    |

docs/specs/forge-msg/requirements/REQ-006_codex_review_messaging.md

@@ -10,13 +10,13 @@ notes:
 
 ## メタデータ
 
-| 項目         | 値                                                                                       |
-| ------------ | ----------------------------------------------------------------------------------------- |
-| 要件 ID      | REQ-006                                                                                    |
-| サブシステム | forge-msg（forge review の実行機構に対する追加開発）                                      |
-| 種別         | 要件定義（新規機構・実験段階）                                                            |
-| 対象         | `/forge:review` の Codex エンジン経路（`run_review_engine.sh`）の代替経路                 |
-| 作成日       | 2026-07-08                                                                                 |
+| 項目         | 値                                                                        |
+| ------------ | ------------------------------------------------------------------------- |
+| 要件 ID      | REQ-006                                                                   |
+| サブシステム | forge-msg（forge review の実行機構に対する追加開発）                      |
+| 種別         | 要件定義（新規機構・実験段階）                                            |
+| 対象         | `/forge:review` の Codex エンジン経路（`run_review_engine.sh`）の代替経路 |
+| 作成日       | 2026-07-08                                                                |
 
 ---
 
@@ -32,11 +32,11 @@ notes:
 
 要件確定までに以下の代替案を検討し、却下した。将来同じ議論を繰り返さないよう経緯を残す。
 
-| 検討した案 | 却下理由 |
-| ---------- | -------- |
-| **agmsg**（外部 OSS、SQLite 経由のエージェント間メッセージング基盤）の導入 | 技術的には要件に適合するが、外部ツールの導入によるセキュリティ監査コストが見合わないと判断 |
+| 検討した案                                                                                    | 却下理由                                                                                                                                                                                                                                                                                                                                                                     |
+| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **agmsg**（外部 OSS、SQLite 経由のエージェント間メッセージング基盤）の導入                    | 技術的には要件に適合するが、外部ツールの導入によるセキュリティ監査コストが見合わないと判断                                                                                                                                                                                                                                                                                   |
 | **DSS**（本リポジトリの `docs/specs/forge-session-dss/` で開発中の Doc Session System）の流用 | DSS は「1 workflow = 1 session、1 往復（request→response）」を前提とした単一オーケストレータ内の成果物受け渡し機構であり、`turn` フィールドは常に `1` 固定・`resume`/`continue` コマンドは実装されていない（REQ-007 §10 で多ターン session は明示的にスコープ外）。独立して起動・常駐する外部プロセス（Codex）との継続的な往復を想定した設計ではなく、目的が異なるため不採用 |
-| **push型通知の実装** | 実際に agmsg の実装を調査した結果、Codex 向けの `turn` delivery モード（デフォルト）自体が Stop フック起点のポーリングであり、push 通知は Claude Code 向け `monitor`（5秒間隔ポーリング）ですら実体はポーリングだった。1秒〜数秒間隔のポーリングで要件を満たせるため、push 型通知の実装コストは不要と判断 |
+| **push型通知の実装**                                                                          | 実際に agmsg の実装を調査した結果、Codex 向けの `turn` delivery モード（デフォルト）自体が Stop フック起点のポーリングであり、push 通知は Claude Code 向け `monitor`（5秒間隔ポーリング）ですら実体はポーリングだった。1秒〜数秒間隔のポーリングで要件を満たせるため、push 型通知の実装コストは不要と判断                                                                    |
 
 ### 1.3 検証済みの技術的前提
 
@@ -108,18 +108,18 @@ agmsg 等の外部プラグイン・パッケージを本機構の実行時依
 
 ## 5. 未確定事項
 
-| ID | 内容 | 解決方法 | 期限 |
-| --- | --- | --- | --- |
-| TBD-001 | v1（ガードレールなし）と既存 evaluator/fixer パイプラインの比較評価結果を踏まえ、fixer 相当の安全境界（allowlist・単一 finding 起動等）を追加するか | `meta/` での比較実験結果をレビューし、追加要件として起票するか判断 | v1 実装完了後 |
-| TBD-002 | Codex 側 `.codex/hooks.json` の配置単位（プロジェクト単位 or グローバル `~/.codex/hooks.json`）と、複数プロジェクトで同時に本機構を使う場合の宛先名の衝突回避方法 | 設計フェーズで確定 | 設計開始前 |
-| TBD-003 | 既存 `/forge:review` パイプラインとの統合要否・統合方法（§2.2 で v1 スコープ外としたが、恒久化する場合は必要になる） | v1 の評価結果を踏まえて別途要件化 | v1 実装完了後 |
+| ID      | 内容                                                                                                                                                              | 解決方法                                                           | 期限          |
+| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------- |
+| TBD-001 | v1（ガードレールなし）と既存 evaluator/fixer パイプラインの比較評価結果を踏まえ、fixer 相当の安全境界（allowlist・単一 finding 起動等）を追加するか               | `meta/` での比較実験結果をレビューし、追加要件として起票するか判断 | v1 実装完了後 |
+| TBD-002 | Codex 側 `.codex/hooks.json` の配置単位（プロジェクト単位 or グローバル `~/.codex/hooks.json`）と、複数プロジェクトで同時に本機構を使う場合の宛先名の衝突回避方法 | 設計フェーズで確定                                                 | 設計開始前    |
+| TBD-003 | 既存 `/forge:review` パイプラインとの統合要否・統合方法（§2.2 で v1 スコープ外としたが、恒久化する場合は必要になる）                                              | v1 の評価結果を踏まえて別途要件化                                  | v1 実装完了後 |
 
 ---
 
 ## 6. 関連文書
 
-| 種別   | パス                                                                          | 関係                                                                 |
-| ------ | ------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| 種別   | パス                                                                           | 関係                                                                 |
+| ------ | ------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
 | ルール | `docs/rules/implementation_guidelines.md`                                      | 標準ライブラリのみ実装・SKILL.md インラインスクリプト禁止等の規約    |
 | ルール | `docs/rules/additive_development_spec.md`（`plugins/forge/docs/`）             | 追加開発フィーチャーの判定基準・frontmatter・merge 手順              |
 | 設計書 | `docs/specs/forge/design/DES-028_review_policy_design.md`                      | 現行 review の finding 分類・review_packet 設計（v1 では接続しない） |