Harden Jyotish runtime evidence gates

docs/research/external_engine_blocker_research_2026_07_05.md

@@ -0,0 +1,49 @@
+# External Engine Blocker Research 2026-07-05
+
+Purpose: record what can be fixed locally vs. what remains blocked by external engines, licensing, or credentials.
+
+## PyJHora / JHora
+
+- PyPI package checked: `PyJHora`
+- Observed PyPI version: `4.8.7`
+- Upstream GitHub search top match: `naturalstupid/PyJHora`
+- Observed GitHub license: `AGPL-3.0`
+- Local status: `scripts/diagnose_pyjhora_adapter.py --json` reports `missing_dependency: jhora`
+- Local action now implemented: diagnostics expose install hint, ephemeris-data note, and AGPL boundary.
+
+Boundary:
+
+- Do not vendor PyJHora into this repo.
+- Do not make PyJHora a required runtime dependency.
+- Keep it as optional external benchmark / parity oracle.
+
+Install hint for a separate benchmark environment:
+
+```bash
+pip install PyJHora
+```
+
+## VedAstro
+
+- Public site checked: `https://vedastro.org/` returned reachable.
+- `https://api.vedastro.org/api` returned HTTP 404 for a direct root probe. This only proves host reachability; it does not prove a full-snapshot endpoint is configured.
+- Current local diagnostic: `scripts/diagnose_external_engine_adapters.py --json` reports VedAstro `available` in `official_extended` mode but with `premium_key_missing`.
+
+Closure rule:
+
+- Do not claim VedAstro cloud closure unless `vedastro_official.raw_response` is present in the runtime evidence packet.
+- Free tier can remain `blocked` or `partial`; API key is recommended for stable official full snapshot.
+
+## Current Aggregate Status
+
+- VedAstro: `available`, blocker `premium_key_missing`
+- PyJHora/JHora: `missing_dependency`, blocker `jhora`
+- jyotishganit: `available`, license `MIT`
+- Three-engine parity: `partial`, not complete.
+
+## Sources Checked
+
+- PyPI: `https://pypi.org/project/PyJHora/`
+- GitHub search/API result: `https://github.com/naturalstupid/PyJHora`
+- VedAstro site: `https://vedastro.org/`
+- VedAstro API host probe: `https://api.vedastro.org/api`

docs/research/final_output_acceptance_error_log_2026_07_04.md

@@ -0,0 +1,25 @@
+# Final Output Acceptance Error Log - 2026-07-04
+
+Purpose: read this log before editing final report / evidence packet artifacts. Keep errors here so the same status drift does not repeat.
+
+## Known Errors
+
+| ID | Error | Seen In | Impact | Prevention |
+|---|---|---|---|---|
+| FOA-001 | status metadata drift | `jhora_master_evidence_packet_REDACTED_DATE_REDACTED_TIME.v13.json` and later packet chain | Top-level packet said final, but metadata stayed stale/draft or old version. | `tests/test_final_jhora_evidence_packet_acceptance.py` asserts top-level status, metadata status, `current_version`, `packet_version`, and `canonical_packet`. |
+| FOA-002 | canonical packet drift | latest packet advanced to v24 while metadata still pointed at v15 | Agents may cite old packet as current truth. | Latest-version acceptance resolves numeric highest packet and requires metadata + ledger to point to that file. |
+| FOA-003 | stale next-step ledger | ledger still said next useful step was Chapter 04 after chapters 04-06, PDF, and raw appendix existed | User/operator can continue wrong workstream. | Ledger acceptance rejects the old Chapter 04 next-step phrase and requires an Acceptance/error-log gate next step. |
+| FOA-004 | blank PDF artifact | prior ReportLab PDF attempt was blank/invalid and discarded | A report artifact can exist but be unusable. | Acceptance requires PDF path, HTML path, rendered QA pages, and non-trivial file sizes. |
+| FOA-005 | chained latest-packet drift | `jhora_master_evidence_packet_REDACTED_DATE_REDACTED_TIME.v25.json` appeared after v24, then v26 appeared after v25 while metadata still pointed one version behind | Fixing only one packet can become stale as later packet versions appear. | Acceptance always resolves the numeric highest packet and checks that exact packet, not a hard-coded version. |
+| FOA-006 | wrong quality-gate CLI flag | `python3 scripts/run_quality_gate.py --runtime-truth` | The gate does not run; command exits with argument error. | Use `python3 scripts/run_quality_gate.py --profile runtime-truth`. |
+| FOA-007 | long runtime-truth gate timeout | `python3 scripts/run_quality_gate.py --profile runtime-truth` exited 124 after 120s in this Codex tool session | A broad gate may not provide timely evidence inside the current command window. | Run focused acceptance first, then split runtime-truth into compile, inventory, diagnostics, and pytest target groups. |
+| FOA-008 | captured quality-gate output hid the slow step | `scripts/run_quality_gate.py` used `capture_output=True` for child commands | Long gates appeared blank until timeout, making the stuck subcommand invisible. | `run()` now streams child output directly. |
+
+## Work Rule
+
+Before changing `scratch/local/pdf_review_123456/` final artifacts:
+
+1. Read this file.
+2. Run `python3 -m pytest -q tests/test_final_jhora_evidence_packet_acceptance.py`.
+3. For the broader runtime gate, prefer `PYTHONUNBUFFERED=1 python3 scripts/run_quality_gate.py --profile runtime-truth`; if it times out, split the gate into compile, inventory, diagnostics, and pytest target groups.
+4. If it fails, record the new error here before patching status/docs.

docs/research/interpretation_source_invocation_honesty_audit_latest.md

@@ -0,0 +1,61 @@
+# Interpretation Source Invocation Honesty Audit Latest
+
+Date: 2026-07-03
+
+## Verdict
+
+There are still local Jyotish information assets that have not been fully proven as invoked by the runtime interpretation chain.
+
+This audit does not claim every character has been semantically read and promoted. It records the current provable boundary.
+
+## Fast Evidence
+
+- `references/` files: 535
+- `references/open_source_sources/` files: 299
+- `references/real_case_studies/` files: 5
+- `docs/research/` files: 543
+- non-standard / binary / notebook / config assets under `references docs/research`: 53
+
+Existing inventory / grading artifacts found:
+
+- `docs/research/character_level_inventory_manifest_latest.md`
+- `docs/research/character_level_external_manifest_latest.md`
+- `docs/research/character_level_source_grading_batch1_latest.md`
+- `docs/research/interpretation_source_full_classification_2026_07_02.md`
+- `docs/research/interpretation_source_priority1_batch1_promotion_audit_2026_07_02.md`
+
+These prove that character-level indexing and batch1 grading exist. They do not prove full runtime invocation for every local source asset.
+
+## Not Fully Closed
+
+1. Open-source source trees are not all proven as interpretation sources:
+   - `references/open_source_sources/jyotishganit`
+   - `references/open_source_sources/jaimini-tropical`
+   - `references/open_source_sources/VedicAstro` notebooks/test suites
+   - `references/open_source_sources/rishi-ai-mcp`
+   - `references/open_source_sources/vedic-astro-skills`
+   - `references/open_source_sources/dashaflow`
+
+2. Non-standard assets require separate extraction before source grading:
+   - `.ipynb` notebooks
+   - images
+   - config/rule files
+   - lockfiles / package metadata
+   - generated PDFs or PDF-related assets if present in later scans
+
+3. `docs/research/` remains mostly research/history/draft territory. It must stay classified and cannot automatically override runtime truth.
+
+4. Existing source grading is batch-based. Batch1 exists; full priority1 and all candidate assets are not proven closed.
+
+## Required Next Step
+
+Build a fast, reusable coverage tool that maps every candidate source file to:
+
+- extraction status
+- source grade
+- promotion status
+- runtime source-pack visibility
+- strict workflow visibility
+- exclusion reason when not promoted
+
+Then run it in CI/quality gate so this question has a machine-checkable answer.

docs/research/interpretation_source_runtime_consumption_audit_2026_07_03.md

@@ -0,0 +1,57 @@
+# Interpretation Source Runtime Consumption Audit 2026-07-03
+
+## Scope
+
+Follow-up to the existing inventory gate and advanced pipeline contract. This audit checks whether already-classified interpretation source layers are consumed by strict workflows without rebuilding the inventory system.
+
+## Result
+
+- `scripts/interpretation_source_inventory_gate.py`: pass.
+- Candidate pool: 956.
+- Unclassified candidates: 0.
+- Source pack status: used.
+- Runtime strict workflows now assert consumption of the promoted batch2 topic layers via secondary context markers.
+
+## Consumed Runtime Markers
+
+The career, finance, and relationship strict workflow tests now require:
+
+- `dasha_timing_layer_used`
+- `varga_strength_layer_used`
+- `annual_special_layer_context`
+- `modifier_obstacle_layer_used`
+
+These markers prove that the batch2 topic layer is not merely visible in the source pack; it is carried into adjudication context.
+
+## Tests Updated
+
+- `tests/test_mcp_strict_workflow_career.py`
+- `tests/test_mcp_strict_workflow_finance.py`
+- `tests/test_mcp_strict_workflow_relationship.py`
+
+The tests no longer require `secondary_context` to equal an old fixed list. They now require the original business signals plus the promoted source-layer markers.
+
+## Verification
+
+Passed:
+
+```bash
+python3 -m pytest -q \
+  tests/test_mcp_strict_workflow_career.py \
+  tests/test_mcp_strict_workflow_finance.py \
+  tests/test_mcp_strict_workflow_relationship.py \
+  tests/test_interpretation_source_inventory_gate.py \
+  tests/test_interpretation_source_advanced_pipeline_contract.py \
+  tests/test_interpretation_source_next_phase_contract.py \
+  tests/test_interpretation_source_core5_strict_visibility.py
+```
+
+Result: 94 passed.
+
+Also passed: `git diff --check`.
+
+## Boundary
+
+No runtime source-pack rebuild was done. No quarantined or draft sources were promoted.
+
+`python3 scripts/run_quality_gate.py --profile quick ...` exceeded the 120s command timeout in this session, so the quick gate was not used as completion evidence.

docs/research/open_source_batches_runtime_reference_audit_2026_07_03.md

@@ -0,0 +1,68 @@
+# Open Source Batches Runtime Reference Audit 2026-07-03
+
+## Scope
+
+Advance the next queued open-source reference batches without turning them into primary truth:
+
+- `rishi_ai_mcp_batch1`
+- `vedic_astro_skills_batch1`
+
+Also expose the remaining external gaps requested by the user:
+
+- VedAstro official default closure
+- external oracle parity
+- install / usage path slimming
+
+## Runtime Wiring
+
+`mcp_server._existing_interpretation_source_pack()` now exposes:
+
+- `rishi_ai_mcp_batch1_layer`
+  - status: `available`
+  - source refs: 16
+  - mapped domains: career, finance, relationship, children, health, full_reading
+  - runtime truth status: `not_primary_truth`
+
+- `vedic_astro_skills_batch1_layer`
+  - status: `available`
+  - source refs: 8
+  - mapped domains: core, reader_validation, career, relationship, rectification, calculator
+  - runtime truth status: `not_primary_truth`
+
+- `external_closure_gap_layer`
+  - `vedastro_official.status = blocked`
+  - `oracle_parity.status = blocked`
+  - `install_usage_path.status = needs_slimming`
+
+## Queue Update
+
+Completed as visible reference layers:
+
+- `real_case_studies_batch1`
+- `rishi_ai_mcp_batch1`
+- `vedic_astro_skills_batch1`
+
+Remaining queue:
+
+- `references_batch2`
+- `vedastro_official_default_closure`
+- `external_oracle_parity_batch`
+- `install_usage_path_slimming`
+
+## Classification Boundary
+
+Open-source sources remain classified as `open_source_reference` unless they were already governed runtime refs such as existing QA / reader / yoga resources. This prevents new open-source material from overriding local strict rules or oracle-calibrated calculations.
+
+## Verification
+
+Passed:
+
+```bash
+python3 -m pytest -q \
+  tests/test_interpretation_source_inventory_gate.py \
+  tests/test_interpretation_source_next_phase_contract.py \
+  tests/test_interpretation_source_advanced_pipeline_contract.py \
+  tests/test_mcp_strict_workflow_career.py \
+  tests/test_mcp_strict_workflow_finance.py \
+  tests/test_mcp_strict_workflow_relationship.py
+```

docs/research/open_source_integration_priority_table_2026_07_03.md

@@ -0,0 +1,197 @@
+# 开源项目接入优先级落地表
+
+日期: 2026-07-03
+
+目的: 把仓内已经存在的开源镜像、黑盒基准、官方桥接入口，整理成一张可执行落地表。只写当前仓库里有真实文件可指认的对象，不靠聊天记忆。
+
+边界先钉死:
+
+- 主运行链 source of truth 仍是本仓 `scripts/`、`mcp_server.py`、`references/`、`tests/`、`jyotish-app/`。
+- `.workbuddy` 不是 runtime truth。
+- `PyJHora` 只能走黑盒输出证据路径，不能把 AGPL 代码抄进 permissive 主链。
+- `open_source_reference` 可以进参考层、审计层、提示层，不自动升级成 primary truth。
+
+相关现状依据:
+
+- 主链地图: [docs/research/unique_main_chain_map_2026_07_01.md](/Users/wuyongnaren/Documents/印度占星/docs/research/unique_main_chain_map_2026_07_01.md)
+- 开源参考层已挂载说明: [docs/research/open_source_batches_runtime_reference_audit_2026_07_03.md](/Users/wuyongnaren/Documents/印度占星/docs/research/open_source_batches_runtime_reference_audit_2026_07_03.md)
+- 已接入 smoke test: [tests/test_open_source_integrations.py](/Users/wuyongnaren/Documents/印度占星/tests/test_open_source_integrations.py)
+
+## 状态定义
+
+- `已接`: 已有代码进入主仓脚本或 runtime reference pack，且有测试/文档证明。
+- `半接`: 仓里有镜像或桥接脚本，但还没压进默认主链，或只在参考层可见。
+- `未接`: 仓里有资料，但当前没有实际接线点。
+
+## 优先级总表
+
+| 优先级 | 开源对象（仓内真实文件） | 当前状态 | 接哪里 | 用来干什么 | 许可证风险 | 预计几小时落地 |
+|---|---|---|---|---|---|---|
+| P0 | `references/open_source_sources/panchanga_api/README.md` `references/open_source_sources/panchanga_api/MCP.md` `references/open_source_sources/panchanga_api/SKILL.md` | 半接 | `scripts/prashna.py` `scripts/remedies.py` `scripts/jyotish_api_server.py` `scripts/unified_consultation_orchestrator.py` `jyotish-app/main.js` | 把“时间问事 / Muhurta / Panchanga / Remedies”压到统一入口，复用你刚接好的 `prashna` 与 `audited_remedies` 主链 | 低。镜像内 README 指向 MIT；当前仓内有 `LICENSE` | 4-8h |
+| P0 | `scripts/vedastro_service_adapter.py` `scripts/vedastro_official_mcp_bridge.py` `scripts/diagnose_vedastro_mode.py` | 半接 | `scripts/jyotish_api_server.py` `mcp_server.py` `scripts/unified_consultation_orchestrator.py` | 让 official layer 真正默认参与，而不是只做桥接存在证明；同时把 runtime truth 里的 `official/full/partial/fallback` 说清楚 | 低。这里主要是官方 API/桥接，不是复制外部 GPL 代码 | 3-6h |
+| P0 | `references/oracle/artifacts/pyjhora_*` `references/oracle/artifacts/pending_packets/*pyjhora*.json` `scripts/generate_pyjhora_oracle_artifact_manifest.py` | 已接（黑盒证据层） | `scripts/external_oracle_sanity_closure.py` `scripts/oracle_benchmark_inventory.py` `scripts/historical_event_backtest.py` `README.md` | 保留 PyJHora 作为黑盒对照、历史事件回测、数值 sanity，不碰源码复制 | 中高。AGPL 风险不在“调用输出”，而在“复制代码/常量/实现” | 1-3h 做下一轮批量证据清点；8-16h 做更完整事件包 |
+| P1 | `references/open_source_sources/jyotishganit/README.md` `references/open_source_sources/jyotishganit/LICENSE` `references/open_source_sources/jyotishganit/jyotishganit/*` | 已接（部分） | `scripts/bhava_bala.py` `scripts/shadbala.py` `scripts/shadbala_advanced.py` `scripts/trimshamsa_d30.py` `scripts/constants/mit_imported_constants.py` `scripts/jyotish_engine.py` | 继续把 MIT 安全算法/常量吸收到本地精度层，尤其是 `Bhava Bala`、`Sputa Drishti`、部分 divisional / constants 对齐 | 低。MIT，且本仓已有显式标注“基于 jyotishganit” | 2-6h 做一轮定点补强；10-20h 做系统 sweep |
+| P1 | `references/open_source_sources/jaimini-tropical/README.md` `references/open_source_sources/jaimini-tropical/LICENSE` | 已接（部分） | `scripts/jaimini.py` `scripts/argala.py` `tests/test_open_source_integrations.py` `references/strict-workflow-router.md` | 补强 Jaimini/Arudha/Argala 这条线，让婚恋、事业、财富裁决里对 `AL/UL/Karaka/Argala` 的引用更硬 | 低。MIT | 2-5h |
+| P1 | `references/open_source_sources/dashaflow/*` | 已接（部分），但镜像证据不完整 | `scripts/jaimini.py` `scripts/synastry.py` `tests/test_open_source_integrations.py` | 继续利用现成 `Arudha Pada`、附加合婚 kutas、Jaimini 辅助能力；少写重复代码 | 中。当前镜像目录里没看到本地 `LICENSE` 文件，虽在别的 README 中被描述为 MIT，也要补 upstream commit + license 证据 | 2-4h 补许可证锚点；4-8h 做能力扩展 |
+| P1 | `references/open_source_sources/VedicAstro/README.md` `references/open_source_sources/VedicAstro/vedicastro/horary_chart.py` `references/open_source_sources/VedicAstro/test_suite/horary_functions_test.py` | 半接 | `scripts/prashna.py` `scripts/kp_system.py` `scripts/ephemeris_backend_probe.py` `tests/` 新 smoke | 作为 KP/Horary 参考源，补“时间问事”与 KP sub-lord 边界，不直接重写主引擎 | 低。MIT | 3-6h |
+| P2 | `references/open_source_sources/vedic-astro-skills/README.md` `references/open_source_sources/vedic-astro-skills/antigravity/skills/...` | 半接（参考层已可见） | `mcp_server.py::_existing_interpretation_source_pack()` `references/strict-workflow-router.md` `jyotish-app` prompt pack / guided topics | 主要拿方法学、问答流程、reader validation、rectification 提示结构；不当计算真值层 | 低。MIT | 2-4h |
+| P2 | `references/open_source_sources/rishi-ai-mcp/README.md` `references/open_source_sources/rishi-ai-mcp/rishi_ai_mcp.py` | 半接（参考层已可见） | `mcp_server.py::_existing_interpretation_source_pack()` `references/` 主题词映射 `prompt pack` | 拿主题分流、问答组织、relationship/finance/career topic taxonomy；不替代本地 strict workflow | 低。MIT | 2-4h |
+
+## 一条一条展开
+
+### 1. `panchanga_api` → 最该先接
+
+仓内文件:
+
+- [references/open_source_sources/panchanga_api/README.md](/Users/wuyongnaren/Documents/印度占星/references/open_source_sources/panchanga_api/README.md)
+- [references/open_source_sources/panchanga_api/MCP.md](/Users/wuyongnaren/Documents/印度占星/references/open_source_sources/panchanga_api/MCP.md)
+- [references/open_source_sources/panchanga_api/SKILL.md](/Users/wuyongnaren/Documents/印度占星/references/open_source_sources/panchanga_api/SKILL.md)
+
+为什么优先:
+
+- 你现在已经有 [scripts/prashna.py](/Users/wuyongnaren/Documents/印度占星/scripts/prashna.py)、[scripts/remedies.py](/Users/wuyongnaren/Documents/印度占星/scripts/remedies.py)、统一入口 [scripts/unified_consultation_orchestrator.py](/Users/wuyongnaren/Documents/印度占星/scripts/unified_consultation_orchestrator.py)。
+- 缺的不是“再发明一套 Prashna/Remedies”，而是把现有入口压得更完整。
+- `panchanga_api` 文档本身就覆盖 `prashna`、`muhurta`、`vrata`、`remedies`，跟你当前三入口结构天然贴合。
+
+最省事接法:
+
+1. `prashna` 入口复用现有 `entry_mode == "prashna"`。
+2. `remedies` 继续只吃 `strict_audit_gate` 过滤后的输入。
+3. 单独补一个 `muhurta/panchanga` 轻 sidecar，不碰主 chart engine。
+
+### 2. VedAstro official bridge → 必须继续压实
+
+仓内文件:
+
+- [scripts/vedastro_service_adapter.py](/Users/wuyongnaren/Documents/印度占星/scripts/vedastro_service_adapter.py)
+- [scripts/vedastro_official_mcp_bridge.py](/Users/wuyongnaren/Documents/印度占星/scripts/vedastro_official_mcp_bridge.py)
+- [scripts/diagnose_vedastro_mode.py](/Users/wuyongnaren/Documents/印度占星/scripts/diagnose_vedastro_mode.py)
+
+为什么优先:
+
+- 这不是“有没有桥”。桥已经有。
+- 真缺口是: 默认主链什么时候自动用官方层、什么时候 cache 命中、什么时候 free-tier queue、什么时候 fallback。
+- 这条一旦压实，web / MCP / skill 才会统一口径。
+
+最省事接法:
+
+1. 继续只走现有 adapter / official bridge。
+2. 不新增第二套 VedAstro planner。
+3. 把 `runtime_truth` 直接下沉到前端结果页、MCP strict 输出、full-reading。
+
+### 3. PyJHora → 只许黑盒，不许抄
+
+仓内文件:
+
+- [references/oracle/artifacts/pyjhora_oracle_artifact_manifest.json](/Users/wuyongnaren/Documents/印度占星/references/oracle/artifacts/pyjhora_oracle_artifact_manifest.json)
+- [scripts/generate_pyjhora_oracle_artifact_manifest.py](/Users/wuyongnaren/Documents/印度占星/scripts/generate_pyjhora_oracle_artifact_manifest.py)
+- 多个 `references/oracle/artifacts/pyjhora_*.txt`
+
+当前定位:
+
+- 它已经在 repo 里，但不是“可接入 runtime 的代码镜像”。
+- 它是“黑盒 external evidence 层”。
+
+最省事接法:
+
+1. 继续扩证据包，不扩源码依赖。
+2. 让 `historical_event_backtest`、`oracle parity`、`benchmark dashboard` 直接吃 artifact。
+3. 不把任何 PyJHora 常量表、实现细节搬进 `scripts/`。
+
+### 4. `jyotishganit` → 已有真吸收，继续吃 MIT 安全部分
+
+仓内文件:
+
+- [references/open_source_sources/jyotishganit/README.md](/Users/wuyongnaren/Documents/印度占星/references/open_source_sources/jyotishganit/README.md)
+- [references/open_source_sources/jyotishganit/LICENSE](/Users/wuyongnaren/Documents/印度占星/references/open_source_sources/jyotishganit/LICENSE)
+- 已接痕迹:
+  - [scripts/bhava_bala.py](/Users/wuyongnaren/Documents/印度占星/scripts/bhava_bala.py)
+  - [scripts/shadbala.py](/Users/wuyongnaren/Documents/印度占星/scripts/shadbala.py)
+  - [scripts/shadbala_advanced.py](/Users/wuyongnaren/Documents/印度占星/scripts/shadbala_advanced.py)
+  - [scripts/trimshamsa_d30.py](/Users/wuyongnaren/Documents/印度占星/scripts/trimshamsa_d30.py)
+  - [scripts/constants/mit_imported_constants.py](/Users/wuyongnaren/Documents/印度占星/scripts/constants/mit_imported_constants.py)
+
+为什么适合继续接:
+
+- 这条已经不是“设想”。
+- 本仓已经明确写了“基于 jyotishganit (MIT License) 算法适配”。
+- 所以这里最值钱的是继续定点补 math，不是重新造壳。
+
+### 5. `jaimini-tropical` + `dashaflow` → 已经接进脚本层，值得继续榨干
+
+仓内文件:
+
+- [references/open_source_sources/jaimini-tropical/README.md](/Users/wuyongnaren/Documents/印度占星/references/open_source_sources/jaimini-tropical/README.md)
+- [references/open_source_sources/jaimini-tropical/LICENSE](/Users/wuyongnaren/Documents/印度占星/references/open_source_sources/jaimini-tropical/LICENSE)
+- [references/open_source_sources/dashaflow/](/Users/wuyongnaren/Documents/印度占星/references/open_source_sources/dashaflow)
+- 已接证明: [tests/test_open_source_integrations.py](/Users/wuyongnaren/Documents/印度占星/tests/test_open_source_integrations.py)
+- 当前脚本:
+  - [scripts/jaimini.py](/Users/wuyongnaren/Documents/印度占星/scripts/jaimini.py)
+  - [scripts/argala.py](/Users/wuyongnaren/Documents/印度占星/scripts/argala.py)
+  - [scripts/synastry.py](/Users/wuyongnaren/Documents/印度占星/scripts/synastry.py)
+
+为什么不是 P0:
+
+- 这条已经有接入 smoke test。
+- 现在更大的缺口不在“有没有 A1/A10/UL/Argala”，而在“这些结果有没有被 strict workflow 主裁决强制消费”。
+
+特殊风险:
+
+- `jaimini-tropical` 本地有 MIT `LICENSE`。
+- `dashaflow` 当前镜像目录未见本地 `LICENSE`。虽然现有文档多处把它当 MIT 参考，但落下一步代码前，应先补一条 canonical license 锚点。
+
+### 6. `VedicAstro` → 适合做 Horary/KP 辅助，不适合夺主链
+
+仓内文件:
+
+- [references/open_source_sources/VedicAstro/README.md](/Users/wuyongnaren/Documents/印度占星/references/open_source_sources/VedicAstro/README.md)
+- [references/open_source_sources/VedicAstro/vedicastro/horary_chart.py](/Users/wuyongnaren/Documents/印度占星/references/open_source_sources/VedicAstro/vedicastro/horary_chart.py)
+- [references/open_source_sources/VedicAstro/test_suite/horary_functions_test.py](/Users/wuyongnaren/Documents/印度占星/references/open_source_sources/VedicAstro/test_suite/horary_functions_test.py)
+
+为什么排 P1:
+
+- 你仓里已有 [scripts/prashna.py](/Users/wuyongnaren/Documents/印度占星/scripts/prashna.py) 和 [scripts/kp_system.py](/Users/wuyongnaren/Documents/印度占星/scripts/kp_system.py)。
+- 所以更值钱的是拿它校一遍 Horary/KP 边界，不是整包搬迁。
+
+### 7. `vedic-astro-skills` / `rishi-ai-mcp` → 继续留在参考层，别冒充真值层
+
+仓内文件:
+
+- [references/open_source_sources/vedic-astro-skills/README.md](/Users/wuyongnaren/Documents/印度占星/references/open_source_sources/vedic-astro-skills/README.md)
+- [references/open_source_sources/rishi-ai-mcp/README.md](/Users/wuyongnaren/Documents/印度占星/references/open_source_sources/rishi-ai-mcp/README.md)
+
+当前已接现状:
+
+- 参考层已挂进 [mcp_server.py](/Users/wuyongnaren/Documents/印度占星/mcp_server.py) 的 `interpretation_source_pack`
+- 研究文档已明确它们是 `not_primary_truth`
+
+为什么不该抢前排:
+
+- 它们更像“问答结构 / topic taxonomy / prompt discipline / reader validation”的参考材料。
+- 不适合替代本地 math、official evidence、strict audit gate。
+
+## 最省算力的执行顺序
+
+1. `panchanga_api` → 接 `prashna/remedies/muhurta` 统一入口
+2. VedAstro official bridge → 压实默认主链 official 优先
+3. `jyotishganit` → 做定点 math 补强
+4. `jaimini-tropical` / `dashaflow` → 让已有结果被 strict workflow 真消费
+5. `VedicAstro` → 做 Horary/KP smoke + 边界校验
+6. `vedic-astro-skills` / `rishi-ai-mcp` → 只升格高价值 reader/rectification 规则
+7. PyJHora → 继续只做黑盒证据扩容
+
+## 我给你的直白建议
+
+如果只选 3 项，最值钱的是:
+
+1. `panchanga_api`
+2. VedAstro official bridge default closure
+3. `jyotishganit` 定点精度补强
+
+原因很简单:
+
+- 第 1 项补“入口能力”
+- 第 2 项补“官方优先”
+- 第 3 项补“本地精度”
+
+这 3 项一起做，才是真正对用户可用性和严谨度都有立刻收益。

docs/research/pre_work_error_ledger.md

@@ -0,0 +1,67 @@
+# Pre-Work Error Ledger
+
+Purpose: read this file before substantial project work. It exists to stop repeat mistakes caused by multiple Codex windows, WorkBuddy mirrors, local drafts, backup folders, and partial cloud-git visibility.
+
+## Mandatory Pre-Work Check
+
+Run or consciously verify:
+
+```bash
+sed -n '1,220p' AGENTS.md
+sed -n '1,260p' docs/research/pre_work_error_ledger.md
+git status --short --branch
+git remote -v
+python3 scripts/pre_work_check.py --remote-timeout 8 --command-timeout 45
+```
+The one-command gate must cover:
+- `tests/test_runtime_import_boundaries.py`
+- `tests/test_project_fragment_governance.py`
+- `tests/test_preflight_fragment_scan.py`
+- `tests/test_remote_repo_visibility_check.py`
+- `tests/test_pre_work_check.py`
+
+For large architecture or release work, also read:
+
+- `docs/research/whole_machine_fragment_sweep_round25_2026_06_25.md`
+- `docs/research/whole_machine_fragment_sweep_2026_07_05.md`
+- `docs/research/unique_main_chain_map_2026_07_01.md`
+- `docs/research/local_drafts_2026_06_disposition.md`
+
+## Error Ledger
+
+| ID | Error / Risk | Current Status | Required Guard |
+|---|---|---|---|
+| ERR-001 | Runtime code pulled modules from `.workbuddy` distribution mirror. | resolved | Keep `tests/test_runtime_import_boundaries.py`; `.workbuddy` is reference only. |
+| ERR-002 | `mcp_server.py` documentation implied `.workbuddy` was a runtime path. | resolved | MCP top docs must point to main repo runtime; mirror wording must say distribution/reference only. |
+| ERR-003 | `local_drafts` mixed high-value research with disposable drafts. | mitigated | Use `docs/research/local_drafts_2026_06_disposition.md`; do not delete or promote drafts ad hoc. |
+| ERR-004 | Multiple local folders contain Jyotish fragments, older adapters, and WorkBuddy mirrors. | active | Read latest fragment sweep before changing adapters, oracle paths, or skill runtime boundaries. |
+| ERR-005 | Terminal git access to GitHub can fail even when the browser can open the repo. | active | Use `python3 scripts/remote_repo_visibility_check.py`; do not claim cloud sync unless status is `verified`. |
+| ERR-006 | Whole-machine `find` can time out when run too broadly. | active | Use split scans by directory and bounded `-maxdepth`; record timeouts as findings. |
+| ERR-007 | `.workbuddy/skills/jyotish-vedic-astrology` is a dirty historical mirror. | active | Never copy it over main repo. Use only for read-only comparison. |
+| ERR-008 | Current main workspace may be dirty with user/Codex changes. | active | Never reset or checkout. Read touched files before editing. |
+| ERR-009 | Astrology interpretation can drift into story-fitting from conversation history. | active | For blind technical reports, use only declared evidence packets/PDF and mark MEVG/real-case gaps. |
+| ERR-010 | VedAstro official/cloud evidence can be partial or dasha-conflicting. | active | Mark official closure partial unless exact endpoint/settings and raw output are verified. |
+| ERR-011 | Bare `pytest` command may be missing from PATH even when pytest module exists. | active | Use `python3 -m pytest ...` in acceptance commands. |
+| ERR-012 | Governance tests can fail if wording is narrower than the actual guardrail. | observed 2026-07-05 | Keep tests tied to explicit user-facing terms such as `开工前` and the ledger path. |
+| ERR-013 | GitHub API can fail from terminal Python even when browser/Web can open GitHub. | active | Treat `remote_repo_visibility_check.py` status `blocked` as authoritative for terminal parity; browser visibility alone is not sync proof. |
+| ERR-014 | Pre-work checks can be skipped when split across several manual commands. | mitigated | Use `python3 scripts/pre_work_check.py` as the one-command pre-work gate. |
+| ERR-015 | One-command pre-work can exceed desktop outer timeout if child command timeout is too wide or scan runs twice. | observed 2026-07-05 | Keep pytest child timeout bounded at 45s; let `pre_work_check.py` cache `preflight_fragment_scan.py` output for `tests/test_preflight_fragment_scan.py`. |
+| ERR-016 | Full `tests/test_api_server_security.py` can exceed the desktop outer timeout. | observed 2026-07-05 | Use focused API test slices during development; reserve full API file run for longer verification windows. |
+| ERR-017 | Pre-work gate could pass without checking the older Round 25 fragment sweep or aggregate external-engine adapter diagnostics. | mitigated 2026-07-05 | `scripts/pre_work_check.py` must require both whole-machine sweep docs and run `scripts/diagnose_external_engine_adapters.py --json` before substantial work. |
+| ERR-018 | External engine blockers can be described verbally but not carried into diagnostics. | mitigated 2026-07-05 | `diagnose_external_engine_adapters.py` must expose VedAstro closure plan and PyJHora/JHora install/license/ephemeris boundary; keep `docs/research/external_engine_blocker_research_2026_07_05.md` current. |
+
+## Fragment Sweep Command Set
+
+Use split scans, not one unbounded full-home command:
+
+```bash
+for d in /Users/wuyongnaren/Documents /Users/wuyongnaren/WorkBuddy /Users/wuyongnaren/.workbuddy /Users/wuyongnaren/Downloads /Users/wuyongnaren/Desktop /Users/wuyongnaren/.codex/attachments; do
+  [ -d "$d" ] && find "$d" -maxdepth 6 -type d -name .git 2>/dev/null | sed 's#/.git$##'
+done | rg -i '印度|jyotish|vedic|astro|yinduzhanxing|workbuddy|星轨|codex|talk' | sort
+```
+
+```bash
+for d in /Users/wuyongnaren/Documents /Users/wuyongnaren/WorkBuddy /Users/wuyongnaren/.workbuddy /Users/wuyongnaren/Downloads /Users/wuyongnaren/Desktop /Users/wuyongnaren/.codex/attachments; do
+  [ -d "$d" ] && find "$d" -maxdepth 7 -type f \( -iname '*jyotish*' -o -iname '*vedic*' -o -iname '*jhora*' -o -iname '*shadbala*' -o -iname '*ashtakoot*' -o -iname '*印度占星*' -o -iname '*yinduzhanxing*' \) 2>/dev/null
+done
+```

docs/research/real_case_batch1_runtime_retrieval_audit_2026_07_03.md

@@ -0,0 +1,35 @@
+# Real Case Batch1 Runtime Retrieval Audit 2026-07-03
+
+## Scope
+
+Promote already-classified `real_case_studies_batch1` from queue-only visibility into a callable local retrieval layer without treating it as primary truth.
+
+## Runtime Wiring
+
+`mcp_server._existing_interpretation_source_pack()` now exposes:
+
+- `real_case_calibration_layer.status = queued`
+- `real_case_calibration_layer.index_status = available`
+- `real_case_calibration_layer.batch_id = real_case_studies_batch1`
+- domain buckets: `career`, `finance`, `relationship`, `health`, `rectification`, `timing`
+- source refs from `references/real_case_studies` and `docs/benchmark`
+
+`real_case_calibration.status` remains `blocked` because matching-case attachment and external MEVG calibration are still required before confidence can be lifted.
+
+## Cleanup Boundary
+
+Duplicate / obsolete / quarantine files were not physically deleted in this patch. They remain hard-excluded from runtime truth by the inventory gate and source-pack tests. This avoids deleting local research history while preventing contamination of the interpretation chain.
+
+## Verification
+
+Passed:
+
+```bash
+python3 -m pytest -q \
+  tests/test_interpretation_source_inventory_gate.py \
+  tests/test_interpretation_source_advanced_pipeline_contract.py \
+  tests/test_interpretation_source_next_phase_contract.py \
+  tests/test_mcp_strict_workflow_career.py \
+  tests/test_mcp_strict_workflow_finance.py \
+  tests/test_mcp_strict_workflow_relationship.py
+```

docs/research/whole_machine_fragment_sweep_2026_07_05.md

@@ -0,0 +1,79 @@
+# Whole-Machine Jyotish Fragment Sweep 2026-07-05
+
+## Scope
+
+Read-only sweep for project source, local mirrors, Codex work folders, WorkBuddy copies, downloads, desktop artifacts, and configured cloud git remote. No files were deleted or moved.
+
+## Git State
+
+Current workspace:
+
+- Path: `/Users/wuyongnaren/Documents/印度占星`
+- Branch: `codex/release-hygiene-ci`
+- Upstream: `origin/codex/release-hygiene-ci`
+- Remote fetch: `git@github.com:732642856/yinduzhanxing.git`
+- Remote push: `https://github.com/732642856/yinduzhanxing.git`
+- Worktree: dirty; do not reset or overwrite user changes.
+
+Remote checks:
+
+- `git ls-remote --heads --tags origin` failed with `ssh: connect to host github.com port 22: Operation timed out`.
+- `git ls-remote --heads --tags https://github.com/732642856/yinduzhanxing.git` failed with `LibreSSL SSL_connect: SSL_ERROR_SYSCALL in connection to github.com:443`.
+- `python3 scripts/remote_repo_visibility_check.py` now records this state structurally and sets `must_not_claim_synced: true` unless terminal refs are verified.
+- `python3 scripts/remote_repo_visibility_check.py --timeout 8` returned `status: blocked`; SSH timed out, HTTPS git returned `SSL_ERROR_SYSCALL`, and GitHub API returned `UNEXPECTED_EOF_WHILE_READING`.
+- `python3 scripts/pre_work_check.py --remote-timeout 8 --command-timeout 45` later returned `status: pass` with `must_not_claim_synced: false`; network was observed to fluctuate, so this proves terminal visibility for that run, not that local dirty work was pushed.
+- Browser/Web access to `https://github.com/732642856/yinduzhanxing` succeeded.
+- Browser/Web branch page shows repository is public, default `main` updated Jun 13, 2026, and active `codex/release-hygiene-ci` updated Jul 2, 2026.
+- Browser/Web commit page for `main` shows latest visible commit `4ff6248 Complete v6.9.14 precision modules` on Jun 13, 2026.
+
+Conclusion: cloud repo exists and is browser-readable, but terminal ref parity is `blocked` for this sweep.
+
+## Local Git Repositories Found
+
+Relevant candidates from bounded split scan:
+
+- `/Users/wuyongnaren/Documents/印度占星` — current main workspace; only implementation target.
+- `/Users/wuyongnaren/.workbuddy/skills/jyotish-vedic-astrology` — dirty historical/distribution mirror; read-only reference.
+- `/Users/wuyongnaren/.workbuddy/skills` — WorkBuddy skills container.
+- `/Users/wuyongnaren/Documents/星轨talk` — adjacent talk engine repo with Jyotish adapters.
+- `/Users/wuyongnaren/Documents/Codex/2026-06-20/732642856-talk-https-github-com-732642856/work/talk-active` — older Codex talk worktree.
+- `/Users/wuyongnaren/Documents/Codex/2026-06-20/732642856-talk-https-github-com-732642856/work/talk` — older Codex talk worktree.
+- `/Users/wuyongnaren/Documents/Codex/2026-06-18/new-chat-4/work/starcanvas` — adjacent astrology/canvas project.
+- `/Users/wuyongnaren/Documents/Codex/2026-06-18/new-chat-4/work/starcanvas-active` — adjacent astrology/canvas project.
+- `/Users/wuyongnaren/Documents/星轨画布` — adjacent astrology/canvas project.
+- `/Users/wuyongnaren/WorkBuddy` and dated WorkBuddy folders — historical/reference material.
+
+## High-Value Fragment Files
+
+Keep these in mind before adapter/oracle/skill work:
+
+- `/Users/wuyongnaren/Documents/星轨talk/engines-repo/jyotish/jyotish-adapter.js`
+- `/Users/wuyongnaren/Documents/星轨talk/engines-repo/jyotish/vedic-calc-runner.py`
+- `/Users/wuyongnaren/Documents/星轨talk/engines-repo/jyotish/jyotishganit-adapter.js`
+- `/Users/wuyongnaren/Documents/星轨talk/engines-repo/jyotish/jyotishganit-runner.py`
+- `/Users/wuyongnaren/Documents/星轨talk/engines-repo/local-jyotish-reference-audit.js`
+- `/Users/wuyongnaren/Documents/星轨talk/reports/local-jyotish-reference-audit.md`
+- `/Users/wuyongnaren/Documents/ObsidianVault/03_研究_术数占星/印度占星 Jyotish.md`
+- `/Users/wuyongnaren/Documents/ObsidianVault/03_研究_术数占星/印度占星研究结论 v3.md`
+- `/Users/wuyongnaren/Documents/ObsidianVault/03_研究_术数占星/一楠 · 印度占星完整解盘报告 v2.md`
+- `/Users/wuyongnaren/Documents/Codex/2026-06-20/732642856-yinduzhanxing-https-github-com-732642856/outputs/yinduzhanxing_local_audit_2026-06-20.md`
+
+## Boundaries
+
+- Main repo remains the runtime source of truth.
+- `.workbuddy` is historical/distribution reference only.
+- Obsidian, Downloads, Desktop, and personal reports may contain private material; do not commit raw contents.
+- Adjacent repos may inform adapter design but are not runtime dependencies.
+- Cloud-git parity remains blocked until terminal `git ls-remote` or equivalent succeeds.
+
+## Acceptance Commands
+
+```bash
+python3 scripts/pre_work_check.py --remote-timeout 8 --command-timeout 45
+python3 -m pytest -q tests/test_runtime_import_boundaries.py tests/test_project_fragment_governance.py tests/test_preflight_fragment_scan.py tests/test_remote_repo_visibility_check.py tests/test_pre_work_check.py
+```
+
+```bash
+git status --short --branch
+git remote -v
+```

docs/superpowers/plans/2026-07-03-local-codex-plugin-wrapper.md

@@ -0,0 +1,42 @@
+# Local Codex Plugin Wrapper Implementation Plan
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+**Goal:** Add a minimal local Codex plugin wrapper around the existing Jyotish repo so Codex can install it as a plugin using the repo's current skills and MCP server.
+**Architecture:** Keep the repo as source of truth. Add only a `.codex-plugin/plugin.json` manifest that points at existing `skills/` and the existing root `mcp_server.py`. Lock it with one static test and document local install/test steps.
+**Tech Stack:** JSON manifest, existing Python MCP server, pytest static checks, Codex local plugin install flow.
+## Global Constraints
+- Reuse existing `SKILL.md`, `skills/`, and `mcp_server.py`; no duplicate runtime chain.
+- Keep plugin scope local-only; no marketplace publishing work.
+- Smallest diff wins: one manifest, one test, one short install doc update.
+
+### Task 1: Add plugin manifest coverage
+**Files:**
+- Modify: `tests/test_runtime_import_boundaries.py` or create focused plugin manifest test if cleaner
+- Test: `tests/test_codex_plugin_wrapper.py`
+**Interfaces:**
+- Consumes: `.codex-plugin/plugin.json`
+- Produces: static validation that plugin manifest exists and points at current repo assets
+- [ ] **Step 1: Write failing static test**
+- [ ] **Step 2: Run test to confirm failure**
+- [ ] **Step 3: Add minimal manifest or adjust expectations**
+- [ ] **Step 4: Re-run targeted test**
+
+### Task 2: Add minimal local plugin manifest
+**Files:**
+- Create: `.codex-plugin/plugin.json`
+**Interfaces:**
+- Consumes: existing `skills/`, root `mcp_server.py`
+- Produces: installable local plugin metadata
+- [ ] **Step 1: Use plugin spec sample to choose minimal accepted fields**
+- [ ] **Step 2: Point `skills` at existing `./skills/`**
+- [ ] **Step 3: Inline `mcpServers` config for `mcp_server.py`**
+- [ ] **Step 4: Validate manifest with plugin validator**
+
+### Task 3: Document local install/test flow
+**Files:**
+- Modify: `README.md`
+**Interfaces:**
+- Consumes: local plugin install command shape
+- Produces: copy-paste local install, reinstall, and test commands
+- [ ] **Step 1: Add minimal plugin install section**
+- [ ] **Step 2: Include reinstall/new-thread note**
+- [ ] **Step 3: Run targeted doc/static checks**

docs/superpowers/plans/2026-07-03-open-source-p0-file-execution-plan.md

@@ -0,0 +1,273 @@
+# Open Source P0 File Execution Plan
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+**Goal:** Finish the three P0 open-source integration fronts with the smallest real diff: `panchanga_api` sidecar integration, VedAstro official-default closure, and PyJHora black-box evidence consumption.
+**Architecture:** Reuse the existing unified planner, API server, MCP strict workflow, local `muhurta/prashna/remedies` modules, and existing VedAstro/PyJHora audit scripts. Do not add a parallel runtime chain. Extend existing payloads so web, MCP, and skill all read the same contract.
+**Tech Stack:** Python 3.11 stdlib, existing `scripts/` modules, existing `jyotish-app` frontend, pytest, existing repo docs.
+
+## Global Constraints
+- Reuse existing repo modules; no new subsystem.
+- Keep authority order: VedAstro official snapshot first, local supplemental modules second, local fallback last.
+- `PyJHora` remains black-box evidence only; do not import/copy AGPL code.
+- `panchanga_api` ideas may shape sidecar outputs, but local computation stays in `scripts/muhurta.py`, `scripts/prashna.py`, `scripts/remedies.py`.
+- Keep diffs tight: prefer helper functions inside current files over new files.
+- Every task ends with targeted tests, not hand-waving.
+
+## File Map
+
+### P0-A: `panchanga_api`-style sidecar integration
+
+| File | Role |
+|---|---|
+| `scripts/unified_consultation_orchestrator.py` | Decide when workflow should run `prashna`, `muhurta/panchanga`, and audited remedies sidecars. |
+| `scripts/jyotish_api_server.py` | Build/attach `prashna`, `muhurta_panchanga`, and `audited_remedies` packets in one workflow response. |
+| `scripts/muhurta.py` | Existing local Panchanga/Muhurta engine. Expose one compact helper fit for API/strict workflow payloads. |
+| `scripts/prashna.py` | Existing time-question engine. Reuse, do not rebuild. |
+| `scripts/remedies.py` | Existing remedies engine; only fed audited gate outputs. |
+| `mcp_server.py` | Surface same sidecars in strict workflow output. |
+| `jyotish-app/index.html` | Existing three-entry UI shell. Only minor control copy/visibility changes if needed. |
+| `jyotish-app/main.js` | Send timing-sidecar inputs and render sidecar outputs. |
+| `jyotish-app/renderers.js` | Reuse existing Panchanga rendering slot instead of new UI surface. |
+| `tests/test_unified_consultation_orchestrator.py` | Planner contract tests. |
+| `tests/test_api_server_security.py` | Workflow contract tests. |
+| `tests/test_muhurta.py` | Compact Muhurta helper tests. |
+| `tests/test_frontend_productization.py` | Frontend contract/render tests. |
+
+### P0-B: VedAstro official-default closure
+
+| File | Role |
+|---|---|
+| `scripts/vedastro_service_adapter.py` | Single official network boundary. Cache/queue/free-tier behavior lives here first. |
+| `scripts/vedastro_priority.py` | Shared official-first source-priority contract. |
+| `scripts/diagnose_vedastro_mode.py` | Runtime diagnosis for `official_extended` vs fallback, free-tier eligibility, queue/cache state. |
+| `scripts/jyotish_api_server.py` | Attach official summary/runtime truth to chart/full-reading/thematic/workflow responses. |
+| `scripts/unified_consultation_orchestrator.py` | Planner-visible official-step intent only; no extra engine. |
+| `mcp_server.py` | Surface same runtime truth and official execution layer summary. |
+| `jyotish-app/api-bridge.js` | Preserve official/runtime truth fields from API. |
+| `jyotish-app/main.js` | Render compact source-priority/runtime-truth block. |
+| `jyotish-app/professional-reading.js` | Show official/partial/fallback boundary in final reading. |
+| `jyotish-app/ai-chat.js` | Carry official evidence snapshot/runtime truth into follow-up payload. |
+| `tests/test_vedastro_runtime_mode_diagnostics.py` | Diagnose contract. |
+| `tests/test_vedastro_official_full_snapshot.py` | Snapshot contract. |
+| `tests/test_vedastro_service_adapter_executor.py` | Adapter execution/caching behavior. |
+| `tests/test_api_server_security.py` | Response contract propagation. |
+| `tests/test_frontend_productization.py` | Frontend visibility contract. |
+| `tests/test_vedastro_official_mcp_bridge.py` | Official bridge smoke. |
+
+### P0-C: PyJHora black-box evidence consumption
+
+| File | Role |
+|---|---|
+| `scripts/generate_pyjhora_oracle_artifact_manifest.py` | Canonical artifact manifest generator. |
+| `scripts/oracle_benchmark_inventory.py` | Make PyJHora artifact counts/queryable fronts visible. |
+| `scripts/external_oracle_sanity_closure.py` | Summarize PyJHora evidence availability into closure report. |
+| `scripts/historical_event_backtest.py` | Attach matching external evidence refs into backtest output. |
+| `scripts/oracle_closure_master_dashboard.py` | Lift PyJHora evidence readiness into one master board. |
+| `README.md` | State black-box boundary and what counts as closed vs not closed. |
+| `tests/test_pyjhora_oracle_artifact_manifest.py` | Manifest shape tests. |
+| `tests/test_oracle_benchmark_inventory.py` | Inventory tests. |
+| `tests/test_external_oracle_sanity_closure.py` | Closure summary tests. |
+| `tests/test_historical_event_backtest.py` | Backtest evidence-link tests. |
+| `tests/test_oracle_closure_master_dashboard.py` | Master dashboard tests. |
+
+## Task 1: Add `muhurta_panchanga` sidecar to unified workflow
+**Files:**
+- Modify: `scripts/muhurta.py`
+- Modify: `scripts/unified_consultation_orchestrator.py`
+- Modify: `scripts/jyotish_api_server.py`
+- Test: `tests/test_muhurta.py`
+- Test: `tests/test_unified_consultation_orchestrator.py`
+- Test: `tests/test_api_server_security.py`
+
+**Interfaces:**
+- Consumes: existing birth/location/time payload, optional `reference_date`, optional user question/topic.
+- Produces: `muhurta_panchanga: {status, source, panchanga, muhurta_windows, remedy_timing, blocked_reason?}` in workflow/module payload.
+
+- [ ] **Step 1: Write failing helper test in `tests/test_muhurta.py`**
+  - Target a new compact helper in `scripts/muhurta.py`, e.g. `build_muhurta_sidecar(...)`.
+- [ ] **Step 2: Run targeted test to verify failure**
+  - Run: `python3 -m pytest tests/test_muhurta.py -q`
+- [ ] **Step 3: Write failing planner/API tests**
+  - `tests/test_unified_consultation_orchestrator.py`: planner adds `run_muhurta_panchanga` for timing/remedy/prashna routes.
+  - `tests/test_api_server_security.py`: workflow response includes `muhurta_panchanga`.
+- [ ] **Step 4: Run targeted planner/API tests**
+- [ ] **Step 5: Implement minimal helper in `scripts/muhurta.py`**
+  - Reuse current Panchanga/Muhurta math.
+  - Return compact summary only; no giant raw blob.
+- [ ] **Step 6: Thread helper into `scripts/jyotish_api_server.py`**
+  - Add one private helper, e.g. `_compute_muhurta_panchanga(...)`.
+  - Attach result to consultation workflow and high-rigor/full-reading payloads where timing/remedies are relevant.
+- [ ] **Step 7: Update planner in `scripts/unified_consultation_orchestrator.py`**
+  - Add `run_muhurta_panchanga` only when route needs timing/remedy support.
+- [ ] **Step 8: Re-run targeted tests**
+
+## Task 2: Surface timing sidecar in MCP and frontend
+**Files:**
+- Modify: `mcp_server.py`
+- Modify: `jyotish-app/main.js`
+- Modify: `jyotish-app/renderers.js`
+- Modify: `jyotish-app/index.html` only if an existing slot/label is missing
+- Test: `tests/test_frontend_productization.py`
+
+**Interfaces:**
+- Consumes: workflow payload with `muhurta_panchanga`, `prashna`, `audited_remedies`.
+- Produces: visible timing/remedy panel in frontend + strict workflow payload exposure in MCP.
+
+- [ ] **Step 1: Write failing frontend/MCP contract test**
+  - Assert payload/rendering can see `muhurta_panchanga`.
+- [ ] **Step 2: Run targeted tests to verify failure**
+- [ ] **Step 3: Thread `muhurta_panchanga` through `mcp_server.py` strict output**
+- [ ] **Step 4: Reuse existing Panchanga render path in `jyotish-app/renderers.js`**
+  - No new tab unless current UI truly has nowhere to show it.
+- [ ] **Step 5: Update `jyotish-app/main.js` to render sidecar from unified workflow response**
+- [ ] **Step 6: Re-run targeted tests**
+
+## Task 3: Make VedAstro official path the real default contract
+**Files:**
+- Modify: `scripts/vedastro_service_adapter.py`
+- Modify: `scripts/vedastro_priority.py`
+- Modify: `scripts/diagnose_vedastro_mode.py`
+- Modify: `scripts/jyotish_api_server.py`
+- Test: `tests/test_vedastro_runtime_mode_diagnostics.py`
+- Test: `tests/test_vedastro_service_adapter_executor.py`
+- Test: `tests/test_vedastro_official_full_snapshot.py`
+- Test: `tests/test_api_server_security.py`
+
+**Interfaces:**
+- Consumes: same birth payload/reference date/theme, existing env/free-tier settings, adapter cache/queue config.
+- Produces: one normalized block:
+  - `runtime_truth`
+  - `official_execution_layers`
+  - `source_priority`
+  - `free_tier_strategy`
+
+- [ ] **Step 1: Write/extend failing diagnostics tests**
+  - Missing premium key should not masquerade as universal blocker.
+  - Free-tier cache/queue possibility should be explicit.
+- [ ] **Step 2: Run diagnostics tests to verify failure**
+- [ ] **Step 3: Write/extend failing adapter/API tests**
+  - Repeated same request should show cache-hit semantics.
+  - Official snapshot status should flow as `ok/partial/blocked`, not disappear.
+- [ ] **Step 4: Run targeted adapter/API tests**
+- [ ] **Step 5: Tighten `scripts/vedastro_service_adapter.py`**
+  - Reuse existing cache + queue path.
+  - Expose explicit metadata, not hidden internal state.
+- [ ] **Step 6: Tighten `scripts/vedastro_priority.py`**
+  - Keep one source-priority truth used by API/MCP/frontend.
+- [ ] **Step 7: Thread normalized blocks through `scripts/jyotish_api_server.py`**
+  - `/api/chart`
+  - `/api/full-reading`
+  - `/api/thematic_report`
+  - `/api/consultation_workflow`
+- [ ] **Step 8: Re-run targeted tests**
+
+## Task 4: Show VedAstro official/fallback truth in MCP + frontend
+**Files:**
+- Modify: `mcp_server.py`
+- Modify: `jyotish-app/api-bridge.js`
+- Modify: `jyotish-app/main.js`
+- Modify: `jyotish-app/professional-reading.js`
+- Modify: `jyotish-app/ai-chat.js`
+- Test: `tests/test_frontend_productization.py`
+- Test: `tests/test_vedastro_official_mcp_bridge.py`
+
+**Interfaces:**
+- Consumes: API payload with `runtime_truth`, `official_execution_layers`, `source_priority`.
+- Produces: user-visible compact truth block and AI follow-up payload carrying same boundary.
+
+- [ ] **Step 1: Write failing frontend contract tests**
+  - Assert frontend preserves and renders runtime-truth/source-priority data.
+- [ ] **Step 2: Run targeted tests to verify failure**
+- [ ] **Step 3: Thread fields via `jyotish-app/api-bridge.js`**
+- [ ] **Step 4: Render concise truth block in `jyotish-app/main.js` / `professional-reading.js`**
+  - Show direct facts: official `ok/partial/blocked`, cache hit, queue used, fallback used or not.
+- [ ] **Step 5: Pass same block into `jyotish-app/ai-chat.js` follow-up payload**
+- [ ] **Step 6: Surface same summary in `mcp_server.py` strict workflow output**
+- [ ] **Step 7: Re-run targeted tests**
+
+## Task 5: Normalize PyJHora artifact manifest for downstream consumers
+**Files:**
+- Modify: `scripts/generate_pyjhora_oracle_artifact_manifest.py`
+- Modify: `scripts/oracle_benchmark_inventory.py`
+- Modify: `scripts/external_oracle_sanity_closure.py`
+- Test: `tests/test_pyjhora_oracle_artifact_manifest.py`
+- Test: `tests/test_oracle_benchmark_inventory.py`
+- Test: `tests/test_external_oracle_sanity_closure.py`
+
+**Interfaces:**
+- Consumes: `references/oracle/artifacts/pyjhora_*` + `pending_packets/*pyjhora*.json`.
+- Produces: consistent per-front summary (`dasha`, `shadbala`, `tajika_sahams`) for audit scripts.
+
+- [ ] **Step 1: Write failing manifest/inventory tests**
+  - Need front-wise counts + file refs + boundary text.
+- [ ] **Step 2: Run targeted tests to verify failure**
+- [ ] **Step 3: Extend `generate_pyjhora_oracle_artifact_manifest.py` minimally**
+  - Add any missing fields needed by inventory/closure consumers.
+- [ ] **Step 4: Update `oracle_benchmark_inventory.py` to consume manifest, not ad hoc file scanning**
+- [ ] **Step 5: Update `external_oracle_sanity_closure.py` to report PyJHora evidence availability explicitly**
+- [ ] **Step 6: Re-run targeted tests**
+
+## Task 6: Feed PyJHora evidence into backtest + master dashboard
+**Files:**
+- Modify: `scripts/historical_event_backtest.py`
+- Modify: `scripts/oracle_closure_master_dashboard.py`
+- Modify: `README.md`
+- Test: `tests/test_historical_event_backtest.py`
+- Test: `tests/test_oracle_closure_master_dashboard.py`
+
+**Interfaces:**
+- Consumes: normalized PyJHora manifest/inventory summary.
+- Produces:
+  - backtest result includes matching `external_evidence_refs`
+  - master dashboard shows PyJHora evidence readiness
+  - README truth text stays honest
+
+- [ ] **Step 1: Write failing backtest/dashboard tests**
+- [ ] **Step 2: Run targeted tests to verify failure**
+- [ ] **Step 3: Update `historical_event_backtest.py`**
+  - Link relevant artifact refs by front/domain; do not overclaim validation.
+- [ ] **Step 4: Update `oracle_closure_master_dashboard.py`**
+  - Lift manifest summary into one closure board.
+- [ ] **Step 5: Refresh README wording**
+  - Keep “black-box evidence only” explicit.
+- [ ] **Step 6: Re-run targeted tests**
+
+## Task 7: Final regression pack
+**Files:**
+- No new files unless a missing narrow test is unavoidable
+
+**Run:**
+- [ ] `python3 -m pytest tests/test_muhurta.py tests/test_unified_consultation_orchestrator.py tests/test_api_server_security.py -q`
+- [ ] `python3 -m pytest tests/test_vedastro_runtime_mode_diagnostics.py tests/test_vedastro_service_adapter_executor.py tests/test_vedastro_official_full_snapshot.py tests/test_vedastro_official_mcp_bridge.py tests/test_frontend_productization.py -q`
+- [ ] `python3 -m pytest tests/test_pyjhora_oracle_artifact_manifest.py tests/test_oracle_benchmark_inventory.py tests/test_external_oracle_sanity_closure.py tests/test_historical_event_backtest.py tests/test_oracle_closure_master_dashboard.py -q`
+- [ ] Run one manual local workflow smoke:
+  - direct chart
+  - prashna/time question
+  - one repeated request to verify cache hit metadata
+- [ ] Record remaining blocked items explicitly, especially:
+  - official live endpoint availability
+  - free-tier queue delay
+  - missing PyJHora evidence fronts
+
+## Fastest Execution Order
+
+1. Task 3
+2. Task 4
+3. Task 1
+4. Task 2
+5. Task 5
+6. Task 6
+7. Task 7
+
+Reason:
+
+- VedAstro default truth is the highest-value user-facing fix.
+- `muhurta/panchanga` sidecar reuses local code and is cheap once workflow contract is stable.
+- PyJHora evidence work is mainly audit/dashboards, not user runtime critical path.
+
+## Stop Conditions
+
+Stop and mark `blocked` if any of these happen:
+
+- VedAstro official endpoint can only return `blocked` in the current environment and no cache sample exists.
+- A proposed PyJHora consumption change would require importing AGPL code instead of consuming stored artifacts.
+- `panchanga_api`-style sidecar would require a second planner/entry system instead of extending current unified workflow.

docs/superpowers/plans/2026-07-03-prashna-remedies-unified-entry.md

@@ -0,0 +1,84 @@
+# Prashna Remedies Unified Entry Implementation Plan
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+**Goal:** Reuse existing `prashna` and `remedies` modules inside the unified consultation workflow so web/API/skill can expose three parallel entry modes: direct chart, rectification, and time-question (Prashna).
+**Architecture:** Keep the current `execute_consultation_workflow()` and `UnifiedConsultationOrchestrator` as the single runtime planner. Add one new `entry_mode` (`prashna`) and one gate-fed remedies path that consumes `strict_audit_gate`/guided-topic conclusion packets instead of raw free-form frontend fields. Frontend only switches entry payload shape and display mode; backend remains the source of truth.
+**Tech Stack:** Python stdlib, existing repo modules (`prashna.py`, `remedies.py`, `unified_consultation_orchestrator.py`, `jyotish_api_server.py`), existing web app JS/HTML, pytest.
+
+## Global Constraints
+- Reuse existing modules; no new subsystem.
+- Keep source priority: VedAstro official snapshot first, local supplemental second, fallback last.
+- Remedies must not accept arbitrary raw advice inputs from frontend once unified path exists.
+- Frontend must expose exactly three peer entry modes: `direct_chart`, `rectification`, `prashna`.
+- Keep diffs small and local to existing orchestrator/API/frontend files.
+
+### Task 1: Add `prashna` to unified runtime planner
+**Files:**
+- Modify: `scripts/unified_consultation_orchestrator.py`
+- Test: `tests/test_unified_consultation_orchestrator.py`
+**Interfaces:**
+- Consumes: `entry_mode: str`, `question: str | None`, existing route/theme normalization.
+- Produces: runtime planner contract supporting `entry_mode == "prashna"` and route/theme selection for Prashna.
+- [ ] **Step 1: Write failing tests**
+- [ ] **Step 2: Run planner tests to verify failure**
+- [ ] **Step 3: Implement minimal planner support for `prashna`**
+- [ ] **Step 4: Re-run planner tests**
+
+### Task 2: Route consultation workflow through Prashna entry mode
+**Files:**
+- Modify: `scripts/jyotish_api_server.py`
+- Test: `tests/test_api_server_security.py`
+**Interfaces:**
+- Consumes: `POST /api/consultation_workflow` payload w/ `entry_mode = "prashna"`, `question`, `question_text`, optional `horary_number`, existing birth/location/time fields.
+- Produces: consultation workflow result containing `entry_mode`, `runtime_planner`, `prashna` result block, and shared provenance fields.
+- [ ] **Step 1: Write failing API workflow tests for `prashna` entry**
+- [ ] **Step 2: Run targeted tests to verify failure**
+- [ ] **Step 3: Implement minimal `prashna` entry path by reusing `_compute_prashna()`**
+- [ ] **Step 4: Re-run targeted tests**
+
+### Task 3: Make unified remedies consume strict gate output only
+**Files:**
+- Modify: `scripts/jyotish_api_server.py`
+- Test: `tests/test_api_server_security.py`
+**Interfaces:**
+- Consumes: guided-topic / strict workflow conclusion packet containing `strict_audit_gate`, `topic`, `supporting_planets`, `active_dasha_lord`, and strength inputs already computed in workflow.
+- Produces: remedies response derived from audited conclusion context, not arbitrary frontend-entered `shadbala`/`doshas` blobs in unified mode.
+- [ ] **Step 1: Write failing test showing unified remedies path rejects missing gate context**
+- [ ] **Step 2: Run targeted test to verify failure**
+- [ ] **Step 3: Implement minimal audited remedies adapter around existing `recommend_remedies()`**
+- [ ] **Step 4: Re-run targeted tests**
+
+### Task 4: Expose three entry modes in frontend
+**Files:**
+- Modify: `jyotish-app/index.html`
+- Modify: `jyotish-app/main.js`
+- Modify: `jyotish-app/api-bridge.js`
+- Test: `tests/test_frontend_productization.py`
+**Interfaces:**
+- Consumes: user choice among `direct_chart`, `rectification`, `prashna`.
+- Produces: frontend payloads to `/api/consultation_workflow`, plus Prashna-specific question fields when `prashna` selected.
+- [ ] **Step 1: Write failing frontend contract test for 3 entry modes**
+- [ ] **Step 2: Run targeted frontend test to verify failure**
+- [ ] **Step 3: Implement minimal UI/payload switch reuse of existing sections**
+- [ ] **Step 4: Re-run targeted frontend tests**
+
+### Task 5: Wire remedies display to unified audited output
+**Files:**
+- Modify: `jyotish-app/main.js`
+- Test: `tests/test_frontend_productization.py`
+**Interfaces:**
+- Consumes: unified workflow response including audited remedies packet.
+- Produces: remedies section rendered from audited packet, not standalone free-form request flow.
+- [ ] **Step 1: Write failing render test**
+- [ ] **Step 2: Run targeted test to verify failure**
+- [ ] **Step 3: Implement minimal audited remedies rendering**
+- [ ] **Step 4: Re-run targeted tests**
+
+### Task 6: End-to-end verification
+**Files:**
+- Modify if needed: `tests/test_api_server_security.py`, `tests/test_frontend_productization.py`
+**Interfaces:**
+- Produces: passing targeted regression coverage for planner, API workflow, remedies gate, and frontend entry modes.
+- [ ] **Step 1: Run targeted backend tests**
+- [ ] **Step 2: Run targeted frontend tests**
+- [ ] **Step 3: Run one live local consultation/prashna smoke probe**
+- [ ] **Step 4: Record any remaining boundary explicitly**

docs/superpowers/plans/2026-07-03-vedastro-runtime-truth-contract.md

@@ -0,0 +1,105 @@
+# VedAstro Runtime Truth Contract Implementation Plan
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+**Goal:** Expose machine-checkable runtime truth for VedAstro official execution and interpretation-source invocation so users and APIs can see what actually ran.
+**Architecture:** Extend the existing unified consultation/high-rigor contract instead of building a new pipeline. Reuse `vedastro_service_adapter`, `vedastro_priority`, existing interpretation source inventory/strict workflow markers, and API response contracts.
+**Tech Stack:** Python 3.11, existing `scripts/` API server/orchestrator modules, pytest.
+## Global Constraints
+- Reuse existing repo modules; no new parallel runtime chain.
+- Keep VedAstro official as preferred evidence, but do not overclaim full-catalog execution.
+- Add tests first for new response contract fields.
+- Preserve current honesty boundaries and blocked states.
+
+### Task 1: Add failing API contract tests for runtime truth fields
+**Files:**
+- Modify: `tests/test_vedastro_external_technique_evidence.py`
+- Modify: `tests/test_api_server_security.py`
+**Interfaces:**
+- Consumes: `JyotishAPIHandler._high_rigor_vedastro_official_summary`, `execute_consultation_workflow`
+- Produces: expected fields `runtime_truth`, `official_execution_layers`, `interpretation_source_runtime_coverage`
+- [ ] Step 1: Write failing tests for consultation/high-rigor responses.
+- [ ] Step 2: Run targeted pytest to confirm failure.
+- [ ] Step 3: Keep assertions narrow: presence, semantics, blocked/partial handling.
+- [ ] Step 4: Re-run targeted pytest.
+
+### Task 2: Implement VedAstro runtime truth summary
+**Files:**
+- Modify: `scripts/jyotish_api_server.py`
+- Check: `scripts/vedastro_priority.py`
+**Interfaces:**
+- Consumes: chart modules, `vedastro_official_full_snapshot`, `source_priority`, evidence snapshot
+- Produces: normalized runtime truth block with official mode, readiness, executed layers, blocked reasons, catalog-vs-runtime boundary
+- [ ] Step 1: Add helper(s) building normalized `runtime_truth` summary.
+- [ ] Step 2: Thread summary into `_high_rigor_vedastro_official_summary`.
+- [ ] Step 3: Thread same summary into consultation workflow top-level payload.
+- [ ] Step 4: Run targeted tests.
+
+### Task 3: Implement interpretation-source runtime coverage summary
+**Files:**
+- Modify: `scripts/jyotish_api_server.py`
+- Check: `mcp_server.py`, `scripts/interpretation_source_inventory_gate.py`
+**Interfaces:**
+- Consumes: strict workflow secondary-context markers, existing source-pack status, current audit boundaries
+- Produces: API-visible summary of proven runtime visibility vs unproven source assets
+- [ ] Step 1: Add helper returning compact coverage summary.
+- [ ] Step 2: Attach to consultation workflow and thematic/high-rigor payloads.
+- [ ] Step 3: Ensure summary distinguishes `proven_runtime_markers` from `not_fully_closed`.
+- [ ] Step 4: Run targeted tests.
+
+### Task 4: Add reusable audit script for machine-checkable coverage
+**Files:**
+- Create: `scripts/interpretation_source_runtime_coverage.py`
+- Add Test: `tests/test_interpretation_source_runtime_coverage.py`
+**Interfaces:**
+- Consumes: existing inventory gate data + strict workflow markers from runtime packs
+- Produces: JSON/markdown report with extraction/source-pack/runtime visibility gaps
+- [ ] Step 1: Write failing test for minimal report shape.
+- [ ] Step 2: Implement minimal script reusing existing modules.
+- [ ] Step 3: Run targeted tests.
+
+### Task 5: Verify end-to-end targeted regression
+**Files:**
+- None or docs if output contract docs need refresh
+**Interfaces:**
+- Consumes: new contract fields/tests/scripts
+- Produces: fresh verification evidence
+- [ ] Step 1: Run targeted pytest set covering API contract + new coverage tool.
+- [ ] Step 2: Run `python3 scripts/diagnose_vedastro_mode.py`.
+- [ ] Step 3: Run new coverage script once in JSON mode.
+- [ ] Step 4: Summarize actual status, not aspirational status.
+
+
+### Task 6: Surface runtime truth in MCP and frontend result payloads
+**Files:**
+- Modify: `mcp_server.py`
+- Modify: `jyotish-app/skill-map.js`
+- Test: `tests/test_frontend_productization.py` and/or existing MCP/API contract tests
+**Interfaces:**
+- Consumes: `consultation_workflow` response contract
+- Produces: visible runtime truth / source coverage status in MCP strict workflow output and frontend result panels
+- [ ] Step 1: Add failing tests for visible payload fields.
+- [ ] Step 2: Thread fields through MCP strict workflow response.
+- [ ] Step 3: Render compact runtime truth/source coverage block in frontend result page.
+- [ ] Step 4: Run targeted tests.
+
+### Task 7: Harden official-extended runtime preflight
+**Files:**
+- Modify: `scripts/diagnose_vedastro_mode.py`
+- Modify: `scripts/vedastro_service_adapter.py` and/or `.env.official.example` only if needed
+- Test: existing VedAstro diagnostics/adapter tests
+**Interfaces:**
+- Consumes: current env + adapter time budget
+- Produces: sharper preflight diagnosis for why official mode is not ready; no silent fast fallback confusion
+- [ ] Step 1: Add failing diagnostics tests if missing.
+- [ ] Step 2: Expose concrete readiness blockers in output contract.
+- [ ] Step 3: Re-run diagnostics tests.
+
+### Task 8: Split slow verification into smaller quality-gate profile(s)
+**Files:**
+- Modify: `scripts/run_quality_gate.py`
+- Modify: relevant tests/docs if profile list changes
+**Interfaces:**
+- Consumes: current gate profiles and long-running test groups
+- Produces: smaller verification profile(s) for runtime-truth/strict-workflow/official contracts
+- [ ] Step 1: Add failing tests or assertions for new profile names/commands.
+- [ ] Step 2: Implement profile split and command grouping.
+- [ ] Step 3: Run targeted gate/profile tests.

docs/superpowers/plans/2026-07-04-bv-raman-report-book-structure.md

@@ -0,0 +1,68 @@
+# B.V. Raman Long Report Book Structure Implementation Plan
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+**Goal:** Convert the existing single-file comprehensive chart study into a reusable long-report book structure that can serve Markdown-first authoring and later PDF export.
+**Architecture:** Keep the existing [`/Users/wuyongnaren/Documents/印度占星/docs/reports/bv_raman_style_comprehensive_chart_research_REDACTED_DATE_REDACTED_TIME_v1.md`](/Users/wuyongnaren/Documents/印度占星/docs/reports/bv_raman_style_comprehensive_chart_research_REDACTED_DATE_REDACTED_TIME_v1.md) as the source draft, then add a new `chart_research_REDACTED_DATE_REDACTED_TIME/` directory with `book.md` as the main concatenation entry, chapter files for thematic expansion, appendix files for raw evidence, and a small metadata file for later export tooling. No new PDF pipeline is added now because none is already wired in this repo.
+**Tech Stack:** Markdown, YAML metadata, existing repo docs conventions, local JSON artifacts under `.tmp/chart_study`.
+## Global Constraints
+- Reuse existing report content; do not rewrite the full report from scratch.
+- Keep Markdown as the source of truth; PDF remains an export artifact, not a second authoring format.
+- Do not add new dependencies or a speculative PDF toolchain.
+- Preserve honesty boundaries about VedAstro/PyJHora/jyotishganit closure.
+- Prefer links to existing JSON artifacts over copying large raw blobs into prose chapters.
+- Before editing chapters, read `docs/reports/chart_research_REDACTED_DATE_REDACTED_TIME/README.md` and `docs/reports/chart_research_REDACTED_DATE_REDACTED_TIME/appendices/H_error_ledger_and_preflight.md`.
+
+### Task 1: Add the long-report container
+**Files:**
+- Create: `/Users/wuyongnaren/Documents/印度占星/docs/reports/chart_research_REDACTED_DATE_REDACTED_TIME/README.md`
+- Create: `/Users/wuyongnaren/Documents/印度占星/docs/reports/chart_research_REDACTED_DATE_REDACTED_TIME/book.md`
+- Create: `/Users/wuyongnaren/Documents/印度占星/docs/reports/chart_research_REDACTED_DATE_REDACTED_TIME/metadata.yaml`
+**Interfaces:**
+- Consumes: existing v1 report and `.tmp/chart_study/*.json`
+- Produces: one stable report root that later tools or humans can extend
+- [ ] **Step 1: Create report root directory structure**
+- [ ] **Step 2: Add `README.md` explaining source-of-truth and export intent**
+- [ ] **Step 3: Add `metadata.yaml` for title/author/date/export hints**
+- [ ] **Step 4: Add `book.md` listing chapters and appendices in final reading order**
+
+### Task 2: Add chapter skeletons mapped to the requested methodology
+**Files:**
+- Create: `/Users/wuyongnaren/Documents/印度占星/docs/reports/chart_research_REDACTED_DATE_REDACTED_TIME/chapters/*.md`
+**Interfaces:**
+- Consumes: user-requested B.V. Raman / Parāśara / Jaimini scope
+- Produces: one file per chapter so later expansion stays bounded
+- [ ] **Step 1: Create 00–21 chapter files**
+- [ ] **Step 2: Put a short contract at top of each chapter saying what belongs there**
+- [ ] **Step 3: Pre-fill only the first few chapters with live links to existing content/data**
+- [ ] **Step 4: Leave later chapters as clean skeletons instead of fake filled content**
+
+### Task 3: Add appendix and data references
+**Files:**
+- Create: `/Users/wuyongnaren/Documents/印度占星/docs/reports/chart_research_REDACTED_DATE_REDACTED_TIME/appendices/*.md`
+- Populate/Reference: `/Users/wuyongnaren/Documents/印度占星/docs/reports/chart_research_REDACTED_DATE_REDACTED_TIME/data/`
+**Interfaces:**
+- Consumes: `.tmp/chart_study/*.json`
+- Produces: report appendix map and raw evidence pointers
+- [ ] **Step 1: Create appendix stubs for raw tables, dasha boundaries, varga positions, parity, audit, glossary**
+- [ ] **Step 2: Reference current `.tmp/chart_study` artifacts instead of duplicating them**
+- [ ] **Step 3: Explain which appendices are ready vs blocked**
+
+### Task 4: Connect old draft into new main chain
+**Files:**
+- Modify/Create: `/Users/wuyongnaren/Documents/印度占星/docs/reports/chart_research_REDACTED_DATE_REDACTED_TIME/README.md`
+- Keep: `/Users/wuyongnaren/Documents/印度占星/docs/reports/bv_raman_style_comprehensive_chart_research_REDACTED_DATE_REDACTED_TIME_v1.md`
+**Interfaces:**
+- Consumes: existing v1 draft headings and current chapter structure
+- Produces: migration notes from monolith draft to book structure
+- [ ] **Step 1: Mark the old v1 report as the seed draft**
+- [ ] **Step 2: Map v1 sections to new chapter files**
+- [ ] **Step 3: Keep migration incremental instead of copying all prose immediately**
+
+### Task 5: Verify structure only
+**Files:**
+- Verify: report directory tree and links
+**Interfaces:**
+- Consumes: created Markdown files
+- Produces: a structure that humans can open immediately
+- [ ] **Step 1: List created files**
+- [ ] **Step 2: Open `book.md` and `README.md` to confirm links**
+- [ ] **Step 3: Avoid claiming PDF export exists until an actual exporter is wired and tested**

docs/vibe_coding_setup.md

@@ -0,0 +1,26 @@
+# Vibe Coding Setup
+
+Use Cline as the main AI coding surface for this repo. Use Aider for small low-cost code edits. Use Dyad only for fast front-end prototypes such as 星轨talk pages.
+
+## Cline MCP
+
+Generate config:
+
+```bash
+python3 scripts/print_cline_mcp_config.py
+```
+
+Install project-local config:
+
+```bash
+python3 scripts/print_cline_mcp_config.py --install-project
+```
+
+This writes `.cline/mcp.json` with the current checkout path. `.cline/` is local-only and ignored by git.
+
+## Recommended Split
+
+- Cline: main repo work, MCP tools, strict workflow checks.
+- Aider: precise low-cost edits with git diffs.
+- Dyad: quick UI prototypes, not the main Jyotish runtime.
+