yoi/docs/plan/ai-maintainer.md

# AI Maintainer Workflow 設計

## 目的

AI maintainer は、yoi リポジトリの開発を継続的に進めるための orchestration role である。単発の `/auto-maintain` より広く、設計相談、work item 整理、実装委譲、レビュー、運用課題の記録、改善提案を一つの maintainer loop として扱う。

`/auto-maintain` はこの設計の限定実行形であり、`tickets.sh` / `work-items/` から小さな実装作業を選んで実装・レビューを orchestration する Workflow に留まる。

## 正本と権限境界

現在の作業管理の正本は `tickets.sh` と `work-items/` である。古い `TODO.md` / legacy `tickets/` directory を前提にした運用は superseded。

- work item の作成・コメント・レビュー・状態変更・完了は原則 `./tickets.sh` 経由で行う
- `work-items/{open,pending,closed}/<id>/item.md` は要件・受け入れ条件の正本
- `thread.md` は計画・判断・レビュー・実装報告の時系列 thread
- `resolution.md` は close 時の完了記録
- 時系列と状態遷移の最終根拠は git history
- `docs/report/` は観測・所感・改善候補の記録であり、最新仕様の authority ではない
- `.yoi/memory` は個人/生成 state であり、project record の正本ではない

AI maintainer は project record を勝手に膨らませない。明確な実装単位は work item 化し、小粒な所見は `KNOWN_ISSUES.md`、ドッグフーディング上の障壁やツール問題は `docs/report/` に記録する。

## Role model

### Maintainer Pod

人間と対話する親 Pod。設計判断、作業選定、scope 委譲、レビュー統括、merge / close の判断を担う。

主な責務:

- `work-items/`, `KNOWN_ISSUES.md`, `docs/`, git history, worktree 状態を読んで現在地を把握する
- 作業可能な work item と設計相談が必要な work item を分ける
- child worktree / child Pod に実装を委譲する
- 実装結果を work item の背景・要件・受け入れ条件に照らして review する
- review / close / merge の branch placement を守る
- 人間に判断が必要な境界で止まる

Maintainer Pod は「便利だから」project record を書き換えない。新規 work item 作成、既存 work item の大幅変更、close、merge、commit などは、ユーザー指示または会話上の合意に基づいて行う。

### Implementation Pod

狭い write scope を持つ作業者。対象 worktree と work item を渡され、その範囲で実装・検証・報告を行う。

制約:

- 指定 scope 外を編集しない
- `.yoi` や main workspace の control-plane record を勝手に編集しない
- work item / review / close は maintainer の責務として扱う
- 実装報告には変更点、検証、未解決点を含める

### Reviewer Pod

原則 read-only。実装 diff と対象 work item を読み、妥当性を確認する。

見るべき点:

- work item の要件・受け入れ条件を満たしているか
- 設計を歪めていないか
- 不必要な後方互換性や局所最適な変更を作っていないか
- テストが適切か
- ドキュメント / work item / known issue の更新が必要か

## Workflow modes

### Mode 0: Design consultation

設計や方針を相談するだけの mode。コードや work item は編集しない。

使う場面:

- 要件がまだ曖昧
- work item 化する前に合意したい
- 複数案の設計判断が必要

### Mode 1: Project record maintenance

`work-items/`, `KNOWN_ISSUES.md`, `docs/`, `docs/report/` など control-plane record だけを編集する。実装コードは触らない。

例:

- work item の作成・詳細化
- review / implementation report / resolution の追記
- stale docs の修正
- known issue の追加・削除

新規 work item 作成や大幅変更は、人間の合意後に行う。

### Mode 2: Implementation orchestration

Maintainer Pod が child worktree と implementation Pod を作り、実装と review を回す。親は scoped delegation と project record authority を保持する。

基本手順:

1. 対象 work item を main workspace で作成・詳細化し commit する
2. orchestrator が child worktree を作る
3. implementation Pod に対象 worktree と task を渡す
4. implementation Pod が実装・検証・報告する
5. reviewer Pod が diff と work item を読む
6. 必要なら修正を戻す
7. maintainer が merge-ready dossier を作る

### Mode 3: Maintainer-managed completion

人間が明示的に許可した場合に、親 Pod が commit / merge / close まで行う。

条件:

- 対象 work item が明確
- scope と worktree が分離されている
- review 結果が approve または残件が明示されている
- validation が通っている
- close / merge してよいというユーザー指示または会話上の合意がある

push はしない。破壊的 git 操作は明示指示なしに行わない。

## Work item lifecycle

### 作成

```
./tickets.sh create --title "..." [--slug slug] [--kind task] [--priority P2] [--label a,b]
```

作成後、必要なら `item.md` を詳細化し、背景・要件・受け入れ条件を明確にする。worktree を使う場合は、対象 work item を作成・詳細化して commit してから branch/worktree を切る。

### コメント / 計画 / 判断

```
./tickets.sh comment <id-or-slug> --role plan --file path
./tickets.sh comment <id-or-slug> --role decision --file path
./tickets.sh comment <id-or-slug> --role implementation_report --file path
```

thread は後から読まれる project record なので、実装ログをだらだら貼るより、判断理由・検証結果・残件を簡潔に残す。

### レビュー

```
./tickets.sh review <id-or-slug> --approve --file path
./tickets.sh review <id-or-slug> --request-changes --file path
```

レビューは diff の確認だけではない。work item の前提・要件・受け入れ条件が実装で満たされているか、コードベースを歪めていないかを確認する。

### 完了

```
./tickets.sh close <id-or-slug> --resolution "..."
```

close は `work-items/closed/` へ移動し、`resolution.md` と thread entry を残す。close commit には resolution と関連 project record 更新を含める。

## Branch / worktree placement

main workspace は orchestration / docs / work item lifecycle / merge の control plane。実装差分は原則 child worktree に隔離する。

```
main/develop workspace:
  work item 作成・詳細化 commit
  child worktree 作成

child worktree feature branch:
  implementation commit(s)
  validation

main/develop workspace:
  reviewer Pod に read-only 依頼
  merge / close / cleanup commit
```

child Pod に write scope を渡している間、親 Pod は同じ path を編集しない。必要なら `StopPod` で scope を回収してから project record を更新する。

## Human approval boundaries

AI maintainer は以下で人間に戻す。

- 要件から複数の設計方針が自然に導ける
- public API / protocol / manifest / durable data format を変える
- 大規模 rename / directory 移動 / repository-wide format を伴う
- work item の作成・大幅変更・close について合意がない
- reviewer が request-changes しており、修正方針が自明でない
- validation が失敗し、原因が対象変更か既存問題か不明
- destructive git operation や push が必要

## Reports / Knowledge / Memory

- `docs/report/`: ドッグフーディングで感じた障壁、改善案、ツール問題の記録。明確な作業単位になったら work item 化する
- `.yoi/knowledge`: curated project knowledge。正本ではなく補助 context
- `.yoi/memory`: generated/personal state。project record の代替にしない
- `KNOWN_ISSUES.md`: ticket 化するほどではないが、次に近所を触る時に拾いたい小粒所見

## Future extension points

### WorkItemStore API

現在は `tickets.sh` + repo-managed `work-items/` を正本とする。将来、remote maintainer hub や issue tracker へ差し替えるなら、WorkItem / Thread / Event / Artifact を扱う store interface を追加し、Git/path layout を上位 workflow に漏らさない形にする。

### Maintainer doctor

merge 前 / close 前に以下を検査する command。

- 対象 work item が存在する
- acceptance criteria と implementation report が対応している
- review status が明示されている
- validation log がある
- work item lifecycle と branch placement が矛盾していない

### Multi-maintainer coordination

複数 maintainer Pod が同じ repository を扱う場合は、work item / branch / scope の lease が必要。現状は人間と git history が最終調停者。