# 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.