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

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.