docs(research): shared-engine reuse audit (Narayana/Tajika/annual return) + task brief for solar-return frame fix

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

docs/tasks/README.md

@@ -416,3 +416,4 @@
 | `TASK-astrologer-rulings-batch1-20261003.md` | `PROGRESS-astrologer-rulings-batch1-20261003.md` | 占星师定稿 2026-10-03 第一批（低风险批）：五大人格、Kemadruma 各只留一个主检测器；Shadbala 达标在前、分档标「网站分档」；Bhava Bala 改正式三分量；罗计不设本宫、宫主链固定传统主星；8 星制 Karaka 排位按 BPHS 修正；八分法净化值进报告/卡片（过运不动）；落陷取消改条件清单；Tajika 年主如实标注。乙3 Narayana、甲1、甲8/9 不在本单（BUG 从 1204 起） | 已实现待验收 | 分支 `codex/astrologer-rulings-batch1-20261003`（未推送；BUG-1204～1212；校正分数不变、未升版本） |
 | `TASK-astrologer-rulings-batch2-20261003.md` | `PROGRESS-astrologer-rulings-batch2-20261003.md` | 占星师第四轮：五大人格 D9 落陷只算减弱；Tajika 年主按 Panchadhikari 选法（移植上游 c7117f92）；Narayana 实现 Sanjay Rath 版并用原书三张样表验收，不接打分；旧 Narayana 如实标注；Rath 版替换校正 Narayana 的 v5 试算（只研究）。产品选方案 A（BUG 从 1213 起） | 已实现待验收（T3 起运宫未过原书样表，按红线未接、T5 未做） | 分支 `codex/astrologer-rulings-batch2-20261003`（未推送；BUG-1213～1215；校正分数不变、未升版本） |
 | `TASK-astrologer-rulings-batch3-20261003.md` | `PROGRESS-astrologer-rulings-batch3-20261003.md` | 占星师第五轮：Mudda 改出生月宿起排（与年主脱钩）；年主改 Tajika 正式五分力量；Rath 版 Narayana 按原书 7 级强弱、计都反转、子运起点重做并以三张样表验收，过了再并列展示与 v5 试算（研究分支）；土计同宫计都优先（产品选 A）；上游两个 bug 记录（BUG 从 1216 起） | 待领取 | 分支 `codex/astrologer-rulings-batch3-20261003` |
+| `TASK-annual-return-frame-20261003.md` | `PROGRESS-annual-return-frame-20261003.md` | 太阳返照时刻错位：出生太阳与求解器不同参考系（差 15″≈6 分钟）+ 年盘丢秒；243 张年盘里年盘上升变 13、年主变 11；搬上游 7cc6425d/46ed9399 两处，PyJHora 对照 ≤0.5 分钟；排在第三批之后（依据 `docs/research/shared_engine_reuse_audit_2026_10_03.md`） | 待产品确认 | 分支 `codex/annual-return-frame-20261003` |

docs/tasks/TASK-annual-return-frame-20261003.md

@@ -0,0 +1,95 @@
+# TASK：太阳返照时刻对齐（出生太阳同参考系 + 保留秒）— 2026-10-03
+
+## 基线与串行
+
+- **必须在第三批（`TASK-astrologer-rulings-batch3-20261003`，分支 `codex/astrologer-rulings-batch3-20261003`）合入 staging 之后开工。** 两边都改 `scripts/solar_return.py`，第三批 T1 还改了年运下游。
+- 以合入后的 `origin/staging` 为基线。分支 `codex/annual-return-frame-20261003`，工作树 `.worktrees/annual-return-frame-20261003`。
+- 依据：`docs/research/shared_engine_reuse_audit_2026_10_03.md` §S1。
+- 上游参照：`/workspace/yinduzhanxing` 的 `7cc6425d`（出生太阳改在求解器同一参考系重算）和 `46ed9399`（年盘保留秒）。只读，不提交、不推送上游。
+
+## 事故实证（按符号定位）
+
+1. **目标经度和求解器不在同一参考系。**
+   - `scripts/solar_return.py:calc_solar_return_chart` 里，`birth_sun_lon = sun_data.get('degree_raw', …)` 取自 `jyotish_engine.compute_chart_data` 的出生太阳。
+   - `_find_solar_return_swe` 用 `_get_sun_lon_jd`（`swe.calc_ut` + `sidereal_flags`）逐步逼近。
+   - 标准盘（1963-08-07 21:15 IST Sambalpur，Lahiri）两者相差 15.1″，2025 年返照时刻差 6 分 16 秒（网站 18:24:47，上游 18:31:03）。
+2. **年盘丢秒。** 同一函数用 `sr_hour_int, sr_minute_int` 调 `compute_chart_data`，没传 `second`，年盘时刻截到整分钟。
+3. **外部复核。** PyJHora `drik.next_solar_date` 在 5 个样本年与「同参考系 + 保留秒」相差 0.0 分钟，与现状相差 −7.2～+6.8 分钟。
+4. **影响面。** 9 位公开名人（`tests/test_pancha_mahapurusha_main_detector.py:FIGURES`）× 2000–2026 年 = 243 张年盘：
+   - 年盘上升星座变 13 张（5.3%）；
+   - 年主变 11 张（4.5%）；
+   - 昼夜判定变 0 张。
+
+## 根因
+
+网站引擎从上游同步到 `f2241463`（2026-09-03）后，`solar_return.py` 只按 BUG 单补过本地化与返照地点（`41d1c740`）。上游 9 月 7–8 日的两处修正没进来。与 ERR-109「同步太阳返照只核对函数在不在」同类。
+
+## 决策记录
+
+- 返照的定义是「太阳回到出生时的恒星黄经」。出生和返照必须用同一参考系计算，这不是方法分歧，而是计算错误。产品授权（2026-10-03 待用户确认后生效）：按上游 `7cc6425d` / `46ed9399` 的做法修。
+- 只搬这两处。上游同期加的 `position_mode`、`solar_return_time_offset_seconds`、`node_longitude_offset_arcseconds`、`annual_house_system_for_sahams` 参数**不搬**（产品不用，属研究回放参数）。
+- 本地化（`_localize_return_datetime`、`annual_location`）保留网站现有实现，不回退成上游的 `birth_tz`。
+
+## 硬红线
+
+1. 不改冻结身份里的文件（`references/rectification_sealed_holdout.v1.json` → `production_scoring_files`）。`solar_return.py`、`tajika.py` 不在清单内；v5 77 例必须与改动前逐项相同（校正不用年盘，跑一遍证明）。
+2. 不改普通对话提示词，不动迁移，不升打分版本。
+3. PyJHora（AGPL）只能作为外部对照：只允许把它算出的**返照 JD 数字**写进 golden，不得 import 进产品代码或测试运行路径。
+4. 改到 `references/*.json` 的字符串要有 `_en` 对照；`tests/test_report_english_dictionary.py` 单独跑。
+5. 禁止 `git stash`。开工前 `df -h /`，少于 15G 停下。
+
+## 任务分解
+
+### T1 出生太阳与求解器同参考系
+- 在 `calc_solar_return_chart` 中改为 `birth_sun_lon = _get_sun_lon_jd(birth_jd_ut, ayanamsa_name=ayanamsa_name)`；拿不到时才退回出生盘的 `degree_raw`。行文照上游 `7cc6425d`。
+- `solar_return` 返回值加 `target_sun_frame: "swe_sidereal_flags"`，便于日后核对。
+- **验收：**
+  - 新测试：标准盘 2025 年返照 JD 与 PyJHora 参照值（预先算好写死在 fixture，注明来源 `pyjhora drik.next_solar_date`）相差 ≤ 0.5 分钟；
+  - 另取乔布斯 2012、齐达内 2002 两例同样断言。
+
+### T2 年盘保留秒
+- 调 `compute_chart_data` 时传 `second=sr_dt_ut.second`，去掉 `sr_hour_int / sr_minute_int` 的截断。照上游 `46ed9399`。
+- **验收：** 新测试断言年盘 `jd` 与返照 `jd_ut` 相差 < 1 秒。
+
+### T3 下游与 golden
+- 用真实引擎重采受影响的 golden：
+  - `frontend/tests/fixtures/consult-evidence-card-golden.json`；
+  - 报告与年运包相关 golden（以 `grep -rl "solar_return\|varshesha\|mudda" tests frontend/tests` 实测为准）。
+- 每个改动的断言写「原值 / 新值 / 原因」三栏。
+- **验收：**
+  - 进度记录附 243 张年盘前后对比表：年盘上升、昼夜、年主、Mudda 首运星（第三批后 Mudda 首运星不随年盘变，应 0 变化，作为回归证据）；
+  - 历史报告能打开（旧报告存的是生成时的结果，不重算）。
+
+### T4 记录
+- `docs/BUG_HISTORY.md` 新条目：现象、根因（两处）、修复、验证（PyJHora 对照、243 张影响表）、防复发（同参考系测试 + 同步清单加「返照求解参考系」一行），关联 ERR-109、BUG-1026～1028。
+- `docs/research/pre_work_error_ledger.md` 在 ERR-109 下补一行复发说明。
+- `CHANGELOG.md`（用户可感知：约 5% 的年份年盘上升和年主会变）；`PROGRESS-annual-return-frame-20261003.md`；`docs/tasks/README.md` 改状态。
+
+## 让步顺序
+
+T1 → T2 → T4 → T3。T1 的 PyJHora 对照不过（> 0.5 分钟）时停下回报，不做 T2 以后。
+
+## 开工前置命令
+
+```bash
+cd /workspace/Jyotisha && git status -sb | head -1
+git fetch origin --prune
+git log --oneline origin/staging | grep -m1 "BUG-1218"   # 确认第三批已合入，否则不开工
+git worktree add -b codex/annual-return-frame-20261003 .worktrees/annual-return-frame-20261003 origin/staging
+df -h /
+grep -oE "BUG-1[0-9]{3}" docs/BUG_HISTORY.md | sort -u | tail -1
+git -C /workspace/yinduzhanxing show 7cc6425d -- scripts/solar_return.py
+git -C /workspace/yinduzhanxing show 46ed9399 -- scripts/solar_return.py
+python3 scripts/pre_work_check.py --remote-timeout 8 --command-timeout 45
+```
+
+## 验收口径
+
+- Python 定向测试；`run_quality_gate.py --profile quick`；另跑 `tests/test_report_english_dictionary.py`。
+- v5 逐项相同。
+- 前端：`tsc` 0 错；lint 0 error；`npm test` 失败名单与开工基线逐条相同。
+- 不 push，由 Claude 验收后推 staging。部署后 `/api/health` 的 `gitCommit` 等于含门禁改动的提交。
+
+## BUG 编号起点
+
+开工时核对当前最大号。第三批计划用到 BUG-1216 起若干条，本单预计从 BUG-1220 起。