Jyotisha/docs/superpowers/plans/2026-06-29-vedastro-adapter-mvp.md

VedAstro Adapter MVP 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: Complete the VedAstro Adapter MVP as a gated external timing radar with provenance, strict workflow injection, Trust Center status, and optional live smoke.

Architecture: Extend the existing scripts/vedastro_service_adapter.py service boundary instead of replacing local computation. Add deterministic mock-tested behavior by default and a separate optional live profile when VEDASTRO_API_ENDPOINT and VEDASTRO_ENABLE_NETWORK are configured.

Tech Stack: Python standard library HTTP/JSON, pytest, existing scripts/run_quality_gate.py, existing jyotish-app JavaScript Trust Center.

Global Constraints

• Local Jyotish computation remains authoritative.
• VedAstro evidence may only enter secondary_context, technique_audit, external_activation, and Life Event Graph external nodes.
• Default CI must not depend on live network.
• No secrets may be rendered in the frontend.
• New production behavior must be introduced with failing tests first.

---

Task 1: Adapter Provenance, Retry, and Artifact Persistence

Files:

• Modify: scripts/vedastro_service_adapter.py
• Test: tests/test_vedastro_service_adapter_executor.py

Interfaces:

• Produces: run_range_scan(case_id: str, domain: str, start_date: str, end_date: str) -> dict

• Produces metadata keys: request_hash, response_hash, called_at, artifact_path, allowlist_event_count, filtered_event_count

• Step 1: Write failing tests

Add tests asserting live mock range-scan writes an artifact and records request/response hashes, plus retry succeeds after one 503.

• Step 2: Run red tests

Run: python3 -m pytest tests/test_vedastro_service_adapter_executor.py -k "artifact or retry" -q

Expected: fails because provenance/artifact/retry fields are missing.

• Step 3: Implement minimal adapter changes

Add deterministic SHA-256 helpers, UTC called_at, scratch artifact writer, and retry loop around _post_json.

• Step 4: Run green tests

Run: python3 -m pytest tests/test_vedastro_service_adapter_executor.py -q

Expected: all adapter executor tests pass.

Task 2: Backend Status Route and Live Quality Gate

Files:

• Modify: scripts/jyotish_api_server.py
• Modify: scripts/run_quality_gate.py
• Test: tests/test_api_server_security.py
• Test: tests/test_vedastro_service_adapter_executor.py

Interfaces:

• Produces: GET /api/vedastro/status

• Produces quality profile: vedastro-live

• Step 1: Write failing tests

Add API test requiring /api/vedastro/status to report configured, network_enabled, status, and safe provenance fields. Add quality-gate static test requiring vedastro-live.

• Step 2: Run red tests

Run: python3 -m pytest tests/test_api_server_security.py -k vedastro_status -q

Expected: fails because the route is absent.

• Step 3: Implement route and quality profile

Expose safe status from adapter schema/env and add a vedastro-live profile that runs the adapter live smoke only when configured, otherwise reports a controlled skip/blocked message.

• Step 4: Run green tests

Run: python3 -m pytest tests/test_api_server_security.py tests/test_vedastro_service_adapter_executor.py -k "vedastro" -q

Expected: focused VedAstro tests pass.

Task 3: Strict Workflow Auto-Injection

Files:

• Modify: mcp_server.py
• Test: tests/test_mcp_strict_workflow_relationship.py
• Test: tests/test_mcp_strict_workflow_career.py
• Test: tests/test_mcp_strict_workflow_finance.py
• Test: tests/test_life_event_graph_v1.py

Interfaces:

• Consumes: modules.external_activation.evidence_ledger

• Produces: strict workflow external_activation when adapter evidence is supplied or generated by a helper.

• Step 1: Write failing tests

Add tests requiring strict workflow to accept an adapter result and render external nodes in Life Event Graph without score/label override.

• Step 2: Run red tests

Run: python3 -m pytest tests/test_mcp_strict_workflow_relationship.py tests/test_life_event_graph_v1.py -k "vedastro or external" -q

Expected: fails for missing auto-injection or graph fields.

• Step 3: Implement minimal strict workflow bridge

Normalize adapter result into modules.external_activation and preserve the existing blocked row when no evidence is available.

• Step 4: Run green tests

Run: python3 -m pytest tests/test_mcp_strict_workflow_relationship.py tests/test_mcp_strict_workflow_career.py tests/test_mcp_strict_workflow_finance.py tests/test_life_event_graph_v1.py -q

Expected: strict workflow tests pass.

Task 4: Trust Center Status Surface

Files:

• Modify: jyotish-app/main.js
• Modify: jyotish-app/export.js if status is exported
• Test: tests/test_frontend_productization.py

Interfaces:

• Consumes: /api/vedastro/status

• Produces visible Trust Center status labels without rendering endpoint secrets.

• Step 1: Write failing frontend static test

Require renderVedAstroStatus, /api/vedastro/status, VEDASTRO_API_ENDPOINT, and a non-secret status label in Trust Center.

• Step 2: Run red test

Run: python3 -m pytest tests/test_frontend_productization.py -k vedastro -q

Expected: fails because Trust Center status is not rendered.

• Step 3: Implement frontend status card

Add a compact Trust Center row showing unconfigured/network disabled/live-ready/last artifact states.

• Step 4: Run green tests

Run: python3 -m pytest tests/test_frontend_productization.py -k vedastro -q && npm run build --prefix jyotish-app

Expected: frontend tests and build pass.

Task 5: Verification and Progress Update

Files:

• Modify: progress.md
• Modify: findings.md

Interfaces:

• Produces: permanent project log with exact verification commands.

• Step 1: Run focused verification

Run: python3 -m pytest tests/test_vedastro_service_adapter_executor.py tests/test_vedastro_external_technique_evidence.py tests/test_vedastro_parity_matrix.py tests/test_vedastro_adapter_candidate_guard.py -q

• Step 2: Run workflow verification

Run: python3 -m pytest tests/test_mcp_strict_workflow_finance.py tests/test_mcp_strict_workflow_relationship.py tests/test_mcp_strict_workflow_career.py tests/test_life_event_graph_v1.py -q

• Step 3: Run product verification

Run: python3 -m pytest tests/test_api_server_security.py tests/test_frontend_productization.py -k "vedastro or trust or api_runtime" -q && npm run build --prefix jyotish-app

• Step 4: Run quick gate

Run: python3 scripts/run_quality_gate.py --profile quick --skip-frontend-runtime

• Step 5: Update progress files

Record implemented files, blocked live endpoint boundary, and verification results in progress.md and findings.md.

Self-Review

• Spec coverage: adapter provenance, live gate, strict workflow injection, Trust Center, and verification are each assigned to a task.
• Placeholder scan: no TBD/TODO placeholders remain.
• Type consistency: adapter result fields use existing evidence_ledger and source_metadata contracts.