docs: brief for annual per-claim evidence grade (BUG-1887, #271)

Adds product contract section K (annual grade v1 dependency table, pending astrologer review).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DbBXoyn7Hj3LCW3BUs5bZ8

docs/tasks/TASK-annual-grade-20261114.md

@@ -0,0 +1,91 @@
+# TASK：年运逐条证据等级 report_evidence_grade_v1（2026-11-14）
+
+- Gitea：#271
+- 分支：`codex/annual-grade-20261114`，从 staging `c18a094a` 切出。
+- Bug 编号：BUG-1887（1886 已被 #260 第二次退回占用）。开工时核对 `docs/BUG_HISTORY.md` 末尾；已被占用就顺延，并在 PROGRESS 写明。
+- 负责验收：Claude（jyotisha-99）。
+
+任务书没写到的取舍，不得写成"产品决定"或"裁定"，一律标「需拍板」。不得修改或删除既有断言来让测试通过。确需修改的，在 PROGRESS 逐条写明原值、新值和原因。
+
+## 背景
+
+占星师 2026-11-12：
+- preset_q3 §1.3–1.4、§5.2：每条结论由后端按路由和结论类型定依赖，算出等级上限；模型只能写到上限或更低；事后检查引用和上限。等级不是概率。
+- 年运验收回复 Q1：年运沿用同一等级契约；Q4：不要年运自己的 A–D「年度能量」。
+
+产品负责人：
+- 2026-11-13（#224）：出生时间误差用用户自报的范围，否则前后 30 分钟；结论需要的分盘上升在误差内换座，该结论封顶 D。
+- 2026-11-12（个人报告原型方案 B，已上线）：每个评级段落下面一行灰字「证据等级 C：有星盘依据，还没有用真实案例校准过」或「证据等级 D：关键依据缺失，暂不能判断」，不需要点开。
+- 2026-11-13：不向用户显示「没有通过核对」的整节隐藏；修起因、修一次，兜底用算好的内容。
+
+依赖表已写进 `references/product_runtime_contract.md` 第 K 节（本任务书同一提交）。照该节执行，不自行增删依赖。
+
+现状（staging `c18a094a`）：
+- 年运写作每节由模型自报 `confidence`（B 或 C）和 `confidence_note`；`annual-report-sections.ts` 的 `confidenceCap()` 恒返回 C。这是 11-07 的旧做法，没有按依赖定上限。
+- 个人报告已实现同一契约：`scripts/report_render/evidence_grade.py`（`claim_grade`、`evidence_grades`、`GRADE_CONTRACT`）、`scripts/report_render/birth_precision_window.py`、前端 `personal-report-reading-contract.ts`（`evidenceGradeTag`、`EVIDENCE_GRADE_MEANING`）。
+- 年运已有出生时间误差取样：`report_facts._birth_survey` / `_stability`，各主题分盘有 `stability`（stable、samples_consistent、varies、unknown）；时间点窗口有 `dates_wide` / `dates_uncertain`。第二批各块（extra_natal_dashas、transit_checks、kp_cusps、pravesha）都有 status。
+
+## 要做的
+
+### 1. 后端算上限（Python）
+
+- 新文件 `scripts/annual_service/evidence_grade.py`。从 `report_render.evidence_grade` import `GRADE_CONTRACT`、`GRADE_ORDER`、`MISSING_STATES` 等常量和可复用的小函数；**不改**个人报告的 `CLAIM_TYPES`。
+- 年运结论类型（id 固定）：`annual_overview`、`annual_domain_career`、`annual_domain_wealth`、`annual_domain_relationship`、`annual_domain_home`、`annual_domain_energy`、`annual_domain_learning`、`annual_timing_window`、`annual_person`。依赖照契约 K 节的表。
+- 判定：
+  - 必需依据 status 属于 MISSING_STATES，或没算出：D。
+  - 主分盘 `stability == "varies"`：该主题 D，记录跨界的分盘和候选。`unknown`（误差未知）照 #224 不应出现；如果出现，写 D 并在 PROGRESS 报告。`samples_consistent` 不降级，但记入 must_disclose。
+  - 时间点窗口 `dates_wide == true`：该窗口 D；`dates_uncertain` 不降级，记入 must_disclose。窗口逐个评级，结果按 window_id 存。
+  - Narayana 在年运是条件参考：status 为 computed 即满足必需；分支未决不算缺失，但记入 must_disclose。
+  - 其余情况上限 C（没有任何真实案例校准，A、B 达不到）。
+  - 「需说明」项缺失只进 must_disclose，不降级。
+- 输出：`report_facts` 的 cards 新增 `evidence_grades` 块：`contract`、`precision_policy`（写明 #224 窗口）、`birth_window`、每个结论类型的 `{cap, required: [...每项 id 与 state], missing_required, must_disclose}`，窗口另有 `windows: {window_id: {...}}`。整块算 `sha256` 存进去。
+
+### 2. 写作改成逐段评级
+
+- 去掉模型自报的 `confidence` / `confidence_note`（两个 schema 都改，原值、新值、原因写进代码注释和 PROGRESS）。`confidenceCap()` 删除，改从 `evidence_grades` 取。
+- 每节的材料里给出本节结论类型的上限、缺失的必需依据、必须说明的项（中文名，不出现字段名）。
+- 模型输出：每段带 `claims`（本段涉及的结论类型，至少一个）和 `grade`。一段混了几类结论时取最严的上限。
+  - overview → annual_overview；area → 对应 annual_domain_*；windows 每个窗口 → annual_timing_window（按窗口）；remaining → annual_timing_window（取所涉窗口最严）；person → annual_person；close 不评级。
+- 事后检查（`gateSection`）：
+  - grade 高于上限 → 失败码 `grade_above_cap:<claim>`，照现有流程重写一次。重写后仍高于上限：不报错、不隐藏，把 grade 改成上限，在 snapshot 记 `grade_clamped`（section、claim、原值、新值）。
+  - 上限是 D 的段落，evidence 里必须写出缺的那项依据（中文名）；没写 → 失败码 `d_without_reason:<claim>`，重写一次；仍没写则由代码在该段末尾补一句「暂不能判断：缺少××」，记 `reason_appended`。
+  - 段落里出现上限是 D 的结论却写成确定的预测，用现有的语气检查即可，不新加关键词表。
+- snapshot：`version` 升到 2；新增 `gradeContract`、`gradesSha256`（等于 facts 里的 sha256）、`factsSha256`（已有）、`promptSha256`（本次 system prompt 的哈希）。旧的 version 1 报告照旧显示，不出等级行，不报错。
+
+### 3. 页面与导出
+
+- 年运页面每个评级段落下面一行灰字，**直接复用**个人报告的 `evidenceGradeTag` 和同一个样式类，不新做组件、不改文案。这是产品负责人 11-12 已批准的原型 B，不再另出原型。
+- 导出的 .md 每段下面带同一行文字。
+- 附录「计算依据」新增一组「证据等级上限」：每种结论一行，写上限、缺了哪些必需依据、要说明哪些（中文名）。时间点窗口逐个列，行数多时沿用先显示第一条、其余折叠。
+
+### 4. 不改的
+
+- 冻结文件只能 import。`references/**`（K 节已由本提交写好）、`consult-preset-prompts.ts` 不碰。
+- 个人报告的评级代码不改行为；只允许把可复用的小函数提出来共享，个人报告的测试必须全过。
+- 不新加任何技法计算，不改第二批各块的内容。
+- 不调用 DeepSeek。测试用桩写手。真模型重新生成样例由验收方另行安排。
+
+## 要改的文件
+
+- `scripts/annual_service/evidence_grade.py`（新）、`scripts/annual_service/report_facts.py`
+- `frontend/src/lib/annual-report-sections.ts`、`frontend/src/lib/annual-report-generate.ts`、年运页面与导出相关文件
+- 测试：`tests/test_annual_grade_20261114.py`、`frontend/tests/annual-grade-20261114.test.tsx`。合成数据覆盖：
+  - 必需依据齐全 → C；
+  - 某主题主分盘 varies → 只有该主题 D，别的主题不受影响；
+  - Vimshottari 缺失 → 总览、各主题、窗口都 D；
+  - 「需说明」项（如 KP blocked）缺失 → 不降级，进 must_disclose；
+  - 窗口 dates_wide → 该窗口 D，其他窗口 C；
+  - 模型写 B 高于上限 C → 重写一次；仍高 → 改成 C 并记 grade_clamped；
+  - 上限 D 没写缺失理由 → 补句并记 reason_appended；
+  - version 1 的旧报告照常显示，没有等级行；
+  - 用户可见文字没有「·」、字段名或下划线。
+- `docs/BUG_HISTORY.md`，只在末尾追加
+- `docs/tasks/PROGRESS-annual-grade-20261114.md`
+
+## 验收标准
+
+1. 公开名人盘上，facts 的 `evidence_grades` 每种结论都有上限和依据清单；生出的报告每个评级段落都有等级行，且不高于上限。
+2. 合成测试覆盖第「要改的文件」列出的每种情况。
+3. 页面上不再有模型自报的把握等级；附录有「证据等级上限」一组；导出带等级行。
+4. 个人报告相关测试全过，行为不变。
+5. tsc、eslint（0 错）、`npm test`（基线失败除外）、quick gate 全部通过。

references/product_runtime_contract.md

@@ -335,3 +335,20 @@ evidence_card.backstage records, for the backend only, that global web evidence
 - 正文「月相回归（Tithi Pravesh）」块后面放 Yoga、Nakshatra 两种研究方法的具名比较表，默认折叠。
 - 完整数据（全部候选、两种年钟、各自的大运分段、Satabdika 状态）放附录「计算依据」，并随导出提供。
 - 本条只决定位置和默认折叠，不减少 Q2 要求显示的内容，也不把研究方法写成结论依据。
+
+## K. 年运逐条证据等级的依赖表（产品 2026-11-14，待占星师复核）
+<!-- 产品对她规则的 v1 落地，不是她的方法。依据：占星师 2026-11-12 preset_q3 §1.3–1.4、§5.2（report_evidence_grade_v1），年运验收回复 Q1「年运沿用同一等级契约，不另设年运 A–D」；产品负责人 2026-11-13 出生时间误差规则（#224）。 -->
+
+- 年运沿用个人报告的 `report_evidence_grade_v1`：A、B 本报告达不到；有星盘依据、未经真实案例校准为 C；结论必需的依据缺失、算不出、或在出生时间误差内会变的为 D。
+- 年运每种结论的必需依据（缺任何一项即 D）与需说明的依据（缺了只披露，不降级）由下表给出。表是产品对她 router §2–§7 的 v1 理解，列给她复核：
+
+| 结论类型 | 必需 | 需说明 |
+|---|---|---|
+| 这一年总览 | 年盘、Vimshottari、Narayana、慢星行运 | Muntha、Mudda、Tajika 名称组合、Saham |
+| 各主题（事业、财富、关系、家宅、身心、学习） | 功能吉凶、年盘、Vimshottari、该主题的主分盘（D10、D2、D9、D4、D24；身心无分盘）在出生时间误差内不变 | Narayana、慢星行运、Mudda、Muntha、Saham、辅助分盘（财富 D11）、Chara、Yogini、Ashtottari、Kalachakra、Double Transit、KP、Sudarshana、Bhrigu Pada（只关系）、Yoga/Nakshatra Pravesha |
+| 时间点窗口 | Vimshottari、Narayana、慢星行运；窗口日期不因出生时间误差移出原月份 | Double Transit、KP、Yogini、Tithi Pravesh |
+| 先看这个人 | 功能吉凶、D1 上升在误差内不变 | D9、Shadbala、Avastha |
+
+- 出生时间误差按 #224：用户自报的误差，否则前后 30 分钟。
+- 研究方法（Yoga/Nakshatra Pravesha）只作观察，不进必需。
+- 本条不减少她要求执行的任何技法，也不把「需说明」项写成结论依据。