Jyotisha/docs/tasks/TASK-upstream-sync2-20260909.md

# TASK · 上游同步二（婚恋三层触发模型 + 条件大运族）— 2026-09-09

- 基线：`origin/staging` @ `d5972ef4`（2026-09-09）。开工前 `git fetch origin --prune`，以远端为准。
- 上游：`/workspace/yinduzhanxing`，源分支 **`origin/codex/add-birth-time-rectification-skill`** @ `b9a0ef8f`（2026-09-09 01:36 +0800，比 `origin/main` `a6f47abd` 多 155 提交，**未进 main**）。本仓快照锁仍是 `a6f47abd`（`references/upstream/yinduzhanxing/source-manifest.json`）。
- 分支：`codex/upstream-sync2-20260909`，worktree `.worktrees/upstream-sync2-20260909`。
- **串行**：`TASK-report-chart-render-20260909.md` 也改 `scripts/jyotish_engine.py`（`_render_south_chart` 一处）与 `CHANGELOG.md`。本单排在它**之后**：领取时若它已合入 staging 就以新 staging 为基线；若未合入，本单先做不碰 `render_pl9_markdown` 的任务 0–2，任务 3 的报告表格改动等它合入后 rebase 再做。

## 1. 现状实证

上游这条分支 09-03 以来做了三类事，逐条核过（`git diff --stat origin/main origin/codex/add-birth-time-rectification-skill`，638 文件 +77,465/−2,939，其中 references/docs 研究台账占九成）：

| 类别 | 上游落点 | 本仓现状 | 本单取舍 |
| --- | --- | --- | --- |
| **婚恋触发三层模型**（CHANGELOG v6.9.15，2026-09-04） | `scripts/punarphoo.py`（新，102 行）、`scripts/relationship_analysis.py` +220、`scripts/dasha_calculator_enhanced.py` +54、`mcp_server.py` +59、`references/technique_registry.json` +40（`punarphoo` 项）、`references/yoga_rules.json` +50、`references/event_judgment_marriage.md` +65、`references/strict-workflow-router.md` +44、`tests/test_punarphoo_observation.py`（154 行）、`tests/test_mcp_strict_workflow_relationship.py` +24 | `relationship_analysis.py`、`yoga_rules.json`、`event_judgment_marriage.md`、`strict-workflow-router.md` 与上游 main **字节一致**（可直接覆盖）；`dasha_calculator_enhanced.py` 三方合并 0 冲突；`mcp_server.py` 三方合并 2 冲突；`technique_registry.json` 是本仓自己的 89 项注册表，只能手加条目 | **取**（任务 2） |
| **条件大运族**（10 套 + 子周期 profile） | 新模块 `shodashottari / dwadashottari / panchottari / satabdika / shastihayani / chaturshitisama / dwisaptatisama / shattrimshatsama / tribhagi / niryaana_shoola_dasha.py` + `source_bounded_child_periods.py`（共 ≈1,700 行，纯计算，只互相 import，不读 references JSON）；`cmd_full_reading` 里 `birth_info_for_alt_dasha` 新增 5 个键并循环调用 10 套；PL9 大运表 104–120 行；29 个测试文件 | 本仓 `cmd_full_reading`（`jyotish_engine.py` L15096；alt-dasha 块 L16309–16340）只跑 Yogini / Ashtottari / Kala Chakra；`_native_dasha_master_families`（L2639）只映射 5 族；本仓旧 `conditional_dashas.py` 有 dwisaptati / shattrimsa / dwadashottari 的早期实现但没接进 full reading | **取**（任务 3）。上游是经 `professional_parity_closure.py`（本仓没有，+1,360 行研究模块）接 PL9 的，本仓走自己的 `_native_dasha_master_families` |
| Shadbala Dig / Chesta 可选 profile | `scripts/shadbala.py` +122（`raman_luminary_zero`、`raman_inferior_planet_assignment`、`raman_wrapped_0_60`，默认 profile 不变）、api_server / MCP 加 `dig_profile` 参数、十几个 `shadbala_mercury_*` 研究脚本 | `shadbala.py` 三方合并 **7 冲突**；这些 profile 全是 Raman 例题 / PyJHora parity 探针，生产默认值不变 | **不取**。产品面零变化，合并成本高 |
| PL9 用户版 `reader_main`（`_render_pl9_user_markdown`） | 把 `blocked`→「待补」、`parameter_sensitive`→「参考」，删含 PyJHora / schema / 审计 的行 | 违反本仓真话边界（报告页 `blocked` / `conflict` 标签必须可见，`frontend/DESIGN.md` Personal report reader） | **不取** |
| 年运北印 SVG（`annual_north_indian_renderer.py`）、年运 Tajika / Mudda / saham 扩展 | 服务端 SVG | 图盘已决定前端自绘（`TASK-report-chart-render-20260909.md`） | 不取 |
| Narayana / Rashi dasha 显式合同（`rashi_dasha_explicit_contract.py`、`narayana_dasha.py` +59、`drig / lagna_kendradi / navamsha / shoola_dasha.py`） | Visti Larsen 源冻结研究 | 本仓 `narayana_dasha.py` 有商业改动，与上游 main 已分叉 | 不取；PROGRESS 记一句 |
| 校正：`_known_case_regression_hint`、「lock yn-1993 ayanamsa calibration baseline」、`active_rectification_candidates.py`、`/api/active_rectification_candidates` | 答案泄漏模式 + 候选差异合同 | 本仓已定性为泄漏（`TASK-upstream-sync-20260903.md` 硬红线 3）；split-hash / 分歧面板已覆盖候选差异需求 | **不取** |
| `_render_pl9_user_markdown` 之外的 `render_pl9_markdown` 25 个 hunk、`write_pl9_pdf(edition)`、api_server +207 | PDF 版式与 MCP 报告入口 | 本仓报告是 Markdown 直渲，api_server 距增长上限只剩 67 行（11296 / 11363） | 不取 |

三方合并干跑（base = 上游 main `a6f47abd`，ours = `origin/staging`，theirs = 分支）：`jyotish_engine.py` 整文件 13 冲突——但本单**不整文件合并引擎**，只搬 `cmd_full_reading` 的两个 hunk（都在本仓 L16309 附近、无冲突区域）；`mcp_server.py` 2 冲突（L50 import 区、`_maybe_attach_vedastro_evidence` 附近的岁差参数改动，后者不取）；`dasha_calculator_enhanced.py` 0 冲突。

## 2. 差距（为什么值得做）

1. 婚恋问题现在走 `jyotish_api_server.py` `_compute_relationship`（L7829）→ `analyze_relationship(planets_for_analysis, asc_sign)`（L7838，**没有传 `dasha_info`**，虽然咨询路径 L5429 已把 `_thematic_dasha_info` 放进 body），再由 `_derived_marriage_evidence`（L5519）把 `spouse_status_yoga` 与我方自己的 `relationship_timing`（`_compute_relationship_timing_evidence` L7861，DK/UL 线）写进证据链。`analyze_relationship` 里的 `timing` 只有一条「Venus/Jupiter/Moon 大运 → 感情活跃」，等于把心动、成对、领证三件事合成一句「婚恋机会」——上游 09-04 审计的假阳性根因就是这个；本仓因为没传 `dasha_info`，这句目前既不会出现、也不会被三层模型替代。上游改法把 `analyze_relationship` 输出加了 `event_class_split`（`romantic_activation` 看 5L / 7H 月亮 / Punarphoo；`relationship_formation` 看 7L / DK / UL；`legal_marriage` 看 Venus / DK / UL；只认 MD/AD，PD 记 `pd_hits` 不升格），这层本仓一行都没有。
2. 长报告「时间系统证据状态」表（`render_pl9_markdown` 内 `_family_status_row`，L4027 定义、L4043–4047 五次调用；families 为空时 L4019 的 fallback 只喂 5 个键）只有 5 族。条件大运族每张盘通常只有 1–3 套适用，适用的那几套是正规 BPHS 内容，报告里现在完全没有。

## 3. 决策记录（产品负责人 2026-09-09 拍板「需要第二份任务书」）

| 决策 | 内容 |
| --- | --- |
| D1 | 取婚恋三层模型全部代码与参照文档；`punarphoo` 进注册表为 `partial / observation_only`，`prediction=not_claimed`，**永远不得**改写 `dominant_label=legal_marriage`。 |
| D2 | 取 10 套条件大运 + `source_bounded_child_periods`，接进 `cmd_full_reading` 与 `_native_dasha_master_families`；报告表格里适用的显示 `executed / parameter_sensitive`，不适用的显示 `not_applicable`（附条件），出错的显示 `blocked`。**不**接 `professional_parity_closure.py`。 |
| D3 | 快照锁推进到分支提交 `b9a0ef8f`，`source-manifest.json` 的 `boundary` 注明来源是非 main 分支；镜像策略 v2 不变（只镜像根 SKILL.md）。 |
| D4 | Shadbala profile、PL9 用户版、年运渲染、Narayana 合同、校正三件：本轮不取（理由见 §1）。 |
| D5 | 上游 AGENTS.md §8「MD/AD/PD 日期只许走引擎、禁止手写 DASHA_ORDER」不改本仓 AGENTS.md（那是产品负责人的文件），改写进商业 `SKILL.md` 路由段与咨询 prompt 的 relationship 硬约束行。 |
| D6 | 商业 Skill 版本 bump `6.9.15 → 6.9.16`（SKILL.md 正文有改动）；新增 `skills/jyotish-vedic-astrology/versions/6.9.16/`，不改 6.9.15。 |

不推翻既有红线。`TASK-upstream-sync-20260903.md` 硬红线 3（校正泄漏不取）、4（咨询响应契约只增不改）继续有效。

## 4. 硬红线

1. **咨询响应契约只增不改**：`/api/consultation_workflow` 与 `/api/relationship` 现有键路径、类型不变；`analyze_relationship` 只新增 `event_class_split` 与 `timing[].event_class`，原 `timing[].dasha / note` 键保留。任务 0 的 golden 逐键比对。
2. `scripts/jyotish_api_server.py` **净增 ≤ 10 行**（当前 11296，上限 11363）。婚恋证据项构造放新模块 `scripts/relationship_event_class_evidence.py`，api_server 只加一行调用。
3. 不整文件合并 `jyotish_engine.py` / `mcp_server.py`；按 hunk 搬，PROGRESS 列每个 hunk 的取舍。
4. Punarphoo 与心动层只能出现在 `secondary_context` / 观察级证据里；任何把 `romantic_activation` 命中写成「会结婚」「领证窗口」的文案都不许，`frontend/docs/VOICE.md` 口径对照。
5. 条件大运不得进入 `_calc_dasa_convergence` 的多系统交叉投票（保持 Vimshottari + Chara + Yogini 三系统不变），也不得进入校正打分（`rectification_*` 一个文件都不碰）。
6. 注册表新条目商业状态按 09-03 规则：网页路径实际执行的才可写 `partial`，否则 `research_only_blocked`；条件大运 10 项因 full reading 会执行且报告会显示 → `partial`，`claim_boundary` 写「条件适用性 + 子周期 profile 为 PyJHora 等分法，未做多引擎 parity」。
7. 不带任何 `references/research/**`、`references/oracle/*_2026_09_*.json` 研究台账进本仓；上游测试里 import 这些路径的用例不搬。
8. 隐私：上游测试若含真实生日（分支里有 `yn-1993`、`1993-04-17` 样本），搬过来时换成公开名人或虚构日期。
9. 前端不动（婚恋证据项走现有 evidence 渲染）；若发现必须动前端，停下来写 PROGRESS。

## 5. 任务分解

### 任务 0 · 基线快照

- 在 `.worktrees/upstream-sync2-20260909` 用真实引擎跑三份 golden 存 `tests/golden/upstream_sync2/`：(a) `/api/relationship` 响应（公开名人案例，含 `dasha_info`）；(b) `/api/consultation_workflow` 婚恋问题响应的 `evidence_snapshot`；(c) `pl9-export` Markdown 里「时间系统证据状态」表。
- 记录开工测试数：`.venv/bin/python -m pytest tests -q -x --co | tail -1`、`npm test` 总数。

验收：三份 golden 进仓库；PROGRESS 记录命令。

### 任务 1 · 快照推进

- `scripts/import_yinduzhanxing.py --source /workspace/yinduzhanxing --source-commit b9a0ef8f… --dry-run` 在干净 worktree 跑，再 `--apply`；manifest 输出到 `references/cross_project_contract/imports/commit-b9a0ef8f….json`；`source-manifest.json` 更新 `source_commit / source_git_tree / boundary`（注明 `branch=codex/add-birth-time-rectification-skill, not on main`）。
- `references/upstream/yinduzhanxing/SKILL.md` 镜像为上游 6.9.15（与 main 只差版本号两行）。

验收：`tests/test_cross_project_contract*.py` 绿；manifest `privacy_scan.status == pass`；`sync_ledger.json` 追加一行。

### 任务 2 · 婚恋三层触发模型

1. 直接覆盖（与上游 main 字节一致的四个文件）：`scripts/relationship_analysis.py`、`references/yoga_rules.json`、`references/event_judgment_marriage.md`、`references/strict-workflow-router.md`，取分支版本。
2. 新增 `scripts/punarphoo.py`；`scripts/dasha_calculator_enhanced.py` 三方合并（0 冲突）。
3. `mcp_server.py` 只搬三处：`from punarphoo import detect_punarphoo`、`present["punarphoo"] = detect_punarphoo(...)`、`_collect_strict_evidence` 里 `romantic_activation` 观察块与 `secondary_context` 两项、`missing_evidence` 白名单加 `"punarphoo"`。**不搬**岁差改 `Optional[None]` 与 `_pl9_ayanamsa_selection_required_response`（本仓岁差已按 profile 传）。
4. `references/technique_registry.json` 手加 `punarphoo`（字段照上游条目，`version` 写 `6.9.16`）；`references/oracle/commercial_skill_truth_overlay.v1.json` 加 `punarphoo: status=partial, claim_boundary="observation_only; not marriage; holdout not passed"`；计数断言（`tests/test_capability_evidence_pool.py` 的 `89 capability entries`、README 徽章、`tests/test_readme_badges.py`）改为新值，PROGRESS 三栏说明。
5. `_compute_relationship` L7838 改为 `analyze_relationship(planets_for_analysis, asc_sign, dasha_info=body.get('dasha_info') if isinstance(body.get('dasha_info'), dict) else None)`（只在传了 `dasha_info` 时输出 `event_class_split`，`/api/relationship` 旧调用方响应不变）。新模块 `scripts/relationship_event_class_evidence.py`：`build_event_class_evidence(relationship: dict, theme_evidence) -> list[dict]`，把 `event_class_split` 变成 1–3 条 `_theme_evidence` 形状的证据项（`Romantic-activation`（观察级，`polarity=neutral`，`strength=weak`）、`Relationship-formation`、`Legal-marriage`（仅当 MD/AD 命中）），每条 `details` 带 `hits / pd_hits / claim_boundary`；`_derived_marriage_evidence` 末尾一行 `items.extend(build_event_class_evidence(relationship, self._theme_evidence))`。现有 `DK-UL-Dasha timing` 项保留不动。
6. 商业 `SKILL.md` 路由段加两句：婚恋问题第一句冻结事件类（`romantic_activation / relationship_formation / legal_marriage`）；Dasha 日期只许引用引擎输出、不得自算 `DASHA_ORDER`。咨询 prompt 里 relationship 主题的硬约束行同步（找 `_build_chart_prompt_pack` 现有主题约束的落点，只加一行）。
7. 测试：搬 `tests/test_punarphoo_observation.py`、`test_mcp_strict_workflow_relationship.py` 新增用例（去真实生日）；新增 `tests/test_relationship_event_class_evidence.py`：Moon–Saturn 7 宫合相 + Venus AD 的构造盘 → 出现 `Romantic-activation` 与 `Legal-marriage` 两条且前者 `strength=weak`；PD 命中不产生 `Legal-marriage`。

验收：

- [ ] `pytest tests/test_punarphoo_observation.py tests/test_mcp_strict_workflow_relationship.py tests/test_relationship_event_class_evidence.py tests/test_capability_evidence_pool.py tests/test_readme_badges.py` 全绿。
- [ ] 任务 0 golden (a)(b) 逐键存在且类型一致；新增键只多不少。
- [ ] `grep -rn "婚姻机会" scripts/relationship_analysis.py scripts/dasha_calculator_enhanced.py` 为 0 命中。
- [ ] 快速门 `run_quality_gate.py --profile quick` 通过。

### 任务 3 · 条件大运族接入 full reading 与长报告

1. 新增 11 个模块（10 套 dasha + `source_bounded_child_periods.py`），取分支版本原样；模块内 `from scripts.source_bounded_child_periods import …` 的导入要兼容本仓两种运行方式（`scripts/` 直跑与包内），照 `professional_report_reference.py` `_load_engine` 的双路径写法。
2. `cmd_full_reading`（本仓 L16309 `birth_info_for_alt_dasha`）：加上游 5 个键（`ascendant_longitude / sun_longitude / ascendant_sign_index / ascendant_hora_lord / navamsa_ascendant_sign_index / venus_rasi_sign_index / venus_navamsa_sign_index / tenth_lord_sign_index`，按上游 hunk 原样），Kala Chakra 之后加 Shastihayani 单独块与 9 套循环块；`pdf_edition` 分支不搬（本仓无该参数），子周期 profile 固定用 `PYJHORA_PARENT_SEEDED_EQUAL_SPLIT_PROFILE`。
3. `_native_dasha_master_families`（L2639）mapping 加 10 个键（`tribhagi / tribhagi_40 / shodashottari / dwadashottari / dwisaptatisama / shattrimshatsama / panchottari / satabdika / chaturshitisama / shastihayani`）；`_native_dasha_family_status`（L2650 调用处）识别模块返回的 `execution_status == 'not_applicable'`，映射为 `status='not_applicable'` 且 `reason` 带适用条件文字；`_family_status_row`（L4027）加 `not_applicable` 分支（现在会把它当 blocked 走 L4039）。
4. `render_pl9_markdown` 「时间系统证据状态」表：`_family_status_row` 之后按上游 104–120 编号顺序加 10 行；`not_applicable` 显示为 `调用状态=not_applicable`、`结论强度=—`、边界写条件（例如「Shodashottari：需上升在太阳 Hora 且白分 / 月亮 Hora 且黑分」）；`executed` 一律 `parameter_sensitive`。L4019 的 fallback mapping 同步加键。
5. `scripts/consultation_engine_field_bridge.py`（L273 附近）与 `scripts/commercial_skill_truth.py` 的模块列表：新 10 个模块**不进**咨询 bundle（聊天不变），只进报告；PROGRESS 写明。
6. 注册表加 10 项（`status=partial`，`user_visibility=expert_audit`，`commands=["full-reading"]`，`output_paths=modules.<key>`）；overlay 同步；计数断言随任务 2 一起改。
7. 测试：搬上游 `tests/test_<family>_dasha.py` 10 个（去真实生日；`*_pyjhora_*_replay.py` 依赖研究 JSON 的不搬）；新增 `tests/test_full_reading_conditional_dashas.py`：公开名人盘 full reading 后 `modules` 含 10 个键、每个键要么有 `periods` 要么 `execution_status in {not_applicable, blocked}`；报告表格行数 = 5 + 10（+ Year Lord）。

验收：

- [ ] 上述测试全绿；`tests/test_full_report_quality_gate.py`、`tests/run_all.py` 不退。
- [ ] 任务 0 golden (c) 表格原 5 行文字不变，只在其后新增行。
- [ ] `_calc_dasa_convergence` 调用参数不变（git diff 里该调用零改动）。
- [ ] `pl9-export` 真实案例耗时增幅 ≤ 20%（PROGRESS 写前后秒数）。

### 任务 4 · 记录与发布件

- `docs/BUG_HISTORY.md`：不是 Bug 修复，不占编号；但 `_compute_relationship` 原「Venus/Jupiter/Moon 大运 = 婚恋机会」的假阳性按 §5 规则登记一条 `resolved`（编号见 §8），关联上游审计结论。
- `CHANGELOG.md`：「婚恋问题分心动 / 成对 / 领证三层作答；长报告时间系统表新增十套条件大运；Skill 6.9.16」。
- `skills/jyotish-vedic-astrology/versions/6.9.16/` 由 `scripts/skill_release_manifest.py` 规则生成，`scripts/skill_release_package.py` dry-run 通过。
- `docs/tasks/PROGRESS-upstream-sync2-20260909.md`：hunk 取舍表、冲突解决表、测试数前后、不取项清单。
- `docs/testing/upstream-sync2-20260909.md`：真人清单——staging 上问一句「我什么时候会结婚」，回答必须分层且不给 PD 级月份；生成一份长报告，时间系统表可见新行。

## 6. 让步顺序

1. 任务 3 第 4 步的表格「条件文字」可先只写 `not_applicable`（条件文案后补）。
2. 任务 3 第 7 步的 10 个上游单测可先搬 5 个（Shodashottari / Dwadashottari / Panchottari / Satabdika / Tribhagi），其余写进 BLOCKED.md。
3. 任务 2 第 6 步的 prompt 硬约束行（保留 SKILL.md 改动）。
4. **不可砍**：任务 0、任务 1、任务 2 第 1–5 / 7 步、任务 3 第 1–3 / 5 / 6 步、任务 4。

## 7. 开工前置命令

```bash
git -C /workspace/Jyotisha status -sb | head -1
git fetch origin --prune
git worktree add -b codex/upstream-sync2-20260909 .worktrees/upstream-sync2-20260909 origin/staging
cd .worktrees/upstream-sync2-20260909
git -C /workspace/yinduzhanxing fetch origin --prune && git -C /workspace/yinduzhanxing rev-parse origin/codex/add-birth-time-rectification-skill   # 须为 b9a0ef8f…；若上游又推了，记录新 SHA 并重跑 §1 的 diff --stat
python3 scripts/pre_work_check.py --remote-timeout 8 --command-timeout 45         # §9 预检（涉及远端同步）
.venv/bin/python scripts/import_yinduzhanxing.py --source /workspace/yinduzhanxing --source-commit <SHA> --dry-run --output /tmp/claude-1000/sync2-dryrun.json
.venv/bin/python -m pytest tests/test_full_report_quality_gate.py tests/test_capability_evidence_pool.py -q   # 基线
```

## 8. BUG 编号起点

`docs/BUG_HISTORY.md` 当前最大 `BUG-601`；602–606 已被两份校正任务书占用，`TASK-report-chart-render-20260909.md` 占 **607**。本单从 **BUG-608** 起（任务 4 的假阳性登记），开工时重新核对。