Harden high-rigor Jyotish timing workflow

docs/research/full_reading_performance_and_vedastro_ingestion_strategy_2026_06_30.md

@@ -0,0 +1,285 @@
+# Full Reading Performance And VedAstro Ingestion Strategy (2026-06-30)
+
+## Scope
+
+This note records one strict round of:
+
+1. whole-repo workflow review,
+2. external-source grounding,
+3. real `full-reading` stage timing collection,
+4. API strategy changes based on measured bottlenecks.
+
+It is intended to prevent future work from drifting back into intuition-only performance decisions.
+
+## High-Level Conclusion
+
+The current project is **not bottlenecked by local Jyotish computation**.
+
+The dominant runtime cost for real user-facing `full-reading` is:
+
+1. `vedastro_official_snapshot`
+2. `vedastro_main_entry_overview`
+
+Therefore, the highest-value optimization order is:
+
+1. preserve the existing local-native calculation path,
+2. reuse existing `vedastro_service_adapter` request caching,
+3. add **API-level final chart response caching** for the normal `/api/chart` path,
+4. keep `high_rigor_workflow` explicitly marked as the lane that should move toward queue/async execution,
+5. do **not** spend engineering cycles micro-optimizing local Dasha/Varga/Yoga layers before fixing official-evidence ingestion cost.
+
+## Repo Facts Confirmed
+
+### Active closure lanes
+
+`docs/research/ACTIVE_FRONTS.md` keeps work constrained to four fronts:
+
+1. Relationship adjudicator closure
+2. Vimsopaka + functional-role closure
+3. Oracle closure batch
+4. VedAstro strict ingestion
+
+This means performance/productization work should be treated as support for the fourth lane, not as an unrelated new product surface.
+
+### Existing reusable building blocks
+
+The repo already contains the main pieces required for an official-first architecture:
+
+- `scripts/vedastro_service_adapter.py`
+- `scripts/vedastro_evidence_orchestrator.py`
+- `scripts/vedastro_priority.py`
+- `scripts/jyotish_engine.py`
+- `scripts/jyotish_api_server.py`
+- `mcp_server.py`
+
+The correct strategy is to **reuse and tighten** these boundaries, not to create a second orchestration stack.
+
+## External-Source Grounding
+
+### Python performance measurement
+
+The Python standard library documents `time.perf_counter()` as the high-resolution timer appropriate for measuring short durations and performance intervals.  
+Source: [Python `time` documentation](https://docs.python.org/3/library/time.html)
+
+The Python profiling documentation distinguishes deterministic profiling (`cProfile` / `profile`) from ad hoc guessing and supports evidence-first investigation of runtime cost.  
+Source: [Python profiling documentation](https://docs.python.org/3/library/profile.html)
+
+### Task-queue direction
+
+FastAPI documents `BackgroundTasks` for simple post-response work, but this pattern is not a substitute for durable heavy workflow execution when requests are long-running.  
+Source: [FastAPI BackgroundTasks](https://fastapi.tiangolo.com/tutorial/background-tasks/)
+
+RQ documents a Redis-backed background job queue suitable for Python jobs that should leave the request path.  
+Source: [RQ documentation](https://python-rq.org/docs/)
+
+### Interpretation for this project
+
+These sources support a two-layer discipline:
+
+1. first instrument real runtime stages with in-code timers,
+2. then move only the truly expensive request-path layers to cache or queue.
+
+For this repository, that means:
+
+- measure `full-reading` stages before architectural change,
+- keep local chart math synchronous,
+- protect heavy VedAstro official ingestion behind cache and later queue/async boundaries.
+
+## Real Timing Evidence
+
+### Sample used
+
+Real sample run:
+
+- birth: `REDACTED_DATE REDACTED_TIME`
+- location: `36.4467, 114.2`
+- tz: `UTC+8`
+- reference date: `2026-06-30`
+
+Command:
+
+```bash
+python3 scripts/jyotish_engine.py full-reading \
+  --year REDACTED_YEAR --month 4 --day 17 \
+  --hour 14 --minute 49 \
+  --lat 36.4467 --lon 114.2 --tz 8 \
+  --today 2026-06-30 \
+  --transit-date 2026-06-30 \
+  --profile-stages
+```
+
+### First measured run
+
+Observed summary:
+
+- total elapsed: `181.0154s`
+- modules: `57`
+- errors: `0`
+
+Stage timings:
+
+- `core_chart_and_setup`: `0.0036s`
+- `dasha_and_core_varga_stack`: `0.8380s`
+- `advanced_interpretation_and_timing_layers`: `0.4753s`
+- `dynamic_hooks`: `0.0001s`
+- `vedastro_official_snapshot`: `133.7938s`
+- `strict_contracts`: `3.5107s`
+- `vedastro_main_entry_overview`: `41.5806s`
+- `guided_topics`: `0.0003s`
+- `ai_prompt_pack`: `0.8122s`
+
+### Second measured run with existing caches warmed
+
+Same command, same birth payload, same reference date.
+
+Observed stage timings:
+
+- `core_chart_and_setup`: `0.0029s`
+- `dasha_and_core_varga_stack`: `0.9145s`
+- `advanced_interpretation_and_timing_layers`: `0.5279s`
+- `vedastro_official_snapshot`: `112.0435s`
+- `strict_contracts`: `2.9865s`
+- `vedastro_main_entry_overview`: `0.0735s`
+- `guided_topics`: `0.0003s`
+- `ai_prompt_pack`: `0.6211s`
+
+### What the second run proves
+
+The second run proves two different things:
+
+1. `vedastro_main_entry_overview` is already benefiting from existing lower-level caching.
+2. `vedastro_official_snapshot` remains overwhelmingly expensive even after a warm rerun.
+
+So the adapter cache is **useful but insufficient** at the user-visible workflow level.
+
+## Root-Cause Interpretation
+
+### What is not the bottleneck
+
+The following are not the dominant latency problem:
+
+- local Dasha
+- local Varga
+- Yoga / Ashtakavarga / Shadbala orchestration
+- strict workflow contract assembly
+- prompt pack generation
+
+All of these are materially small relative to official evidence ingestion.
+
+### What is the bottleneck
+
+The dominant cost is the official evidence layer itself, especially:
+
+- `run_official_full_snapshot_for_case(...)`
+- official full-snapshot section fanout and retry path
+
+The repo also shows a second pattern difference:
+
+- CLI `full-reading` attaches overview by directly calling `run_range_scan_for_case(...)`
+- API chart attaches overview through `orchestrate_vedastro_evidence(...)`, which already bundles official full snapshot and route-scoped scans
+
+This means there are still opportunities to reduce duplication by reusing higher-level official results more aggressively.
+
+## Strategy Decision
+
+### Decision A: Normal chart path gets API-level final result caching
+
+Why:
+
+- `/api/chart` is the normal synchronous user path.
+- It packages chart + official evidence + prompt pack together.
+- The user cares about final response latency, not just adapter request latency.
+
+Therefore a **final chart response cache** is justified at API level.
+
+### Decision B: High-rigor workflow is the queue/async candidate lane
+
+Why:
+
+- `high_rigor_workflow` composes chart + rectification + historical backtest + thematic report.
+- It is heavier than normal chart consumption by design.
+- This lane is the correct place to expose queue/async execution strategy in future work.
+
+### Decision C: Do not optimize local Jyotish math first
+
+Why:
+
+- measured evidence shows local-native layers are cheap relative to official ingestion.
+- optimizing them first would spend effort where the user does not feel the delay.
+
+## Implementation Landed In This Round
+
+### `scripts/jyotish_engine.py`
+
+Landed:
+
+- stage timing instrumentation for `full-reading`
+- `--profile-stages` CLI flag
+- summary output containing:
+  - `stage_timing_enabled`
+  - `stage_timings`
+  - `slowest_stages`
+
+This is now the baseline tool for future performance decisions.
+
+### `scripts/jyotish_api_server.py`
+
+Landed:
+
+- API chart final-response cache helpers:
+  - `_build_api_chart_cache_payload`
+  - `_api_chart_cache_key`
+  - `_load_api_chart_response_cache`
+  - `_store_api_chart_response_cache`
+- runtime cache metadata attached to cached responses:
+  - `scope`
+  - `cache_hit`
+  - `cache_key`
+  - `cache_created_at`
+  - `cache_expires_at`
+  - `cache_ttl_seconds`
+- `_compute_chart(...)` now checks API-level cache before recomputing
+- `_high_rigor_workflow_plan_only(...)` now exposes execution strategy:
+  - normal chart path uses sync chart response cache
+  - high-rigor lane is the queue recommendation target
+
+### Tests landed
+
+Added/updated tests in `tests/test_api_server_security.py` to verify:
+
+- API chart response cache contract exists and round-trips
+- cache key changes with VedAstro runtime state
+- high-rigor plan-only output explicitly surfaces chart-cache and queue strategy
+
+## What Is Still Not Closed
+
+1. The current official full snapshot still does not have an equivalent high-level final cache strong enough to collapse the `112s+` cost on rerun.
+2. `high_rigor_workflow` exposes queue recommendation metadata, but no durable job runner or polling endpoint is landed yet.
+3. CLI `full-reading` and API chart still do not fully unify around one deduplicated “official snapshot + overview reuse” path.
+
+## Recommended Next Implementation Order
+
+1. Add **official full snapshot result caching** at a higher semantic level than raw request caching.
+2. Make API chart reuse that official full snapshot cache before rebuilding the same evidence package.
+3. Introduce a minimal asynchronous lane for `high_rigor_workflow`:
+   - enqueue request
+   - return job id
+   - poll result
+   - keep synchronous mode for debug/local use
+4. Only after those are landed, decide whether deeper profiler work is still needed.
+
+## Honesty Boundary
+
+This document does **not** claim:
+
+- that the entire full-reading path is now fast,
+- that all VedAstro-heavy routes are production-grade for synchronous use,
+- that queue/async execution is already complete,
+- that local and official evidence are fully deduplicated.
+
+What it does claim is narrower and evidenced:
+
+- stage timing is now real and reproducible,
+- the main bottleneck has been identified with measured data,
+- API-level final chart response caching is now partially landed,
+- the repo now has a documented, evidence-backed strategy for the next optimization steps.

docs/research/local_drafts_2026_06_disposition.md

@@ -0,0 +1,115 @@
+# 2026-06 Local Drafts Disposition
+
+Date: 2026-07-01
+
+Purpose: freeze the governance boundary for `docs/research/local_drafts/2026-06` without deleting or moving the drafts. The draft directory is evidence and recovery memory, not runtime truth. Do not move or delete files in this pass.
+
+Source-of-truth rule:
+
+- Main repo truth stays in `SKILL.md`, `AGENTS.md`, `references/`, `scripts/`, `tests/`, and canonical `docs/research/*.md`.
+- `.workbuddy` is a historical distribution mirror and recovery reference only. It must not reverse-sync over this repo, and runtime code must not import from it.
+- A `promote` row means the draft should be converted into a canonical research note, benchmark artifact, test, or source change before it drives implementation.
+- A `reference-only` row means it can be cited as background after re-anchoring to current code and licenses.
+- An `archive` row means it should stay out of current implementation flow unless a future audit explicitly reopens it.
+
+## Disposition Table
+
+| Disposition | Draft | Reason |
+|---|---|---|
+| reference-only | antigravity_round31_api_completion_top50_2026_06_26.md | Older API exposure wishlist; re-check against current `jyotish_api_server.py` before reuse. |
+| promote | antigravity_round31_ayanamsa_ephemeris_timezone_risk_matrix_2026_06_26.md | Core accuracy boundary for ayanamsa, ephemeris, timezone and node-mode evidence. |
+| reference-only | antigravity_round31_cli_completion_top50_2026_06_26.md | Useful CLI wishlist, but many items are superseded by later tests and active plans. |
+| reference-only | antigravity_round31_cloud_sync_whitelist_final_draft_2026_06_26.md | Distribution-sync background only; current rule is no reverse contamination from `.workbuddy`. |
+| archive | antigravity_round31_codex_round32_top180_2026_06_26.md | Broad execution board superseded by later narrower closure plans. |
+| promote | antigravity_round31_copy_allowed_assets_top80_2026_06_26.md | License-safe reuse candidates need canonical whitelist linkage before code migration. |
+| promote | antigravity_round31_external_oracle_closure_top60_2026_06_26.md | External oracle closure remains a high-rigor blocker and should feed oracle queues. |
+| promote | antigravity_round31_extra_astronomical_edge_cases_polar_regions_2026_06_26.md | Polar and astronomical edge cases affect correctness and confidence boundaries. |
+| reference-only | antigravity_round31_extra_internationalization_i18n_readiness_2026_06_26.md | Product-localization idea; not a current strict accuracy front. |
+| reference-only | antigravity_round31_extra_offline_fallback_mode_2026_06_26.md | Frontend resilience idea; keep outside current engine-truth work. |
+| reference-only | antigravity_round31_extra_performance_profiling_memory_leaks_2026_06_26.md | Performance background; only promote after API payload profiling is reopened. |
+| archive | antigravity_round31_final_execution_board_2026_06_26.md | Round board superseded by current active fronts. |
+| reference-only | antigravity_round31_frontend_completion_top50_2026_06_26.md | UI exposure backlog, not current runtime truth. |
+| promote | antigravity_round31_jhora_pyjhora_capture_manual_review_2026_06_26.md | Human oracle capture standards belong with benchmark and operator docs. |
+| promote | antigravity_round31_license_quarantine_blacklist_top60_2026_06_26.md | License quarantine rules are project safety boundaries and should stay canonical. |
+| promote | antigravity_round31_local_accuracy_shortest_path_top50_2026_06_26.md | Local accuracy verification path supports regression confidence and user trust. |
+| reference-only | antigravity_round31_local_user_experience_top60_2026_06_26.md | UX backlog; not a main-chain source of truth. |
+| promote | antigravity_round31_single_source_of_truth_enforcement_2026_06_26.md | Single-source governance supports the current mirror-contamination fix. |
+| promote | antigravity_round31_true_missing_traditional_techniques_top30_2026_06_26.md | Traditional technique gap list should inform registry and roadmap truth. |
+| promote | antigravity_round31_whole_machine_fragment_reuse_fourth_pass_2026_06_26.md | Whole-machine reuse findings are high value, but must be re-anchored before integration. |
+| reference-only | antigravity_round32_api_direct_coding_top40_2026_06_26.md | Concrete API tasks, but must be reconciled with current endpoint map first. |
+| reference-only | antigravity_round32_cli_direct_coding_top40_2026_06_26.md | Concrete CLI tasks, but no longer authoritative without current test review. |
+| archive | antigravity_round32_codex_round33_top200_2026_06_26.md | Broad execution board superseded by current closure lanes. |
+| promote | antigravity_round32_copy_allowed_assets_top100_2026_06_26.md | License-safe assets list should merge with canonical reuse whitelist. |
+| reference-only | antigravity_round32_extra_accuracy_verification_blocks_2026_06_26.md | Trust-center idea; promote only if product verification UI is reopened. |
+| reference-only | antigravity_round32_extra_i18n_translation_2026_06_26.md | Localization backlog, not current strict workflow. |
+| reference-only | antigravity_round32_extra_offline_fallback_2026_06_26.md | Offline/PWA idea; reference only until frontend resilience is prioritized. |
+| reference-only | antigravity_round32_extra_payload_performance_2026_06_26.md | Performance backlog; useful when API payload slimming resumes. |
+| archive | antigravity_round32_final_execution_board_2026_06_26.md | Superseded round board. |
+| reference-only | antigravity_round32_frontend_direct_coding_top40_2026_06_26.md | UI backlog; not canonical runtime map. |
+| promote | antigravity_round32_jhora_pyjhora_fast_capture_pipeline_2026_06_26.md | Capture pipeline can reduce oracle bottlenecks and should feed operator docs. |
+| promote | antigravity_round32_license_blacklist_recheck_2026_06_26.md | GPL/AGPL isolation remains a hard boundary. |
+| promote | antigravity_round32_local_accuracy_shortest_chain_final_2026_06_26.md | Accuracy shortest chain should connect to benchmark and preflight gates. |
+| reference-only | antigravity_round32_local_ux_direct_top30_2026_06_26.md | UX backlog only. |
+| promote | antigravity_round32_oracle_sample_push_matrix_2026_06_26.md | Oracle sample matrix belongs in benchmark planning. |
+| reference-only | antigravity_round32_sync_script_blueprint_2026_06_26.md | Sync script idea; keep constrained by no reverse `.workbuddy` authority. |
+| promote | antigravity_round32_timezone_dst_polar_direct_tasks_2026_06_26.md | Timezone, DST and polar handling affect chart correctness. |
+| promote | antigravity_round32_true_missing_techniques_rerank_top20_2026_06_26.md | Technique gap rerank should feed registry and roadmap. |
+| promote | antigravity_round32_whole_machine_fragment_reuse_fifth_pass_2026_06_26.md | Fragment reuse findings are useful after license/source re-anchoring. |
+| promote | antigravity_round36_asc_degree_yogi_tight_orb_wealth_pack_2026_06_26.md | Wealth-specific Yogi/tight-orb material supports strict finance adjudication. |
+| promote | antigravity_round36_bhrigu_pada_all_event_expansion_pack_2026_06_26.md | Event expansion material is relevant to historical backtest and timing routes. |
+| promote | antigravity_round36_global_first_honesty_board_2026_06_26.md | Honesty boundary belongs near oracle and benchmark governance. |
+| reference-only | antigravity_round36_pakshi_swara_boundary_pack_2026_06_26.md | Advanced traditional technique background; not current route-critical. |
+| reference-only | antigravity_round36_rtn_anomalous_d9_deepening_pack_2026_06_26.md | Niche D9 deepening background; promote only with current evidence. |
+| promote | antigravity_round36_tajika_sahams_external_closure_pack_2026_06_26.md | Tajika/Saham external closure is an active benchmark frontier. |
+| reference-only | antigravity_round36_tithi_lord_freeze_gap_pack_2026_06_26.md | Technique detail backlog; not current main-chain blocker. |
+| reference-only | antigravity_round37_article_template_industrialization_board_2026_06_26.md | Interpretation template backlog; useful after truth arbitration. |
+| archive | antigravity_round37_codex_round38_top100_2026_06_26.md | Execution board superseded by later focused documents. |
+| promote | antigravity_round37_dasha_external_oracle_shortest_closure_board_2026_06_26.md | Dasha external closure is a high-rigor requirement. |
+| promote | antigravity_round37_public_benchmark_moat_board_2026_06_26.md | Public benchmark strategy should inform benchmark dashboard governance. |
+| promote | antigravity_round37_shadbala_absolute_value_frontier_board_2026_06_26.md | Shadbala absolute values remain a precision frontier. |
+| promote | antigravity_round37_tajika_sahams_annual_closure_board_2026_06_26.md | Annual chart closure aligns with current Tajika oracle work. |
+| reference-only | antigravity_round38_advanced_sensitive_points_top20_2026_06_26.md | Advanced sensitive points backlog; not current strict route source. |
+| reference-only | antigravity_round38_article_detail_template_batch2_2026_06_26.md | Template backlog; keep behind truth arbitration. |
+| archive | antigravity_round38_codex_round39_top150_2026_06_26.md | Execution board superseded by current active fronts. |
+| promote | antigravity_round38_dasha_external_oracle_packet_factory_2026_06_26.md | Dasha oracle packet factory should feed operator packet docs/tests. |
+| reference-only | antigravity_round38_mrityu_bhaga_authority_table_hunt_2026_06_26.md | Authority-table research, but not active route-critical. |
+| promote | antigravity_round38_open_source_copy_whitelist_sensitive_points_2026_06_26.md | License-safe sensitive-point whitelist should be reconciled before reuse. |
+| promote | antigravity_round38_public_benchmark_board_v2_2026_06_26.md | Benchmark dashboard v2 should be promoted if public benchmark work resumes. |
+| promote | antigravity_round38_shadbala_absolute_value_capture_matrix_2026_06_26.md | Shadbala absolute capture matrix belongs with oracle closure planning. |
+| promote | antigravity_round38_skill_global_rank_gap_after_round38_2026_06_26.md | Global gap assessment informs honest capability claims. |
+| promote | antigravity_round38_whole_machine_fragment_reuse_sixth_pass_2026_06_26.md | Fragment reuse shortlist needs canonical anchoring. |
+| promote | antigravity_round39_yogi_wealth_bridge_audit_2026_06_28.md | Directly relevant to current wealth strict adjudication. |
+| promote | antigravity_round40_article_technique_truth_arbitration_2026_06_27.md | Truth arbitration prevents noisy article-derived code migration. |
+| archive | antigravity_round40_codex_round41_skill_top60_2026_06_27.md | Round-specific action board, not canonical truth. |
+| promote | antigravity_round40_dasha_second_wave_closure_pack_2026_06_27.md | Dasha second-wave closure supports high-rigor timing validation. |
+| promote | antigravity_round40_shadbala_absolute_authority_ladder_2026_06_27.md | Shadbala authority ladder belongs with precision/oracle governance. |
+| promote | antigravity_round40_tajika_annual_second_wave_board_2026_06_27.md | Tajika second-wave board supports annual oracle closure. |
+| promote | antigravity_round40_whole_machine_fragment_reuse_shortlist_2026_06_27.md | Top 20 fragment shortlist should be re-anchored to current code/tests. |
+| archive | antigravity_sidecar_work_order_round33_2026_06_26.md | Sidecar work order; historical coordination only. |
+| archive | antigravity_sidecar_work_order_round34_2026_06_26.md | Sidecar work order; historical coordination only. |
+| archive | antigravity_sidecar_work_order_round35_2026_06_26.md | Sidecar work order; historical coordination only. |
+| archive | antigravity_sidecar_work_order_round36_2026_06_26.md | Sidecar work order; historical coordination only. |
+| archive | antigravity_sidecar_work_order_round37_2026_06_26.md | Sidecar work order; historical coordination only. |
+| archive | antigravity_sidecar_work_order_round40_2026_06_27.md | Sidecar work order; historical coordination only. |
+| promote | article_technique_coverage_matrix_2026_06_26.md | Article-to-technique coverage matrix should remain a canonical truth-arbitration input. |
+| reference-only | chayue_screenshot_coverage_matrix_2026_06_26.md | Source-specific screenshot coverage; useful as evidence only. |
+| reference-only | cloud_sync_minimum_whitelist_for_skill_truth_2026_06_26.md | Sync governance background; no reverse authority over main repo. |
+| promote | current_skill_core_gap_rerank_2026_06_26.md | Current skill gap rerank should feed active roadmap and registry work. |
+| promote | dasha_accuracy_closure_status_2026_06_26.md | Dasha closure status is a high-rigor timing boundary. |
+| promote | dasha_code_only_priority_rerank_2026_06_26.md | Code-only Dasha prioritization can guide scoped local improvements. |
+| promote | five_hard_fronts_master_board_2026_06_26.md | Five-front board is the best compact strategic index for precision gaps. |
+| archive | git_execution_card_skill_truth_only_2026_06_26.md | One-off git execution card; no ongoing truth role. |
+| promote | global_open_source_positioning_of_skill_2026_06_26.md | Honest positioning is required for claims and benchmark framing. |
+| promote | high_granularity_technique_deepening_backlog_2026_06_26.md | Technique deepening backlog should be reconciled with the registry. |
+| promote | jhora_capture_task_v2.md | Human oracle capture task should connect to benchmark packets. |
+| reference-only | recovered_old_skill_reuse_audit_2026_06_26.md | Recovery audit; reuse only after current-code and license recheck. |
+| promote | reuse_license_whitelist_for_skill_2026_06_26.md | Reuse license whitelist should be canonical before any migration. |
+| promote | skill_fragment_map_and_source_of_truth_2026_06_26.md | Source-of-truth map supports mirror and fragment discipline. |
+| promote | skill_single_source_of_truth_disposition_2026_06_26.md | Single-source disposition remains a governance anchor. |
+| promote | skill_truth_conflict_matrix_2026_06_26.md | Conflict matrix should inform future source-truth decisions. |
+| promote | three_fronts_skill_depth_audit_2026_06_26.md | Three-front depth audit is compact and still relevant to skill depth. |
+| reference-only | zhanxingyindu1_screenshot_coverage_matrix_2026_06_26.md | Source-specific screenshot coverage; useful as evidence only. |
+
+## Immediate Next Use
+
+When a future task needs one of these drafts, first copy the claim into a canonical target and verify it against current code/tests. Never import code or truth from `.workbuddy` or local drafts directly into the runtime chain.

docs/research/unique_main_chain_map_2026_07_01.md

@@ -0,0 +1,64 @@
+# Unique Main Chain Map
+
+Date: 2026-07-01
+
+This is the single current map for the Jyotish runtime chain. It does not replace `SKILL.md`, `AGENTS.md`, or `references/strict-workflow-router.md`; it names which file owns each entrypoint and how they should relate. The main repo is the source of truth. Historical mirrors, including `.workbuddy`, are reference/distribution material only and must not import from `.workbuddy`.
+
+## Authority Rule
+
+- Runtime truth lives in this repository: `scripts/`, `mcp_server.py`, `jyotish_vedic/`, `references/`, and `tests/`.
+- `SKILL.md` is the skill/user-facing instruction entry.
+- `AGENTS.md` is the hard override for high-rigor project behavior, including Functional Benefic/Malefic and honesty boundaries.
+- `references/strict-workflow-router.md` is the route checklist for career, relationship, finance, timing, historical verification, and technique reliability questions.
+- `.workbuddy` is a distribution mirror or historical recovery source. It can be inspected as evidence, but runtime code must not import from `.workbuddy`.
+
+## Entrypoint Map
+
+| Entry | Owner | Role | Calls / Depends On | Boundary |
+|---|---|---|---|---|
+| Skill entry | `SKILL.md` | Human/agent instruction surface for Jyotish analysis | `references/strict-workflow-router.md`, `AGENTS.md`, canonical references | Instruction truth only; not executable runtime. |
+| Web/API entry | `scripts/jyotish_api_server.py` | Local HTTP API for `jyotish-app` and high-rigor workflow jobs | `scripts/unified_consultation_orchestrator.py`, local modules, chart cache, rectification gate, historical backtest loader | Must route through local repo modules and preserve API/cache provenance. |
+| MCP entry | `mcp_server.py` | AI-native tool surface for chart, Dasha, Shadbala, Ashtakavarga, Varga, full reading, and `strict_workflow` | Local `scripts/` modules, `UnifiedConsultationOrchestrator`, functional-benefic layer, VedAstro evidence summaries | MCP strict workflow is the canonical reusable strict adjudication surface. |
+| Shared route contract | `scripts/unified_consultation_orchestrator.py` | Normalizes themes/questions and builds the surface-agnostic runtime planner | Web/API and MCP callers | Owns route naming and sync/async step planning; does not itself calculate astrology. |
+| VedAstro official entry | `scripts/vedastro_service_adapter.py` | Controlled official evidence boundary: official full snapshot, range scan, external technique calls | VedAstro official endpoint/env, official Python bridge/capability runner where configured | VedAstro official snapshot has priority when available; local modules supplement or fallback when official evidence is blocked. |
+| Strict workflow entry | `mcp_server.py::strict_workflow` | Main strict adjudication chain for career, relationship, finance, timing and event judgement | `mcp_server.py` evidence collectors, functional benefic/malefic, Shadbala, Ashtakavarga, Dasha, Varga, VedAstro official evidence | Must expose missing evidence, conflicts, confidence caps, and Technique Audit Table facts. |
+| Rectification entry | `scripts/jyotish_api_server.py` `/api/rectification_gate` | Birth-time rectification gate reused by high-rigor workflow | Chart payload, rectification references and frontend rectification engine outputs | Rectification is a gate/support layer, not proof by itself. |
+| Historical backtest entry | `scripts/historical_event_backtest.py` | Reusable historical event backtest runner | Calls `mcp_server.strict_workflow` for supported event domains | Measures route support for supplied events; blocked/unsupported cases must not be overstated as predictive accuracy. |
+
+## Main Flow
+
+```mermaid
+flowchart TD
+  Skill["SKILL.md"] --> Router["references/strict-workflow-router.md"]
+  Web["scripts/jyotish_api_server.py"] --> Orchestrator["scripts/unified_consultation_orchestrator.py"]
+  MCP["mcp_server.py"] --> Orchestrator
+  Orchestrator --> Strict["mcp_server.py::strict_workflow"]
+  Web --> Rectification["/api/rectification_gate"]
+  Web --> Backtest["scripts/historical_event_backtest.py"]
+  Backtest --> Strict
+  Strict --> VedAstro["scripts/vedastro_service_adapter.py"]
+  Strict --> Local["local scripts: varga, dasha, shadbala, ashtakavarga, functional benefics"]
+```
+
+## High-Rigor Domain Requirements
+
+| Domain | Mandatory local evidence | Mandatory timing cross-check | External/oracle boundary |
+|---|---|---|---|
+| Career | D10 + A10, Shadbala, Ashtakavarga, Functional Benefic/Malefic | Vimshottari + Narayana Dasha | VedAstro official snapshot/range scan where available; PyJHora and jyotishganit remain external reference layers with license boundaries. |
+| Wealth | D2 / D11, Shadbala, Ashtakavarga, Functional Benefic/Malefic | Vimshottari + Narayana Dasha | Treat VedAstro official evidence as external context; do not upgrade blocked external layers to validation. |
+| Relationship | D9 + UL, Darakaraka/7th-house context, Functional Benefic/Malefic | Vimshottari + Narayana Dasha | External oracle closure remains required for high-confidence timing claims. |
+| Historical event | Route-specific Varga, Dasha, Shadbala, Ashtakavarga, Functional Benefic/Malefic | Vimshottari + Narayana Dasha | `scripts/historical_event_backtest.py` must mark blocked/unsupported/miss honestly. |
+
+## Non-Goals
+
+- This document does not authorize copying code from `.workbuddy`, PyJHora, GPL/AGPL projects, or local drafts.
+- This document does not claim that every VedAstro official method runs on every request.
+- This document does not close external oracle validation by itself.
+
+## Verification Hooks
+
+- Runtime mirror guard: `tests/test_runtime_import_boundaries.py`
+- Preflight governance: `tests/test_preflight_fragment_scan.py`
+- Main-chain and draft governance docs: `tests/test_research_governance_docs.py`
+- Shared route planner: `tests/test_unified_consultation_orchestrator.py`
+- Historical event backtest: `tests/test_historical_event_backtest.py`