docs: sync cross repo advantage plan

docs/research/commercial_onboarding_ux_research_contract_2026_07_19.md

@@ -0,0 +1,52 @@
+# Commercial onboarding UX → research contract — 2026-07-19
+
+Purpose: reuse commercial UX strengths in the research repo without importing business runtime.
+
+## Flow to learn
+
+称呼 → 出生时间 → 出生地点 → 时间校正
+
+Observed commercial strengths:
+
+- conversational first contact instead of static form
+- one question per step
+- progressive disclosure: ask only the next missing datum
+- birth-time uncertainty is accepted instead of forcing a fake exact time
+- profile-missing guidance instead of generic failure
+- 资料缺失时引导补全，不把缺失说成系统错误
+- mobile-first chat layout
+- starter questions after onboarding
+- visible evidence-status language: based on chart evidence, not generic horoscope prose
+
+## Research-safe abstraction
+
+Target form: research interaction prototype.
+
+Allowed:
+
+- onboarding flow contract
+- prompt/response transcript fixtures
+- birth-time uncertainty UX notes
+- evidence-status display notes
+- mobile layout references
+- tests that ensure missing data prompts are useful
+
+Forbidden:
+
+- 不迁移积分、支付、商业账户权益
+- no Supabase service-role runtime
+- no production authentication dependency
+- no commercial redemption/admin-code logic
+
+## Contract requirements
+
+1. If name is missing, ask for name/nickname only.
+2. If birth time is missing or uncertain, ask for known precision; do not force exact time.
+3. If place is missing, ask for place after birth-time step.
+4. If profile remains incomplete, explain the missing field and continue useful guidance where possible.
+5. When chart evidence is available, label answers as evidence-based.
+6. Do not hide claim boundaries behind a friendly UI.
+
+## Next implementation target
+
+Create a lightweight research prototype that can replay onboarding transcripts and show which evidence layers would become available after each step.

docs/research/cross_repo_advantage_sync_status_2026_07_19.md

@@ -0,0 +1,58 @@
+# Cross-repo advantage sync status — 2026-07-19
+
+Scope: this window synchronizes strengths between the research repo and the commercial repo.
+
+## Direction rules
+
+### Research → Commercial
+
+Move mature astrology capability, validation contracts, oracle boundaries, and answer policies only.
+
+Already synced or in progress:
+
+- timing precision contract: `verified_window`, `candidate_windows`, `exact_triggers`, `claim_status=exploratory_unvalidated`
+- three-engine mismatch attribution
+- Xalen fourth-oracle formula isolation
+- VedAstro hosted/pinned identity boundaries
+- Shadbala/Ashtakavarga component provenance registry
+- gender interpretation boundary
+- day-level holdout validator/template/blind-eval/intake scaffolding
+
+Blocked / not upgraded:
+
+- day-level holdout: still awaiting independent human negative labels
+- VedAstro hosted identity: hosted deployment build/version still not pinned
+- Shadbala/AV worked example: lineage attribution exists, but authoritative step-by-step worked example arbitration is still incomplete
+
+### Commercial → Research
+
+Move user-experience knowledge that improves research interaction prototypes; not credits, billing, payment, or Supabase service-role runtime.
+
+Commercial UX strengths to abstract:
+
+- conversational onboarding
+- 称呼 → 出生时间 → 出生地点 → 时间校正
+- mobile-first chat layout
+- evidence-based answer status
+- profile-missing guidance instead of generic failure
+- starter question suggestions
+- birth-time uncertainty flow
+
+Research-safe target:
+
+- research interaction prototype
+- UX contract documents
+- testable prompt/flow expectations
+- no commercial account/credit/payment runtime
+
+## Next sequence
+
+1. Keep this ledger current after every cross-repo sync.
+2. Run the commercial eight-question astrology E2E acceptance contract.
+3. Abstract commercial onboarding UX back into research docs/prototypes.
+4. After DB/business dependencies are handled by collaborators, add a formal gender field chain if needed.
+5. Continue deep blockers: day-level holdout, VedAstro hosted identity, Shadbala/AV worked example.
+
+## Current claim boundary
+
+File sync is not equal to runtime proof. A capability is only `e2e_verified` after a real commercial question demonstrates the expected layers in answer context and the answer respects all boundary language.

references/cross_project_contract/commercial_astrology_e2e_acceptance_questions_2026_07_19.json

@@ -0,0 +1,57 @@
+{
+  "contract_id": "commercial_astrology_e2e_acceptance_questions_2026_07_19",
+  "status": "acceptance_contract_not_runtime_claim",
+  "purpose": "Eight real-user commercial questions used to verify that synchronized astrology capabilities enter the answer context and preserve claim boundaries.",
+  "questions": [
+    {
+      "id": "marriage_timing",
+      "user_question": "我什么时候更适合结婚？",
+      "required_layers": ["Vimshottari Dasha", "Narayana Dasha", "D9", "UL", "Darakaraka", "timing precision contract", "gender interpretation boundary"],
+      "must_not_claim": ["exact day/month verified", "single-factor Venus/Jupiter truth"]
+    },
+    {
+      "id": "career_direction",
+      "user_question": "我的事业方向适合什么？",
+      "required_layers": ["Vimshottari Dasha", "Narayana Dasha", "D10", "A10", "functional benefic/malefic"],
+      "must_not_claim": ["gender changes career math", "D10 missing when present"]
+    },
+    {
+      "id": "wealth_pattern",
+      "user_question": "我的财富模式和赚钱方式是什么？",
+      "required_layers": ["Vimshottari Dasha", "Narayana Dasha", "D2", "D11", "Ashtakavarga", "functional benefic/malefic"],
+      "must_not_claim": ["guaranteed financial outcome", "D2/D11 missing when present"]
+    },
+    {
+      "id": "foreign_migration",
+      "user_question": "我适合出国发展或长期迁移吗？",
+      "required_layers": ["Vimshottari Dasha", "Narayana Dasha", "D4", "D9", "12th house", "Rahu/Ketu context"],
+      "must_not_claim": ["visa/legal guarantee"]
+    },
+    {
+      "id": "relationship_compatibility",
+      "user_question": "我和这个人合不合？",
+      "required_layers": ["D9", "UL", "Darakaraka", "Ashtakoot boundary", "gender interpretation boundary"],
+      "must_not_claim": ["relationship guarantee", "gender binary forced when not provided"]
+    },
+    {
+      "id": "birth_time_uncertain",
+      "user_question": "我的出生时间不太准，还能看吗？",
+      "required_layers": ["birth-time uncertainty boundary", "rectification boundary", "candidate windows", "not_auto_rectified"],
+      "must_not_claim": ["auto-rectified exact birth time"]
+    },
+    {
+      "id": "engine_disagreement",
+      "user_question": "为什么不同软件算出来不一样？",
+      "required_layers": ["Shadbala", "Ashtakavarga", "Shadbala/AV provenance registry", "VedAstro gateway boundary", "no_majority_vote"],
+      "must_not_claim": ["majority vote truth", "method variant as absolute error"]
+    },
+    {
+      "id": "precise_timing_boundary",
+      "user_question": "你能不能精确看某一天或某个月会发生什么？",
+      "required_layers": ["timing precision contract", "verified_window", "candidate_windows", "exact_triggers", "day-level holdout boundary"],
+      "must_not_claim": ["day/month prediction verified before holdout", "exact_triggers as guaranteed events"]
+    }
+  ],
+  "pass_condition": "For each question, the commercial answer context includes required layers or explicitly reports a justified missing layer, and the answer avoids every must_not_claim item.",
+  "blocked_until_runtime_e2e": true
+}

tests/test_cross_repo_advantage_sync_plan.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+LEDGER = ROOT / "docs" / "research" / "cross_repo_advantage_sync_status_2026_07_19.md"
+E2E = ROOT / "references" / "cross_project_contract" / "commercial_astrology_e2e_acceptance_questions_2026_07_19.json"
+UX = ROOT / "docs" / "research" / "commercial_onboarding_ux_research_contract_2026_07_19.md"
+
+
+def test_cross_repo_advantage_ledger_tracks_both_directions_and_blockers() -> None:
+    text = LEDGER.read_text(encoding="utf-8")
+
+    assert "Research → Commercial" in text
+    assert "Commercial → Research" in text
+    assert "not credits, billing, payment, or Supabase service-role runtime" in text
+    assert "gender interpretation boundary" in text
+    assert "day-level holdout" in text
+    assert "VedAstro hosted identity" in text
+    assert "Shadbala/AV worked example" in text
+
+
+def test_commercial_e2e_acceptance_has_eight_real_user_questions() -> None:
+    data = json.loads(E2E.read_text(encoding="utf-8"))
+
+    assert data["contract_id"] == "commercial_astrology_e2e_acceptance_questions_2026_07_19"
+    assert data["status"] == "acceptance_contract_not_runtime_claim"
+    assert len(data["questions"]) == 8
+    required_layers = {layer for q in data["questions"] for layer in q["required_layers"]}
+    for layer in {
+        "Vimshottari Dasha",
+        "Narayana Dasha",
+        "D9",
+        "D10",
+        "D2",
+        "D11",
+        "UL",
+        "A10",
+        "Shadbala",
+        "Ashtakavarga",
+        "VedAstro gateway boundary",
+        "timing precision contract",
+        "gender interpretation boundary",
+    }:
+        assert layer in required_layers
+
+
+def test_commercial_onboarding_ux_contract_is_research_safe() -> None:
+    text = UX.read_text(encoding="utf-8")
+
+    assert "称呼 → 出生时间 → 出生地点 → 时间校正" in text
+    assert "资料缺失时引导补全，不把缺失说成系统错误" in text
+    assert "不迁移积分、支付、商业账户权益" in text
+    assert "research interaction prototype" in text