docs: record ticket audit and restart failures
This commit is contained in:
@@ -0,0 +1,221 @@
|
||||
# Ticket検索・close監査に必要な履歴visibilityが不足している
|
||||
|
||||
Tracking Ticket: `00001KZRNHB35`
|
||||
|
||||
## 発生日
|
||||
|
||||
2026-08-06
|
||||
|
||||
## 概要
|
||||
|
||||
active Ticketから「Implementation reportやapprove、commit evidenceはあるがcloseされていないTicket」を監査した際、model-facing Ticket toolだけでは候補抽出とscope履歴の照合が難しかった。
|
||||
|
||||
この不足により、Workerが複数Ticketの履歴を目視で突き合わせ、`00001KZ46DP6K`のImplementation reportを別のWorkdir delete要件と誤対応させた。最終的にはfull thread、current source、commit `e6a2da54`を再確認して訂正したが、Ticket bodyの誤編集と誤った監査commentを発生させた。
|
||||
|
||||
誤判定自体はWorkerの確認不足である。一方、現在のtool surfaceはこの種の事故を防ぐための検索・version history・typed evidence projectionを提供していない。
|
||||
|
||||
## 観測した障壁
|
||||
|
||||
### `TicketList`から候補を抽出できない
|
||||
|
||||
今回のmodel-facing結果では、`TicketList`が次のようなcount summaryだけを返す場合があった。
|
||||
|
||||
```text
|
||||
Listed 23 ticket(s) for state active
|
||||
```
|
||||
|
||||
個々のTicket id、title、state、updated_atを取得できないため、既知のIDを使って`TicketShow`を全件呼ぶ必要がある。pagination offsetやevent/evidence filterもない。
|
||||
|
||||
必要だった検索条件は以下。
|
||||
|
||||
- activeかつImplementation reportあり
|
||||
- activeかつapproveあり
|
||||
- activeかつcommit evidenceあり
|
||||
- `done`だが未close
|
||||
- Implementation report後にitem body/titleが変更された
|
||||
- unresolved `request_changes`あり／なし
|
||||
- commit hashまたは本文文字列を含むTicket
|
||||
|
||||
### `TicketShow`のprojectionが安定しない
|
||||
|
||||
同じ`TicketShow`でも、state一行だけになる場合と、body/thread/relationsを含むfull JSON projectionになる場合があった。
|
||||
|
||||
```text
|
||||
Ticket 00001KZ46DP6K state planning
|
||||
```
|
||||
|
||||
`body_max_bytes`と`event_limit`を大きくしても常にfull projectionになるとは限らず、Workerは「eventがない」のか「表示が省略された」のかを区別できない。
|
||||
|
||||
### Implementation reportがtyped eventではない
|
||||
|
||||
Implementation reportとcommit evidenceは通常のMarkdown commentとして保存されている。
|
||||
|
||||
```markdown
|
||||
## Implementation report
|
||||
...
|
||||
commit `e6a2da54`
|
||||
```
|
||||
|
||||
そのため、backendは以下を構造化して検索できない。
|
||||
|
||||
- implementation reportの存在
|
||||
- repository id
|
||||
- base/head commit
|
||||
- test evidence
|
||||
- dirty state
|
||||
- assignment id
|
||||
- report対象revision
|
||||
|
||||
Markdown headingや文言に依存した監査になる。
|
||||
|
||||
### item editのversion historyを復元できない
|
||||
|
||||
threadの`item_edit` eventは、変更fieldとreplacement countだけを返す。
|
||||
|
||||
```text
|
||||
Ticket item updated: title, body. Body replacement applied to 10 occurrence(s).
|
||||
```
|
||||
|
||||
編集前title/body、編集後snapshot、item revision idを取得できない。Implementation reportがどのitem revisionを対象にしたかも記録されない。
|
||||
|
||||
このため、「実装完了後にTicketが別scopeへrescopeされた」のか、「Implementation reportの読み違い」なのかをthreadだけから確実に判定できない。
|
||||
|
||||
### lifecycle監査queryがない
|
||||
|
||||
`TicketDoctor`はschema/consistency diagnosticsには有効だが、次のsemantic lifecycle driftを検出しない。
|
||||
|
||||
- Implementation report + approve + reachable commitがあるのにplanning/inprogress
|
||||
- state `done`だが未close
|
||||
- close後にunresolved request_changesが追加された
|
||||
- Implementation report後のmaterial rescope
|
||||
- report commitがcurrent repositoryで解決不能
|
||||
- MR current revisionとreview対象revisionが不一致
|
||||
|
||||
### relation削除operationがない
|
||||
|
||||
`TicketRelationRecord`と`TicketRelationQuery`はあるが、誤登録やstale relationを削除するtyped operationがない。storage直接編集はauthority bypassになるため実施できない。
|
||||
|
||||
## 影響
|
||||
|
||||
- active Ticket全件へのN+1 `TicketShow`が必要になる。
|
||||
- known IDを持たないWorkerは候補自体を列挙できない。
|
||||
- Markdown commentの目視照合で別Ticketのevidenceを混同しやすい。
|
||||
- rescope後のcurrent bodyだけを見て過去Implementation reportを誤評価する。
|
||||
- close漏れ監査が高コストで、Ticket state driftが蓄積する。
|
||||
- 今回は誤ったTicket body editと監査commentを追加し、後から訂正eventを積むことになった。
|
||||
|
||||
## 提案
|
||||
|
||||
### read toolを`Query` / `Show`へ整理する
|
||||
|
||||
既存のselection-only `TicketList`へ検索責務を積み増すのではなく、read surfaceを次の責務へ整理する。
|
||||
|
||||
- `QueryTicket`: Ticket workflowのselection、全文検索、structured filter、attention候補
|
||||
- `ShowTicket`: 一件のcurrent item、version refs、bounded thread、resolution、artifacts
|
||||
- `QueryObjective`: Objectiveのselection、全文検索、state/linked-Ticket filter
|
||||
- `ShowObjective`: 一件のcurrent bodyとlink projection
|
||||
|
||||
`QueryTicket`は次のoptional queryを受け取る。
|
||||
|
||||
```text
|
||||
QueryTicket {
|
||||
query?: string,
|
||||
states?: [...],
|
||||
event_kinds?: [...],
|
||||
evidence?: implementation_report | commit | approved,
|
||||
review_status?: none | approved | request_changes | unresolved_changes,
|
||||
attention?: done_not_closed
|
||||
| implementation_report_not_closed
|
||||
| report_after_rescope
|
||||
| unresolved_review
|
||||
| missing_commit
|
||||
| blocked
|
||||
| unblocked,
|
||||
related_ticket_id?: TicketId,
|
||||
relation_kind?: RelationKind,
|
||||
linked_objective_id?: ObjectiveId,
|
||||
updated_before?: timestamp,
|
||||
updated_after?: timestamp,
|
||||
limit,
|
||||
cursor?,
|
||||
}
|
||||
```
|
||||
|
||||
`attention`は自動mutationを行わず、候補と根拠だけを返す。Worker/Userが`ShowTicket`、review、repository authorityを再読してclose判断する。
|
||||
|
||||
resultは常にbounded summaryを返す。
|
||||
|
||||
- Ticket id/title/state/readiness
|
||||
- matched field/event kind
|
||||
- bounded snippet
|
||||
- event id/sequence
|
||||
- updated_at
|
||||
- unresolved blocker/review count
|
||||
- `next_cursor` / `truncated`
|
||||
|
||||
`QueryObjective`も同じ共通query infrastructureを使い、`query`、`states`、`linked_ticket_id`、`updated_*`、cursor paginationを提供する。domain固有filterとresult型は混ぜない。
|
||||
|
||||
### 横断検索toolは追加しない
|
||||
|
||||
同じqueryを`QueryTicket`と`QueryObjective`へそれぞれ実行すれば十分である。異なるauthorityとresult型を`WorkspaceSearch`へ混ぜるとsurfaceとprojectionが増えるため、横断toolは追加しない。
|
||||
|
||||
### typed Implementation report
|
||||
|
||||
Markdown bodyに加えて、最低限次をtyped attributesとして保存する。
|
||||
|
||||
- `assignment_id`
|
||||
- `repository_id`
|
||||
- `base_commit`
|
||||
- `head_commit`
|
||||
- `merge_request_id` / `revision_id`
|
||||
- validation evidence refs
|
||||
- dirty/untracked state
|
||||
- source Runtime/Worker identity
|
||||
|
||||
reportは作成時のTicket item revisionを参照する。`QueryTicket.evidence`と`attention`はMarkdown headingをparseせず、このtyped authorityをqueryする。
|
||||
|
||||
### retrievable item revisions
|
||||
|
||||
`ShowTicket`のoptional revision selectorまたはbounded version projectionでitem historyを取得できるようにする。専用tool追加は、同じprojectionではsize/authorityを分離できない場合だけ検討する。
|
||||
|
||||
```text
|
||||
TicketItemRevision {
|
||||
revision_id,
|
||||
title,
|
||||
body_digest,
|
||||
body or bounded diff,
|
||||
edited_at,
|
||||
source,
|
||||
}
|
||||
```
|
||||
|
||||
Implementation report/review/close resolutionから対象item revisionを参照する。
|
||||
|
||||
### stable tool projection
|
||||
|
||||
`QueryTicket`、`ShowTicket`、`QueryObjective`、`ShowObjective`は、同じparameterなら常に同じshapeのbounded JSONを返す。省略時は明示的な`truncated`、`returned`、`next_cursor`を返し、「entryなし」と「projection省略」を区別する。
|
||||
|
||||
### write commandは副作用単位で明示する
|
||||
|
||||
relationのadd/remove、Queue、review、Close、item editなどはauthorization、precondition、idempotency、notification、compensation、audit/result型が異なるため、generic `MutateTicket`や`MutateObjective`へ統合しない。明示commandを維持し、model-facing tool数はprofile・role・Flow別catalog projectionで抑える。
|
||||
|
||||
Implementation reportはtyped Ticket thread eventとして扱い、item revision参照とbounded query結果から監査可能にする。
|
||||
|
||||
## 推奨順序
|
||||
|
||||
1. `QueryTicket`を追加し、全文検索・state・updated time・thread kind・resolution・artifact・relation filterとcursorを入れる
|
||||
2. `ShowTicket`へitem/threadの安定したversion referenceを加える
|
||||
3. `QueryObjective`を同じquery/cursor infrastructureで追加する
|
||||
4. `ShowObjective`へlink projectionを加える
|
||||
5. typed Implementation reportとprofile/role/Flow別catalog projectionを追加する
|
||||
6. WebUIに検索・filter・pagination・implementation-report表示を追加する
|
||||
|
||||
## 期待する監査手順
|
||||
|
||||
1. `QueryTicket(states=active, attention=implementation_report_not_closed)`で候補抽出。
|
||||
2. candidateごとに`ShowTicket`でcurrent item revision、report対象revision、latest reviewを取得。
|
||||
3. typed commit/MR evidenceをrepository authorityで検証。
|
||||
4. unresolved `request_changes`とdependencyを確認。
|
||||
5. User/Orchestratorが明示的にcloseする。
|
||||
|
||||
この順序なら、全TicketのMarkdown threadを目視で横断せず、scopeの異なるevidenceを誤対応させずにclose漏れを監査できる。横断検索toolやgeneric mutation toolを増やさず、roleごとのcatalog projectionでsurfaceを限定できる。
|
||||
Reference in New Issue
Block a user