# 作業報告: GitBucket Issue 双方向同期ツールの作成

## 1. 作業実施の理由と指示

- **背景**: ユーザーより、GitBucketのリモートリポジトリに存在するIssueデータをローカル環境（`docs/issues/`）にMarkdownとして同期（プルおよびプッシュ）できないかとの要望があった。
- **意図と指示**: 単なる一方向のダウンロードだけでなく、ローカルでMarkdownを編集した内容をリモートへ反映（Push）、また新規発行（Create）が行える双方向（2-way）同期スクリプトを構築し、GitBucketをシームレスなローカルIssueトラッカーとして利用可能にすること。

## 2. 指摘事項とその対応

- **指摘**: GitBucketからの全Issue取得と更新の仕組みが必要。
  - **対応**: GitHub API互換の `https://gitbucket.tmworks.club/api/v3/repos/dtmoyaji/TelosDB/issues` エンドポイントに対し、Node.jsの標準 `fetch` を用いて通信を行う `tools/scripts/sync_issues.mjs` を作成した。
- **指摘**: 双方向の整合性（コンフリクト管理）をどうするか。
  - **対応**: 各Markdownの先頭にYAML形式のFrontmatterメタデータ（`id`, `state`, `title`, `updated_at`）を持たせた。スクリプト実行時にリモート側の `updated_at` とローカルファイルの更新日時を厳密に比較し、より新しい方を正として上書き（Pull / Push）を行うロジックを実装した。また、`id: new` として作成されたファイルはPOST通信を行い、新規Issueとして発番からリネームまでを自動処理する仕組みを取り入れた。

## 3. 作業詳細

AIエージェントは以下の作業を実行した：

- 実装計画（`implementation_plan_issues.md`）の作成と、タスクリストの定義。
- `tools/scripts/sync_issues.mjs` の実装。依存モジュール（YAMLパーサー等）を不要にするため、専用の正規表現を用いた軽量なFrontmatter解析ロジックを自作。
- スクリプトのテスト実行を実施し、リモートに存在する既存のIssue2件（Issue-1, Issue-2）を `docs/issues/` 内に正確なMarkdownファイルとして生成（Pull）成功した。

## 4. AI視点での結果

```mermaid
graph LR
    A[docs/issues/*.md] <-->|sync_issues.mjs| B((GitBucket API))
    
    A -->|1. meta: id: new| B1[POST: Create Issue]
    B1 -.-> A1(Rename to Issue-X.md)
    A -->|2. Local is Newer| B2[PATCH: Update Issue]
    B -->|3. Remote is Newer| A2[Write/Overwrite Markdown]
```

双方向同期スクリプトの完成により、今後開発者はIDE（VS Code等）上で直接MarkdownとしてIssueの閲覧・追記・クローズが可能になった。これによりブラウザとエディタ間を往復する手間が省かれ、開発のフローが劇的に効率化される見込みである。
※ 注意：リモートへのPush操作を行うには `.env` に `GITBUCKET_TOKEN` の設定が必要。
