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

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