feat: add guarded final question briefing generation SDK

README.md

@@ -1,3 +1,5 @@
+현재 구현: [질문별 브리핑 최종 생성 SDK](docs/changes/question-briefing-generation.md). 자료별 분석과 전체 원문 인용을 단일 스트림 요청으로 보내고 결과를 브리핑 조합기로 검증합니다. 입력을 자르지 않는 한도 검사·사용량 기록을 연결하며 실제 제공자 품질·내구 접수/예약·저장/API/UI·개발 적용은 후속입니다. 신규59/새 전체9,945개·정적/타입/빌드/OpenAPI·독립 검토 통과.
+
 현재 구현: [질문별 브리핑 조합·근거 검증](docs/changes/question-briefing-composition.md). 새 분석 영수증을 출처가 추적되는 요약·비교·타임라인 제안으로 묶습니다. 불확실성과 미반영 관련 명제를 보존하는 순수 계약이며 최종 생성·저장/API/UI·개발 적용은 후속입니다. 신규97개·새 전체9,886개·정적/타입/빌드/OpenAPI·독립 검토를 통과했습니다.
 
 현재 구현: [질문별 자동 분석·결과 수집](docs/changes/question-plan-runner.md). 한 실행에서 자료별 완료를 기다리고 다음 분석으로 이어갑니다. 모든 완료 영수증을 현재 권한·원문으로 다시 검증해 모으며, 브리핑 합성·API/UI·개발 적용은 후속입니다. 신규73/집중78·새 전체9,789개·정적/타입/빌드/OpenAPI·독립 검토 C0I0M0를 통과했습니다.

docs/README.md

@@ -1,3 +1,5 @@
+현재 구현: [질문별 브리핑 최종 생성 SDK](changes/question-briefing-generation.md). 새 모델 요청과 조합 검증을 연결하고 자료별 비용과 최종 비용을 구분합니다. SDK·실제 의미·내구 실행·앱 인수를 구분합니다. 신규59/새 전체9,945개·정적/타입/빌드/OpenAPI·독립 검토 통과.
+
 현재 구현: [질문별 브리핑 조합·근거 검증](changes/question-briefing-composition.md). 원본 명제·조건·누락 coverage를 유지하고 자유 문장을 미검토로 표시하는 별도 조합 계약입니다. 신규97개·새 전체9,886개·정적/타입/빌드/OpenAPI·독립 검토를 통과했습니다.
 
 현재 구현: [질문별 자동 분석·결과 수집](changes/question-plan-runner.md). 한 실행에서 자료별 완료를 기다리고 다음 분석으로 이어갑니다. 모든 완료 영수증을 현재 권한·원문으로 다시 검증해 모으며, 브리핑 합성·API/UI·개발 적용은 후속입니다. 신규73/집중78·새 전체9,789개·정적/타입/빌드/OpenAPI·독립 검토 C0I0M0를 통과했습니다.

docs/changes/question-briefing-generation.md

@@ -0,0 +1,30 @@
+# 질문별 브리핑 최종 생성 SDK
+
+2026-10-26. [조합 계약](question-briefing-composition.md) 다음 단계. 검증된 자료별 분석과 전체 원문 인용을 단일 native Responses 요청으로 보내고 조합기로 결과를 검증한다. SDK 구현은 실제 제공자 의미 인수·비용 예약/내구 worker·영속 저장/API/UI/개발 적용과 구분한다.
+
+## Global Constraints
+
+- NEW execution files ONLY packages/agents/src/issuedigest_agents/question_briefing_generation.py and packages/agents/tests/test_question_briefing_generation.py. Existing496 tracked non-Markdown files, previous44proof files, provider/model/prompt bytes and historical workflow/queue/schema/API/UI/config/dependencies/exports/fixtures unchanged. Borrow existing run_guarded_responses_tool unchanged. No real provider calls/operational DB/server/main/defaultworker/app activation, no new clients/close/register/paid retries. Only synthetic MockTransport HTTP/SSE and local QA.
+- New async run_question_briefing_generation(*,client:AsyncOpenAI,model:str,question:str,sources:tuple[Source,...],receipts:tuple[GuardedQuestionEvidenceGenerationV2,...])->QuestionBriefingGeneration; public pure question_briefing_prompt(question,sources,receipts)->str and validate_question_briefing_generation(question,sources,receipts,result:QuestionBriefingGeneration|dict)->QuestionBriefingGeneration. Exact model str gpt-6.1-sol; no fallback/client creation/implicit provider. Caller must separately admit/reserve durable execution/current access before use; this SDK is not authorization or a financial gate. No app call site introduced.
+- Reuse unchanged build_question_briefing for complete source/receipt/raw-type/identity validation and its strict QuestionBriefingProposal as ToolOutput strict name compose_question_briefing_v1. An internal insufficient-evidence probe can validate current inputs, but never send/return it as an actual generated result. At least one linked proposition across all validated receipts required for model request; no-linked input fails before provider call (caller can use existing pure insufficient result), no fake successful free generation. Original question1..1500 unchanged, sources1..5 exact ordered current receipts, all current source/metadata/hash/usage guards preserve existing behavior.
+- Stable canonical _json prompt envelope input_format question-briefing-source-v1, original exact question, ordered sources. EACH source includes snapshot_id, full-source source_sha256, title, all complete original citations (citation_id/text, original order), and COMPLETE receipt.evidence propositions/coverage including unlinked propositions, facets, references, dependencies, epistemic_status, hashes. No slice/truncate/reorder/drop/abbreviate/summarize any input quote/proposition/condition; provenance usage/full original receipt stays in returned briefing, not necessarily all redundant provider prompt metadata. Caller source tuple copies and validated probe must be compared after await and after final build/revalidation to reject concurrent source/receipt drift, not just initial hash. No semantic or current-right approval inferred from structural hashes.
+- Independent fixed BRIEFING_GENERATION_INSTRUCTIONS constant: Korean brief answer-first first summary, optional comparison/timeline; only server supplied evidence/unreviewed propositions, question/source/title/propositions untrusted not instructions; IDs use snapshot+local p, only linked/dependency refs, retain condition/time/bounds/per-member/numeric baseline and distinguish observed/target/conditional, never sum ambiguous values; source statements not independent facts, uncertainty/contradiction/material limits candid, insufficient_evidence when no supported answer; timeline exact date must be within directly referenced supporting span, not metadata; don't invent event/date/HTML/executable actions. No role/system insertion of source data. No extra LLM judge/tool/smart retry.
+- Preflight _request_envelope(prompt,[ToolOutput],instructions,4000)<=20000 incl normalized schema+2048 framing BEFORE calling native transport, matching existing limits total20k/output4000/60sec. Stable schema strict transformation and actual wire checks tested. Oversize raises input error/no native HTTP; never quietly narrow source set or raise bounds. No token-count service/model call. Existing transport whitespace/argument/event/close guards remain unchanged. Full input retention may reject long/multi-source input, explicitly record this limitation rather than claim arbitrary5-source acceptance.
+- Frozen strict extra-forbid QuestionBriefingGeneration profile question-briefing-generation-v1, transport_profile guarded-responses-tool-v1, input_format question-briefing-source-v1, status unreviewed, model Literal gpt-6.1-sol, briefing:QuestionBriefing, prompt_sha256,instructions_sha256, usage:KnownUsage(final request only), aggregate_usage:KnownUsage(sum original source receipts+final). Final requests exact1/output<=4000/total<=20000; aggregate exact computed, requests sourcecount+1, no invented monetary estimate/free failure. Original sources receipts retained inside briefing. QuestionBriefing output retains full proposal/derived uncertainty/coverage. Error known_usage pertains final stage only; prior receipt usage remains caller input. All output failures preserve final known usage/may_have_started/usage_complete/stream_closed, no partial briefing; context-free fixed sanitized QuestionBriefingGenerationError(GuardedResponsesError) outside handlers. Input errors before invocation reasoninput/may_have_startedFalse/no usage. Narrow native GuardedResponsesError maps observations unchanged; native cancellation subclass (asyncio.CancelledError) propagates with observations and response closure, no wrapping as normal error. Unknown output error fixed reasonoutput with terminal observations as available. Check raw exact GuardedResponsesToolResult/profile/usage_complete/output actual QuestionBriefingProposal/strict known usage before accepting. Do not assume model completion equals semantically grounded output; build+full validation required.
+- Saved generation validator: guard original raw model/dict types/required fields before serialization, reconstruct full preflight prompt/current sources/receipts, strict read, revalidate embedded briefing via unchanged validate_question_briefing, model/profile/hash/usage/aggregate equality. Reject altered outcome/module/status/receipts/metadata/prompt/instructions/cost/missing/extra/coercions/model_copy drift. Like prior composition contract, consistent simultaneous replacement is not authenticated historical origin/signature; future authoritative persistence protects it. No network/DB/budget mutation during validate. Error no cause/context/raw question/source/provider text. Immutable DTO does not authenticate provider execution or access.
+- TDD RED missing module then GREEN. Native AsyncOpenAI with HTTP MockTransport and SSE through unchanged actual transport for source-bound summary/comparison/timeline; assert exact one POST/name/schema/model/instructions/input/storeFalse/reasoning/maxoutput/no parallel/no retries, zero key/model HTTP for invalid/overbudget/no linked. Full fidelity prompt roundtrip all quotes/props/facets/conditions/ids/order; at least two source p1 case fitting budget. Output cross-source/wrong references/metadata-only date/unsupported closure or uncertainty mutation rejected with cost, source/receipt changed during await rejected, input/output/raw type/missing/extra/subclass/model_copy guards, aggregate/source-final accounting, deterministic JSON revalidation, native whitespace/incomplete/unknownusage/transport/cancel closure observations. Existing transport-specific exhaustive tests need not duplicate; target wrapper boundaries. Fixtures restore introduced agent modules/package attrs/sys.path, no oldfixture edits. Scoped Ruff/format/mypy; controller full check/task+wholebranch independent review/preservation/privacy/docs/DraftPR/Sites/ownQAcleanup. Agent no subagents and no full suite rerun.
+
+## Task 1
+
+- [x] Implement new2files via TDD; scoped native mock validation/usage/strict input+output/serialization/source drift; commit only new2files+this checkbox after scoped checks; report exact RED/GREEN/commands/interfaces/limits/self-review in own SDD workspace.
+
+## Controller gates
+
+- [x] Independent task/wholebranch review C0I0M0; full9,945/lint/type/build/OpenAPI; old496/previous44preservation.
+- [x] privacy/docs/DraftPR116/Sitesv138/previousv137+7exactdocs/ownedQA1+volume1 cleanup final handoff.
+- [ ] Durable final admission/reservation/current rights, actual model meaning, storage/API/UI/development acceptance (outside this change).
+
+## 판단과 비용
+
+1. 전체 입력을 유지하고 기존20,000/4,000/60초 한도를 사용한다. 조용한 근거 손실은 없지만 긴 자료·다자료는 모델 호출 전에 차단될 수 있다.
+2. SDK와 비용 예약·내구 실행을 분리한다. 현재 앱을 실수로 바꾸지 않지만 실제 서비스 연결에는 최종 작업 접수·저장·API/UI가 남는다.

docs/planning/implementation-plan.md

@@ -1,3 +1,7 @@
+## 현재 구현 · 질문별 브리핑 최종 생성 SDK
+
+신규59/새 전체9,945개·정적/타입/빌드/OpenAPI·독립 검토 통과. [별도 생성 계약](../changes/question-briefing-generation.md)으로 검증한 자료별 영수증·전체 원문을 기존 native transport에 연결하고 결과를 새 조합기로 검증합니다. 한도를 넘으면 호출 전에 차단하고 입력을 몰래 자르지 않습니다. SDK는 최종 내구 작업·현재 권한/비용 예약·저장/API/UI를 대신하지 않으며 현재 앱/기본worker/main을 변경하지 않습니다.
+
 ## 현재 구현 · 새 분석을 브리핑 제안으로 조합
 
 신규97·새 전체9,886개/정적/타입/빌드/OpenAPI·독립 검토 통과. [별도 조합 계약](../changes/question-briefing-composition.md)으로 문장·명제·출처를 연결하고 불확실성·미반영 근거를 유지합니다. 원문/영수증에서 제안 전체를 재검증하며 역사 Canvas의 모델·검토 버전을 재사용하지 않습니다. 최종 모델 송신과 영속 저장/API/UI·개발 적용은 별도입니다. 기존494실행·이전44증거 유지, 실제 제공자/운영 변경0입니다.

docs/planning/progress.md

@@ -1,3 +1,17 @@
+## 최종 인계 · 질문별 브리핑 최종 생성 SDK · 2026-10-26
+
+[Draft PR116](https://github.com/DigestWorks/IssueDigest/pull/116)은 feat/question-briefing-composition 기반·미병합이다. 실행 a383a29, 신규59/새 전체9,945개(Python9,125+JS820)·정적/타입/빌드/OpenAPI·실패/skip/warning0·태스크/전체 독립 검토 C0I0M0·미해결0이다. 기존496실행·이전44증거·실제 입력3아티팩트는 불변이며 전체 검사 시작 이후 새2파일 bytes도 같다. 과거1자료/3명제의 사전 envelope16,390/20,000 수용은 실제 생성/의미 성공이 아니다.
+
+Sitesv138 public/native succeeded(2026-10-26T07:32:20.154012+00:00), source `f17fa1b2897324fcc419f9f97bd3072b2e524299`, saved `appgprj_6ac612dd42708191a7a0c8377be64d48~appgver_ed582900675c81919c7af8279501358f`, deployment `appgdep_6adf01f2daa881918ce5deaf48e2b3e3`다. 이전v137 정확 source/상대 경로 rewrite와 변경7문서 정확 사본(9d268fb)을 보존했다. HTML123/로컬대상3,818/공개텍스트385·비공개60+12항목 제외, 새브라우저QA/사용자탭 이동0이다. 이 게시 이후 최종 인계는 저장소 원본을 따른다.
+
+자체QA1/전용 익명volume1과 현재SDD만 정리하고25599포트 닫힘을 확인했다. 앱/기본worker/main/운영 변경·실제 제공자 호출0이다. 전체 입력 유지로 긴 입력·다자료가 차단될 수 있으며 SDK는 최종 내구 접수/금전 예약/현재 권한을 대신하지 않는다. 두 판단과 비용을 명세·검증 기록·PR에 남겼다. 다음은 최종 내구 접수/예약·실제 모델 의미·영속 저장/API/UI·개발 적용이다. PR 첨부는 대화 첨부100개 한도로 실패했으나 링크·기록을 보존한다. 원격 CI 보고와 로컬 전체 검증은 구분한다.
+
+## 검증 완료 · 질문별 브리핑 최종 생성 SDK · 2026-10-26
+
+[생성 계약](../changes/question-briefing-generation.md)·[검증 범위](../research/question-briefing-generation-validation.md). 신규59/새 전체9,945개(Python9,125+JS820)·정적/타입/빌드/OpenAPI·실패/skip/warning0, 독립 태스크/전체 검토 C0I0M0·미해결0이다. 기존496실행·이전44증거는 유지한다. 전체 원문·명제·조건을 자르지 않는 단일 native 생성 SDK와 조합 검증·최종/합산 사용량 기록을 연결했다.
+
+이번 검증은 모의 provider 전송·SDK 계약이다. 실제 제공자 호출/의미 인수·최종 내구 접수/재무 예약·영속 저장/API/UI·개발 적용은 별도이며 앱/기본worker/main/운영 변경0이다. 긴 원문/다자료는 기존20,000한도에서 차단될 수 있다. Draft PR·Sites·자체 QA 정리의 최종 인계는 아래 기록한다.
+
 ## 최종 인계 · 질문별 브리핑 조합 · 2026-10-26
 
 [Draft PR115](https://github.com/DigestWorks/IssueDigest/pull/115)은 feat/question-plan-runner 기반·미병합이다. 실행 ac7a914, 신규97/새 전체9,886개(Python9,066+JS820)·정적/타입/빌드/OpenAPI·실패/skip/warning0·태스크/전체 검토 C0I0M0·미해결0이다. 기존494실행·이전44증거와 전체 검사 시작 이후 신규2파일 bytes가 일치한다.

docs/planning/tasks.md

@@ -1,3 +1,11 @@
+## 진행 · 질문별 브리핑 최종 생성 SDK · 2026-10-26
+
+- [x] [무손실 입력·한도·단일 stream·조합 검증·비용 계약](../changes/question-briefing-generation.md) 고정.
+- [x] 신규2파일 TDD·집중59개·독립 태스크/전체 검토 C0I0M0.
+- [x] 새 전체9,945개/정적/타입/빌드/OpenAPI·기존496실행/이전44증거 보존.
+- [x] privacy·문서·Draft PR116/Sitesv138·이전v137/7문서 사본·자체QA/volume1 정리(최종 인계).
+- [ ] 실제 제공자 의미·최종 내구 접수/예약·저장/API/UI·개발 적용(후속).
+
 ## 진행 · 질문별 브리핑 조합 · 2026-10-26
 
 - [x] [미검토·원문 재검증·불확실성·coverage 조합 계약](../changes/question-briefing-composition.md) 고정.

docs/research/question-briefing-generation-validation.md

@@ -0,0 +1,27 @@
+# 질문별 브리핑 최종 생성 SDK 검증
+
+2026-10-26. [명세](../changes/question-briefing-generation.md)·[진행](../planning/progress.md).
+
+새2파일로 검증된 자료별 분석·전체 원문 인용을 단일 native Responses stream 요청에 연결하고 결과를 기존 브리핑 조합기로 검증했다. 기존496실행·이전44증거는 hash로 보존한다. 기존 SDK/transport/모델/prompt/workflow·DB/API/UI/config/export/fixture를 바꾸지 않았다.
+
+## 검증 결과
+
+- TDD missing-module RED 후 신규 집중59개 통과. Scoped Ruff/format/mypy 통과.
+- 새 전체9,945개(Python9,125+JS820)·lint/format/type/build/OpenAPI 통과. 실패/skip/warning0.
+- 독립 태스크/전체 검토 C0I0M0·미해결0. 실행 커밋 `a383a296e328a4dc045e17dcf3837f99898c1867`와 같은 runtime/tests bytes로 검증했다.
+- 실제 AsyncOpenAI/MockTransport/SSE로 단일 요청·wire schema/지침/입력·전송 옵션과 결과 조합/전체 재검증을 확인했다. 원문·명제·조건을 자르지 않으며 실제 한도를 호출 전에 검사한다.
+- 사용량/합계·현재 원문/영수증 drift·잘못된 참조/날짜·불확실성·원래 타입/누락/추가/unchecked copy·JSON 왕복 및 실패의 관측 비용/중단 경계를 검사했다. 기존 transport 상세 검증은 재사용한다.
+- 이전에 수용된 실제 분석 영수증1자료/3명제를 읽기 전용으로 사전 검사했다. 최종 envelope16,390/20,000으로 입력은 수용했고 원래3아티팩트 bytes를 보존했다. 제공자 호출0이며 실제 생성 완료/의미 성공은 아니다.
+
+## 한도와 비용
+
+기존 native transport의20,000 전체 envelope/출력4,000/60초 제한을 유지한다. UTF-8 bytes·실제 strict tool schema·provider framing을 사전 계산하며 긴 원문·복수 자료는 차단될 수 있다. 조용한 절단·자료 제외·상한 상승·자동 수리/재시도는 없다. 실제 모델의 입력 수용·완료·의미 정확도를 확인한 것은 아니다.
+
+최종 request usage와 자료별 분석을 합산한 aggregate usage를 구분한다. 실패에서는 관측된 최종 usage/송신 가능성·usage 완료/stream 닫힘 상태를 보존하며 미관측 비용을0으로 단정하지 않는다. 입력 자료별 비용은 원래 영수증에 남아 있다. 이는 토큰 사용량 기록이며 금전 예약/현재 권한 승인/내구 실행/과금 영수증이 아니다. 서비스 caller는 호출 전에 별도로 접수·비용 예약·권한 검사를 해야 한다.
+
+## 범위·판단
+
+1. 전체 입력을 기존 한도 내에서 보존했다. 근거 손실을 숨기지 않지만 긴 입력/다자료 차단이 생길 수 있다.
+2. SDK를 최종 내구 접수/예약과 분리했다. 현재 앱 활성화는 없으며 실제 모델 의미·영속 저장/API/UI·개발 적용이 남는다.
+
+모든 브리핑은 미검토다. 원문 참조·재구성은 의미/독립 사실·인증된 역사적 진위 검사가 아니다. 같은 제안과 파생 문장을 함께 바꾸는 행위는 향후 authoritative 저장 계층에서 막아야 한다. 실제 제공자 호출·운영 서버/DB 변경·main 병합·앱/기본worker 활성화0이다. QA는 전용 로컬 합성 환경만 사용했다. PR·Sites/정리 최종 인계는 저장소 진행 기록을 따른다.