feat(agents): clarify evidence reference and uncertainty field rules

README.md

@@ -1,3 +1,5 @@
+현재 구현: [정확한 근거 필드·불확실 상태 지침](docs/changes/guarded-question-reference-rules.md). 신규47/관련532·scoped정적검사·독립 코드 검토를 통과했습니다. 실제1요청에서 모델 완료/명제3개 SDK수용·JSON 재검증을 확인했으며, 필수3명제는 AI 개발판정에서 보존을 확인했으며, 전체9,515개·정적 검사/빌드/OpenAPI도 통과했습니다. 일반 품질·앱 인수와 구분합니다.
+
 최신 실제 관측: [질문별 근거 스트림 인수](docs/research/guarded-question-acceptance.md). 요청1회/HTTP200·모델 완료·최종 사용량2,387/2,569를 확인했지만 주체/서술어 참조 누락과 불확실 상태 불일치로 SDK가 거부했습니다. 재호출/자동 보정 없이 원래 결과를 보존하며 의미·앱 인수는 남습니다.
 
 현재 구현: [질문별 근거 스트림 연결](docs/changes/guarded-question-evidence.md). 신규33/관련287·새전체9,468개(Python8,648+JS820)·정적 검사/빌드/OpenAPI·독립 검토 C0I0M0를 통과했다. 기존472실행 파일과 직전69개 증거를 보존했으며 제공자 호출0·앱/worker/main 활성화0이다. 실제 모델 의미와 versioned worker/앱 인수는 남는다.

docs/README.md

@@ -1,3 +1,5 @@
+현재 구현: [정확한 근거 필드·불확실 상태 지침](changes/guarded-question-reference-rules.md). 신규47/관련532·scoped정적검사·독립 코드 검토를 통과했습니다. 실제1요청에서 모델 완료/명제3개 SDK수용·JSON 재검증을 확인했으며, 필수3명제는 AI 개발판정에서 보존을 확인했으며, 전체9,515개·정적 검사/빌드/OpenAPI도 통과했습니다. 일반 품질·앱 인수와 구분합니다.
+
 최신 실제 관측: [질문별 근거 스트림 인수](research/guarded-question-acceptance.md). 요청1회/HTTP200·모델 완료·최종 사용량2,387/2,569를 확인했지만 주체/서술어 참조 누락과 불확실 상태 불일치로 SDK가 거부했습니다. 재호출/자동 보정 없이 원래 결과를 보존하며 의미·앱 인수는 남습니다.
 
 현재 구현: [질문별 근거 스트림 연결](changes/guarded-question-evidence.md). 신규33/관련287·새전체9,468개(Python8,648+JS820)·정적 검사/빌드/OpenAPI·독립 검토 C0I0M0를 통과했다. 기존472실행 파일과 직전69개 증거를 보존했으며 제공자 호출0·앱/worker/main 활성화0이다. 실제 모델 의미·합산 예산/권한/복구·앱 인수는 후속이다. Sites v129에 요약을 게시했고 이전v128을 보존했다.

docs/changes/guarded-question-reference-rules.md

@@ -0,0 +1,34 @@
+# 질문별 근거 참조·불확실 상태 규칙 보완
+
+2026-10-26 KST. [실제1회 거부](../research/guarded-question-acceptance.md)에서 정확한 인용17회가 있어도 subject_refs/predicate_refs를 비우고 source_statement를 제출한 두 명제를 확인했다. 검증기를 완화하지 않고 새 guarded-v2 SDK의 지침을 명확히 한다. 이전 응답·SDK·모든 비용을 보존한다.
+
+## Global Constraints
+
+- Only new `packages/agents/src/issuedigest_agents/guarded_question_evidence_v2.py` and its new test file may change execution code. Existing474 tracked non-Markdown files (including both previous generators, source validators, transport, worker, exports, dependencies) remain byte-identical. Documentation may change. No automatic repair/filling/downgrade, retries/fallback, app/worker activation, DB/server writes or main merge. Implementer makes no actual provider/network calls.
+- New version-local SDK mirrors the existing async guarded SDK's strict source/hash/usage/receipt/error/cancellation guarantees, with public `GuardedQuestionEvidenceGenerationV2`, `GuardedQuestionEvidenceV2Error`, `run_guarded_question_evidence_v2(*, client: AsyncOpenAI, model: str, source: Source, question: str)` and `validate_guarded_question_evidence_v2(source, question, result)`. Reuse existing pure helpers rather than clone their internals. A narrow version-local request/receipt orchestration duplicate is acceptable to preserve frozen historical execution. New receipt profile exact `guarded-question-evidence-v2`; transport_profile remains `guarded-responses-tool-v1`, input_format remains `question-evidence-source-v2`, status unreviewed. Do not impersonate v1 receipt or silently migrate it.
+- `REFERENCE_RULES_SUFFIX` exact bytes (one leading ASCII space, no trailing newline): ` Field rules: fill subject_refs and predicate_refs with exact spans when supported. If subject_refs or predicate_refs is empty, epistemic_status must be uncertain. Empty quantity metric_refs or relative-time anchor_refs also requires uncertain. Broad supporting_refs cannot replace these fields; never invent missing references.`
+- `GUARDED_QUESTION_V2_INSTRUCTIONS = QUESTION_EVIDENCE_V2_INSTRUCTIONS + REFERENCE_RULES_SUFFIX`. Whole prompt/quotes/question/tool name `fill_question_evidence_v2` and existing schema remain unchanged. Reuse v2 input preflight then additionally enforce `_request_envelope(prompt, tools, GUARDED_QUESTION_V2_INSTRUCTIONS, 4000) <= 20000` before native transport. Stored instructions hash and saved validation use the new exact instructions, not the old ones. No changed token/output/deadline/stream limits, no new provider settings or model default.
+- Same actual-type/raw-required guards, original source hash before/after await/construction/validation, strict budgets, source proposition validator, one borrowed native call and lifecycle, sanitized observational errors, cancellation identity, known observed/final usage and close confirmation as guarded v1. Preserve valid over-budget terminal observations before rejecting output. Unknown ordinary failures claim no invented final usage/closure. Reject missing/forged profiles/hashes/original DTO/raw required fields. Native failure carries original reason/observations unchanged; source rejection after completed transport retains known usage. Missing references with source_statement must still fail; uncertain with legitimately empty fields may structurally pass without certifying semantic coverage. Broad support alone never fills field references.
+
+## Task 1: Versioned exact field-rule generator
+
+- [x] Implement only the new two Python files plus this checkbox using TDD.
+
+Read test-driven-development. RED before implementation, GREEN then focused Ruff/format/mypy and related frozen guarded-v1/native/source tests. Real AsyncOpenAI+httpx2.MockTransport SSE integration asserts exact328-byte suffix, new instructions wire/hash, unchanged full prompt/tool/schema/options, one request and borrowed client remains open. Successful nonempty source-attributed proposition + JSON save/revalidate; empty insufficient accepted but unreviewed. Source_statement with missing subject or predicate, missing quantity metric, unanchored relative time rejects; same structurally uncertain data may pass without filling/replacing any field. Old/new receipt/hash substitutions fail. New instructions envelope checked before dispatch (case old envelope fits but new exceeds; boundary <=20000). Native error/cancel/observed usage, source mutation and output rejection retain prior guarantees; do not duplicate all native event matrix. Strict unchecked DTO/raw omission tests can reuse existing fixtures/guards. Module import isolation must preserve frozen reload tests. No private source/real network/model calls; public fixtures only. Commit owned files after scoped tests; write report with RED/GREEN/selfreview/static results. Controller runs fullQA/reviews; do not spawn subagents.
+
+## Controller gates
+
+- [x] Independent task/whole-branch review C0I0M0, full9,515 checks, historical byte preservation and docs/privacy checks.
+- [x] New instructions measured against old full development input; preregister source/criteria/rubric/settings/wire/hash, consume at most1 real request in a new private namespace after code review. No retries/repair/limit increase; partial/invalid output not semantic success. Preserve all old paid namespaces.
+- [x] Compare completion/structural acceptance/JSON saved validation and P5/P9/P10 meaning separately, other9/total12 unchanged. Independent evidence review; no general/holdout/human truth claims.
+- [x] Draft PR109, Sitesv131/previousv130/7exact docs snapshots, ownQA1/volume1/SDD cleanup; no app activation.
+
+## 판단과 영향
+
+새 버전 지침에서 실제 빈 필드 조건을 명시하고 기존 검증기·SDK는 유지한다. 과거 실행 재생을 보존하지만 버전별 요청 조율 코드가 일부 중복되며 실제 모델의 규칙 준수를 보장하지 않는다. 지침328bytes를 요청 예산에 포함하므로 상한 근처 입력은 기존 경로보다 먼저 차단될 수 있다.
+
+## 검증 결과
+
+신규47/관련532·새전체9,515개(Python8,695+JS820)·정적 검사/빌드/OpenAPI·실패/skip/warning0·태스크/전체 코드 검토 C0I0M0다. [실제1회](../research/guarded-question-reference-acceptance.md)에서 모델 완료/명제3개 SDK수용·현재 원문/JSON 왕복·최종usage2,444/2,781을 확인했다. 독립 AI 개발판정은 P5/P9/P10 explicit3·다른9미평가, 증거 검토 C0I0M0다. 이전474실행/원문·응답·실패·사용량은 보존하며 앱/worker/main 활성화는 하지 않았다.
+
+최종 인계: [Draft PR109](https://github.com/DigestWorks/IssueDigest/pull/109)·Sitesv131 public/native succeeded, 이전v130/변경7문서 정확 사본(70325c2)을 보존했다. Site source `ae602f7f73f4314d026e28e9c70e1b649f882686`, saved `appgprj_6ac612dd42708191a7a0c8377be64d48~appgver_fef73bb1d6748191b31a9c00d425ad76`, deployment `appgdep_6adeb6fd9a408191933065b216cac3fc`다. HTML116/로컬대상3,335/공개텍스트350·비공개60+12항목 제외를 확인했고 사용자 탭 이동/새브라우저QA0이다. 자체QA1/전용volume1을 정리했으며 실제 요청은 이번 최초1회뿐이다. 이후 인계는 저장소 원본을 따르고 main/앱/worker 활성화는 없다.

docs/planning/implementation-plan.md

@@ -1,3 +1,7 @@
+## M3 진행 · 명시적 근거 필드·불확실 상태
+
+[guarded-v2](../changes/guarded-question-reference-rules.md)는 실제 빈 필드 조건을328byte로 명시하고 이전 SDK/검증기는 보존한다. [단일 실제 인수](../research/guarded-question-reference-acceptance.md)에서 명제3개의 SDK수용/원문 검증/JSON왕복을 확인했다. 필수3명제는 비맹검 AI개발판정 explicit3/다른9미평가·독립 증거 검토 C0I0M0이며 새전체9,515개(Python8,695+JS820)·정적 검사/빌드/OpenAPI·실패/skip/warning0를 통과했다. 실제 worker/합산 예산/권한/복구·앱 인수는 별도로 남는다.
+
 ## M3 실제 인수 · 생성 스트림의 원문 계약 거부
 
 [단일 실제 요청](../research/guarded-question-acceptance.md)은 모델 완료/최종 사용량까지 수신했지만 주체·서술어 참조 누락과 불확실 상태 불일치로 SDK가 거부했다. 인용 위치17회 exact를 의미 성공으로 세지 않으며 재호출/보정하지 않는다. 출력 지침·참조/uncertainty를 먼저 보완하고 실제 구조/의미를 인수한 뒤 versioned worker·합산 예산/권한/복구·앱 연결로 진행한다. 기존 앱·worker·SDK는 유지한다.

docs/planning/progress.md

@@ -1,3 +1,9 @@
+## 현재 구현·실제 관측 · 정확한 근거 필드·불확실 상태 · 2026-10-26
+
+[새 SDK 계약](../changes/guarded-question-reference-rules.md)·[실제 인수](../research/guarded-question-reference-acceptance.md). 신규47/관련532·scoped정적검사·태스크/전체 코드 검토 C0I0M0. 같은 원문/Q2·새328byte 지침/envelope19,907을 사전 고정해 실제1요청/HTTP200/completed·30.925초·명제3개 SDK수용/JSON저장 재검증을 확인했다. 최종usage2,444/2,781(추론포함)을 보존했고 재호출/보정0이다. 독립 AI개발판정은 필수3명제 explicit3/다른9미평가이며 증거검토 C0I0M0다. 일반/사람/holdout 품질로 확대하지 않는다. 새전체9,515개(Python8,695+JS820)·정적 검사/빌드/OpenAPI·실패/skip/warning0를 통과했다. Sites/PR 최종 인계는 아래 기록을 따른다. 기존474실행/과거 결과·비용·앱/worker/main은 유지한다.
+
+최종 인계: [Draft PR109](https://github.com/DigestWorks/IssueDigest/pull/109)·Sitesv131 public/native succeeded, 이전v130/변경7문서 정확 사본(70325c2)을 보존했다. Site source `ae602f7f73f4314d026e28e9c70e1b649f882686`, saved `appgprj_6ac612dd42708191a7a0c8377be64d48~appgver_fef73bb1d6748191b31a9c00d425ad76`, deployment `appgdep_6adeb6fd9a408191933065b216cac3fc`다. HTML116/로컬대상3,335/공개텍스트350·비공개60+12항목 제외를 확인했고 사용자 탭 이동/새브라우저QA0이다. 자체QA1/전용volume1을 정리했으며 실제 요청은 이번 최초1회뿐이다. 이후 인계는 저장소 원본을 따르고 main/앱/worker 활성화는 없다.
+
 ## 실제 관측 · 질문별 근거 스트림 · 2026-10-25
 
 [실제 인수 기록](../research/guarded-question-acceptance.md). 같은 전체 원문·Q2·3필수/12기준과 새SDK 모델/settings/body를 사전 고정하고1회 호출했다. HTTP200/completed·31.842초·최종usage입력2,387/출력2,569를 받았으나 source contract가 주체/서술어 근거 누락+uncertain 불일치를 거부해 저장 결과를 만들지 못했고 의미 인수는 진행하지 않았다. 필수3명제는 SDK 거부로 미평가이며 의미0/3으로 세지 않는다. 기존474실행·SDK36/실제58/진단66 증거·원문/기준/실패/비용은 유지한다. 전체9,468QA는 코드 불변의 구조 증거로 재사용하며 신규전체QA/서버자원/앱활성화0이다. 다음은 정확참조·uncertainty 보완이며 독립 증거 검토 C0I0M0·사전 고정/보존·문서/비공개자료 검사를 통과했고 PR·Sites 인계를 진행한다.

docs/planning/tasks.md

@@ -1,3 +1,12 @@
+## 진행 · 정확한 근거 필드·불확실 상태 · 2026-10-26
+
+- [x] [새 guarded-v2 지침/영수증](../changes/guarded-question-reference-rules.md) 고정·328byte/기존 입력 envelope19,907.
+- [x] TDD47/관련532·독립 코드 검토 C0I0M0·전체9,515/정적 검사/빌드/OpenAPI·이전474실행/51+36증거 보존.
+- [x] 사전 고정 후 실제1회·completed/SDK수용/JSON왕복·최종usage2,444/2,781·재호출0.
+- [x] 필수3명제 explicit3(AI 비맹검 개발판정)/다른9미평가·독립 증거 검토 C0I0M0.
+- [x] Draft PR109·Sitesv131/이전v130/7문서 정확 사본·자체QA/volume/SDD 정리·인계.
+- [ ] 실제 구조/의미 이후 versioned worker·합산 예산/권한/복구·앱 인수.
+
 ## 실제 관측 · 질문별 근거 스트림 · 2026-10-25
 
 - [x] [원문/Q2/기준/단일 요청 사전 고정](../research/guarded-question-acceptance.md)·474실행/이전SDK36/과거 실제58·진단66 증거 보존.