ticket: add pending work items

2026-06-20 20:53:58 +09:00 · 2026-06-20 20:53:58 +09:00 · c04c8796f5
commit c04c8796f5
parent 9e7c84a430
6 changed files with 237 additions and 0 deletions
--- a/.yoi/tickets/00001KVJA7V2R/artifacts/.gitkeep
+++ b/.yoi/tickets/00001KVJA7V2R/artifacts/.gitkeep
--- a/.yoi/tickets/00001KVJA7V2R/item.md
+++ b/.yoi/tickets/00001KVJA7V2R/item.md
@ -0,0 +1,115 @@
+---
+title: 'WebFetch: PDF を page-delimited text として取得できるようにする'
+state: 'ready'
+created_at: '2026-06-20T10:46:48Z'
+updated_at: '2026-06-20T10:46:54Z'
+assignee: null
+readiness: 'implementation_ready'
+risk_flags: ['security', 'dependency', 'public-api', 'output-bounds']
+---
+
+## Background
+
+ユーザー要望: `WebFetch` で PDF URL を取得し、LLM が読める bounded text として返せるようにする。調査は同一会話内で完了済みで、初期実装は semantic な「PDF to Markdown」ではなく、PDF から page-delimited な Markdown-ish text を抽出する方針とする。
+
+現状:
+
+- `crates/tools/src/web.rs` の `WebFetch` は HTML / text / JSON / XML-ish content のみを許可し、`application/pdf` は unsupported Content-Type として拒否する。
+- 既存の `render_content()` は `reject_binary(bytes)` と UTF-8 decode 前提なので、PDF binary を既存 text path に乗せることはできない。
+- `WebFetch` の既存 safety behavior は維持する必要がある: private/local host rejection、bounded redirects、`max_response_bytes`、`max_output_bytes`、untrusted content warning。
+
+調査結論:
+
+- 初期実装には `pdf-extract` crate が最有力。
+  - MIT license。
+  - pure Rust。
+  - native/system dependency なし。
+  - memory buffer API あり。
+  - page split API `pdf_extract::extract_text_from_mem_by_pages()` あり。
+- Poppler / `pdftotext` は GPL / system dependency / deployment / Nix packaging の重さから採用しない。
+- `pdfium-render` は Pdfium native library が必要で、初期の text extraction には重すぎるため採用しない。
+- `unpdf` / `pdf_oxide` / `spectre_pdf` 等は Markdown-oriented な候補だが、初期採用には成熟度・audit が不足気味。必要なら follow-up で比較する。
+
+## Requirements
+
+- `WebFetch` が `application/pdf` response を unsupported Content-Type として拒否せず処理できる。
+- PDF binary bytes は既存の UTF-8 text path / `reject_binary()` path と分離して扱う。
+- `pdf_extract::extract_text_from_mem_by_pages()` を使い、page ごとに抽出した text を Markdown-ish に整形する。
+- 出力例:
+
+```markdown
+## Page 1
+
+...
+
+## Page 2
+
+...
+```
+
+- `transformed_as` は `pdf_text_by_pages` など、semantic Markdown 化を約束しない名前にする。
+- result JSON に PDF 用 metadata を追加する。
+- text/html / JSON / XML / text の既存挙動と `html_extraction` metadata を regress させない。
+- `WebFetch` の既存 bounds と safety behavior を維持する。
+
+## Acceptance criteria
+
+- `application/pdf` response が bounded text result を返す。
+- PDF response では `render_content()` の UTF-8 decode 前提 path を通らず、PDF 専用 extraction path が使われる。
+- `pdf_extract::extract_text_from_mem_by_pages()` により、page delimiter 付き Markdown-ish text が返る。
+- result JSON に `pdf_extraction` metadata が含まれる。
+- `max_output_bytes` を超える抽出結果は既存 truncation marker で切り詰められ、`output_truncated` が正しく立つ。
+- `max_response_bytes` / Content-Length check / redirect limit / private host rejection / embedded credential rejection は既存通り維持される。
+- malformed PDF / encrypted PDF / text のない PDF で panic しない。diagnostic error または readable=false 相当の metadata を返す。
+- PDF 以外の unsupported binary content は引き続き拒否される。
+- 既存 WebFetch HTML reader tests が通る。
+
+## Binding decisions / invariants
+
+- `WebFetch` は fetch/extraction tool のままとし、LLM summarization や multi-page research orchestration は入れない。
+- 初期実装では semantic な「PDF to Markdown」を約束しない。page-delimited Markdown-ish text extraction として扱う。
+- 初期実装で対応する MIME は `application/pdf` のみとする。`application/x-pdf`、`application/acrobat`、`application/octet-stream` with `.pdf`、extension sniffing は必要なら follow-up。
+- `max_response_bytes` default は変更しない。大きい PDF が必要な場合は既存 config override を使う。
+- Poppler / Pdfium / subprocess `pdftotext` / system native dependency は導入しない。
+- OCR、scanned PDF 対応、画像抽出、rendering、table reconstruction、2-column layout の完全復元、heading inference、PDF 保存/cache は範囲外。
+- PDF 抽出結果も untrusted content として扱い、既存の warning / network safety / bounds を弱めない。
+
+## Implementation latitude
+
+- PDF metadata は互換性重視で `pdf_extraction` を新設するのが推奨。既存 `html_extraction` は残す。
+- `pdf_extraction` metadata の具体フィールドは実装時に調整してよいが、少なくとも method / pages or pages_included / readable / error diagnostic 相当が分かるようにする。
+- PDF extraction は CPU-heavy になり得るため、可能なら `spawn_blocking` 等で async runtime を塞がない設計にする。ただし Rust parser の強制 cancel までは初期実装の必須条件にしない。
+- 抽出品質が `pdf-extract` で明確に不足する場合は、実装を歪めず、別 Ticket で `unpdf` / `pdf_oxide` 等を比較する。
+
+## Readiness
+
+- readiness: implementation_ready
+- risk_flags: [security, dependency, public-api, output-bounds]
+
+## Escalation conditions
+
+- `pdf-extract` が実装上致命的に使えない、または license/build/security 上の問題が見つかった場合は実装前に戻す。
+- Tool result JSON shape に breaking change が必要になりそうな場合は、既存互換を維持する案を先に提示する。
+- PDF fixture で parser panic / runaway CPU / excessive memory の懸念が出た場合は、bounds 追加または別方針を提案する。
+- Nix packaging / Cargo.lock / cargoHash 影響が大きい場合は実装報告で明示する。
+
+## Validation
+
+- focused tests:
+  - small valid PDF fixture returns expected text。
+  - multi-page PDF fixture returns `## Page 1` / `## Page 2`。
+  - output truncation sets `output_truncated`。
+  - unsupported binary non-PDF remains rejected。
+  - oversized PDF Content-Length remains rejected。
+  - existing WebFetch HTML reader behavior remains unchanged。
+- commands:
+  - `cargo fmt --check`
+  - `cargo test -p tools web`
+  - `cargo check -p tools`
+  - `git diff --check`
+  - `TicketDoctor` if Ticket consistency needs checking。
+
+## Related work
+
+- `crates/tools/src/web.rs` — current WebSearch/WebFetch implementation。
+- Closed prior WebFetch HTML work: `00001KSX9W968`, `00001KSXECDG0`。
--- a/.yoi/tickets/00001KVJA7V2R/thread.md
+++ b/.yoi/tickets/00001KVJA7V2R/thread.md
@ -0,0 +1,23 @@
+<!-- event: create author: ticket-intake at: 2026-06-20T10:46:48Z -->
+
+## 作成
+
+LocalTicketBackend によって作成されました。
+
+---
+
+<!-- event: intake_summary author: ticket-intake at: 2026-06-20T10:46:54Z -->
+
+## Intake summary
+
+ユーザー要望を調査 Ticket ではなく concrete implementation Ticket として作成した。調査済み結論に基づき、`WebFetch` が `application/pdf` を `pdf-extract` で page-delimited Markdown-ish text として返せるようにする。Poppler/Pdfium/subprocess/OCR/semantic Markdown 化は非ゴール。既存 WebFetch safety bounds と HTML/text behavior は維持する。
+
+---
+
+<!-- event: state_changed author: ticket-intake at: 2026-06-20T10:46:54Z from: planning to: ready reason: implementation_ready field: state -->
+
+## State changed
+
+Intake 済み。Orchestrator は implementation routing として扱える。実装 side effect / worktree 作成 / coder 起動はここでは行っていない。
+
+---
--- a/.yoi/tickets/00001KVJDJD02/artifacts/.gitkeep
+++ b/.yoi/tickets/00001KVJDJD02/artifacts/.gitkeep
--- a/.yoi/tickets/00001KVJDJD02/item.md
+++ b/.yoi/tickets/00001KVJDJD02/item.md
@ -0,0 +1,92 @@
+---
+title: 'Intake workflow に Ticket 化前の調査ゲートを明示する'
+state: 'ready'
+created_at: '2026-06-20T11:45:00Z'
+updated_at: '2026-06-20T11:45:00Z'
+assignee: null
+readiness: 'implementation_ready'
+risk_flags: ['prompt-context', 'workflow-source', 'role-behavior', 'ticket-authority']
+---
+
+## Background
+
+Intake がユーザー発話をそのまま Ticket 化しようとし、Ticket 作成前に必要な既存 Ticket / docs / code / workflow 調査を十分に行わない挙動が観測されている。
+
+今回の Intake 調査では、workspace 側の `.yoi/workflow/ticket-intake-workflow.md` には既存 Ticket 確認、関連 docs/code/workflow/history の確認、readiness 分類、ユーザー合意前に official Ticket を作らないことが書かれている一方で、以下の弱さが見えた。
+
+- `resources/prompts/role/intake.md` は role prompt として短く、`create or update the appropriate Ticket` の重みが強い。
+- `resources/workflows/ticket-intake-workflow.md` は workspace workflow snapshot より薄く、Ticket 化前の調査ゲート、draft-before-create、user agreement gate、`spike_needed` の扱いが弱い。
+- workspace workflow でも「必要に応じて関連 docs / code / workflow / history を読む」が optional に読めるため、曖昧な依頼で調査せず draft/Ticket 化へ倒れやすい。
+- draft template に `Action required` / `Attention required` が残っており、現在の Ticket schema / vocabulary とずれた文言が残っている。
+
+関連して参照した既存 Ticket:
+
+- `00001KTAZ2401` Ticket intake workflow
+- `00001KT0JPZS0` Built-in Ticket intake and orchestration routing
+- `00001KTRKZ14C` Project workflows を public builtin と dogfood 運用に分離する
+- `00001KSKBPHRG` Prompt / Workflow 評価メトリクスと改善 Offer
+
+## Requirements
+
+- Intake role prompt に「Ticket 化前の最小調査」を明示する。
+- Ticket intake workflow に、以下を binding step として追加または強調する。
+  - 既存 Ticket / workflow / relevant files を読むべき条件。
+  - 調査不足なら `TicketCreate` せず、draft または `spike_needed` / `requirements_sync_needed` として止めること。
+  - ユーザー主張、Intake が確認した事実、未確認仮説を Ticket draft 上で分けること。
+  - “言われたことそのまま” を requirements / acceptance criteria にしないこと。
+- `resources/workflows/ticket-intake-workflow.md` と workspace workflow `.yoi/workflow/ticket-intake-workflow.md` の役割差を確認し、必要なら bundled 側も詳細化する。
+- stale な `Action required` / `Attention required` 語彙を削除または現在の Ticket 運用に合う表現へ置換する。
+- Intake が coder / reviewer / read-only investigation helper Pod を起動しない境界は維持する。
+
+## Acceptance criteria
+
+- Intake が曖昧な依頼を受けた時、`TicketCreate` より先に duplicate / related work / relevant docs-code-workflow の確認を行うべき条件が model-facing prompt/workflow に明文化されている。
+- 調査が必要な依頼では、Intake が `spike_needed` または `requirements_sync_needed` として draft 提示に留められることが prompt/workflow 上で明示されている。
+- role prompt が “create/update Ticket” だけでなく “materialize 前に十分に調査し、未確認事項を分離する” ことを明示している。
+- bundled workflow resource と workspace workflow の不整合が解消されるか、意図した差分として短く説明されている。
+- Ticket 作成前の user agreement rule は維持されている。
+- stale な `Action required` / `Attention required` が新規 draft template から消えるか、現行 schema と矛盾しない説明に置き換わっている。
+
+## Binding decisions / invariants
+
+- Intake は scheduler ではなく、coder / reviewer / read-only investigation helper Pod を起動しない。
+- Intake は implementation worktree 作成、implementation routing、review routing、merge、close を行わない。
+- ユーザー合意なしに official Ticket を作らないルールは維持する。
+- Ticket body には、ユーザー主張、Intake が確認した事実、未確認仮説、未決定点を混同して保存しない。
+- Prompt / workflow 文言は `resources/prompts` / `resources/workflows` と workspace workflow override の責務境界を崩さない。
+
+## Implementation latitude
+
+- prompt / workflow 文言の修正で足りるならコード変更しない。
+- 実例セッションが必要なら、`~/.yoi/sessions` の該当 transcript を小さく確認して原因分析に使ってよい。ただし raw private context や不要な transcript 全文を Ticket に保存しない。
+- `00001KSKBPHRG` の prompt/workflow evaluation work と接続して、将来的な評価シナリオにするのは可。
+- bundled workflow と dogfood workspace workflow を完全一致させる必要はないが、差分がある場合は意図を説明できる状態にする。
+
+## Readiness
+
+- readiness: implementation_ready
+- risk_flags: [prompt-context, workflow-source, role-behavior, ticket-authority]
+
+## Escalation conditions
+
+- Intake の観測挙動が prompt/workflow ではなく Panel handoff、workflow selection、role profile resolution、または active workflow snapshot の問題に見える場合。
+- workflow source priority や builtin/workspace override semantics の設計変更が必要になる場合。
+- session history を読まないと原因を特定できず、かつ transcript に private context が含まれる可能性がある場合。
+
+## Validation
+
+- prompt / workflow diff review。
+- `git diff --check`。
+- 必要に応じて `yoi ticket doctor`。
+- 可能なら Intake の小さな再現シナリオで、曖昧な依頼に対して `TicketCreate` せず調査/draft に留まることを確認する。
+
+## Related work
+
+- `resources/prompts/role/intake.md`
+- `resources/workflows/ticket-intake-workflow.md`
+- `.yoi/workflow/ticket-intake-workflow.md`
+- `resources/profiles/intake.lua`
+- `00001KTAZ2401`
+- `00001KT0JPZS0`
+- `00001KTRKZ14C`
+- `00001KSKBPHRG`
--- a/.yoi/tickets/00001KVJDJD02/thread.md
+++ b/.yoi/tickets/00001KVJDJD02/thread.md
@ -0,0 +1,7 @@
+<!-- event: create author: LocalTicketBackend at: 2026-06-20T11:45:00Z -->
+
+## 作成
+
+LocalTicketBackend によって作成されました。
+
+---