docs: product-level README, AGENTS.md split into code/reading parts, add CLAUDE.md, move task briefs to docs/tasks

- README.md is now the product/repo front door (architecture, repo map, local dev, test tiers, delivery flow, doc map). Engine positioning, VedAstro/Codex setup and the oracle/benchmark command reference move verbatim to docs/engine/README.md, docs/engine/vedastro-gateway.md and docs/benchmark/README.md. Capability badges realigned with the registry (91/78/8/0); tests/test_readme_badges.py was red on staging. - AGENTS.md: Part A (environment truth, delivery, worktrees, record placement, bug workflow, growth freeze, frontend red lines, privacy, pre-work check, test tiers) and Part B (reading-rigor constraints). GitHub issue-tracker/triage boilerplate removed: GitHub is a read-only mirror. All strings locked by tests/ are preserved. - CLAUDE.md added: roles, three working modes, task-brief sections, acceptance criteria, session discipline; imports AGENTS.md. - 50 tracked TASK-*/PROGRESS-* files and 3 never-committed briefs move to docs/tasks/ with an index; REPO_LAYOUT.md merged into README. Docs-only change (no gated path touched). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0193vBv6w5MV2cifdTUu9H5P
2026-09-03 06:56:06 +00:00
parent af411f590a
commit 8db71aaf81
63 changed files with 1958 additions and 1196 deletions
@@ -0,0 +1,260 @@
+# 准确率基线、外部 Oracle 闭环与 Benchmark 看板
+
+> 本文从根 README 拆出（2026-09-03），内容原样保留。这里是所有"本机现在能跑什么、哪些指标可测、哪些能力还缺外部 oracle 证据"的命令入口；看板产物就在本目录。所有看板固定输出 `can_claim_global_first: false` 与 `production_tuning_allowed: false`，直到外部样本达到生产调参标准。
+
+### 真实案例复验与准确率边界
+
+一条命令查看本机当前技能覆盖与准确率基线：
+
+```bash
+python3 scripts/local_accuracy_report.py --format markdown
+```
+
+如需给副手、CI 或后续自动化读取，使用 JSON：
+
+```bash
+python3 scripts/local_accuracy_report.py --format json
+```
+
+当前总控报告会聚合 technique registry、BPHS invariants、公开人物真实案例复验、Yoga precision/recall/F1、Dasha/Shadbala oracle readiness、Ashtakoot API parity。它用于回答“本机现在能跑什么、哪些指标已经可测、哪些能力还缺外部 oracle 证据”；它不把本地回归测试包装成最终人生事件预测准确率。
+
+公开人物样本复验命令：`python3 tests/run_real_case_revalidation.py`。
+
+当前复验口径是公开人物样本的出生盘星座级一致率，并对部分带有来源矛盾、时区争议或边界度数的参考行标记为 controversial_reference。这个指标用于验证排盘计算是否稳定，不等同于人生事件预测准确率，也不应被当作个人命运判断的命中率。
+
+### Dasha 参考差异审计
+
+对照外部 PDF 或第三方软件时，先运行 Dasha 参考差异审计，而不是直接改生产常数：
+
+```bash
+python3 scripts/dasha_reference_audit.py \
+  --year YYYY --month MM --day DD \
+  --hour HH --minute mm --second ss \
+  --lat LAT --lon LON --tz TZ \
+  --target-start-date 1986-05-18 \
+  --target-source third_party_chart.pdf
+```
+
+该工具会输出当前 Vimshottari 起点、秒级出生时间敏感性、年长常数敏感性，以及对齐目标日期所需的 Moon sidereal longitude 偏移量。不要为单份 PDF 直接调生产常数；应先建立更大的 oracle 样本集，比较 ayanamsa、Moon sidereal longitude、Nakshatra 边界与 Vimshottari 起算口径。
+
+也可以运行合并版外部 oracle 边界审计，同时查看 Dasha、外部黄经与 Shadbala 的校准状态：
+
+```bash
+python3 scripts/oracle_boundary_audit.py \
+  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json
+```
+
+该报告会明确标出 `production_tuning_recommended: false`：当前目标集已有外部验证行，但差异审计仍会拒绝单样本或全局倍率调参；VedAstro SDK 黄经样本已纳入 `longitude_cases`，用户盘最大差异约 26.23 角秒、D1/D9 落点一致，但这只能说明基础黄经接近，不能把当前目标集闭合夸大成生产级全局校准。
+
+三方官方/外部 oracle sanity 总控命令：
+
+```bash
+python3 scripts/external_oracle_sanity_closure.py --format markdown
+```
+
+该报告同时检查 VedAstro official precision sanity、PyJHora black-box artifacts、jyotishganit MIT reference layer。默认命令为非阻塞 sanity，总控质量门可运行；需要真实触发 VedAstro official full snapshot 细算时，加 `--live-official-full-snapshot`。当前允许声明的是“高严谨带 blocked 行”：PyJHora 黑盒证据与 jyotishganit 参考层可审计；VedAstro 黄经 sanity 通过但 official full snapshot 细算仍需显式 live probe 且可能因前台预算或官方快照合同 blocked，不能声称三方 fully closed。
+
+外部真值采集队列用于把缺失目标值拆成可执行任务，而不是直接调生产参数：
+
+```bash
+python3 scripts/oracle_collection_queue.py \
+  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
+  --format markdown
+```
+
+如需给自动化或副手读取，可改用 JSON 输出：
+
+```bash
+python3 scripts/oracle_collection_queue.py \
+  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
+  --format json
+```
+
+如需让真人或 Antigravity AI 副手直接填写证据包，可一次性导出每个 case 的 draft JSON：
+
+```bash
+python3 scripts/prepare_oracle_capture_packets.py \
+  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
+  --output-dir references/oracle/artifacts/pending_packets
+```
+
+该命令会生成 `capture_manifest.json`、`OPERATOR_NEXT_STEPS.md` 和 5 个 `external_*.json`。这些导出包只是人工复核/再采集入口；当前主 oracle 文件的目标集状态以 closure dashboard 和 validator 输出为准。
+
+如果只想优先准备当前最短闭环链路的三条首包，而不是一次性导出整批 pending packets，可直接生成统一 blank kit：
+
+```bash
+python3 scripts/generate_blank_oracle.py \
+  --output-dir references/oracle/artifacts/first_packet_blank_kit
+```
+
+该命令会按当前推荐顺序导出 `dasha`、`tajika_sahams`、`shadbala` 三条 front 的首包草稿、`blank_oracle_kit_manifest.json` 和 `BLANK_ORACLE_KIT_NEXT_STEPS.md`。它只复制当前首包模板，不会猜测真值，也不会把本地引擎输出伪装成 external oracle。
+
+填完某个 `external_*.json` 后，必须把 `status` 改为 `external_verified`，补齐 metadata、具体 `source_artifact` 文件路径以及所有 `target_placeholders`。再把该包合并回 oracle 文件：
+
+```bash
+python3 scripts/oracle_collection_queue.py \
+  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
+  --apply-packet references/oracle/artifacts/pending_packets/external_template_steve_jobs_dasha_lahiri.json \
+  --format json
+```
+
+这一步只负责把人工填写的外部证据写回 `template_cases`；它不会自动认可证据，也不会允许生产调参。合并后仍必须重新生成 queue 并运行 validator。
+
+该 JSON 的 scope 是 `external_oracle_collection_queue`。当前目标集可以出现 `external_verified` 与 `ready_for_calibration` 已闭合的状态，但 `production_tuning_allowed` 仍保持 `false`；这表示只能把外部黑盒目标值作为审计证据，不能直接用这些样本做 Dasha/Shadbala 生产调参。
+
+Ashtakoot 外部合婚 oracle 使用同一个队列生成器，但独立样本文件是 `references/oracle/ashtakoot_oracle_cases.json`：
+
+```bash
+python3 scripts/oracle_collection_queue.py \
+  --oracle-file references/oracle/ashtakoot_oracle_cases.json \
+  --format json
+```
+
+该队列同样保持 `ready_for_calibration: 0`，用于采集 `ashtakoot_36_point` 外部合婚目标值，而不是重写现有 `scripts/ashtakoot.py` 算法。每条样本要补齐 `target.total_score`、`target.varna`、`target.vashya`、`target.tara`、`target.yoni`、`target.graha_maitri`、`target.gana`、`target.bhakoot`、`target.nadi`、`target.kuja_status`，并保留 JHora/VedAstro/AstroSage 等外部截图或 API artifact。
+
+每个队列任务还包含 `evidence_packet.capture_id` 草稿证据包。人工或副手录入外部真值时，必须至少填写 `tool_name`、`tool_version_or_url`、`capture_date`、`source_artifact`、`ayanamsa`、`node_mode`、`timezone`、`operator_note`，并保留截图、API 响应或 stdout 等外部 artifact；不得把本仓库本地计算输出当作 `source_artifact`。
+
+外部截图和 stdout 片段统一存入 `references/oracle/artifacts/`，证据包里的 `source_artifact` 必须使用该目录下的 repo-relative 路径或明确标注的外部审阅位置。所有私人截图必须打码；不得提交私人 PDF 原件、不得提交完整出生报告，也不得提交浏览器 scratch 目录或含账号会话/cookie/token/桌面通知的截图。
+
+第一条 JHora/PyJHora 黑盒证据采集按 `docs/user_jhora_capture_guide.md` 执行：优先使用 Steve Jobs 或合成样本，采集 Moon sidereal longitude、Vimshottari start date 与 Shadbala 七曜六分量，保存到 `references/oracle/artifacts/` 后再运行 evidence validator。
+
+外部目标字段采用 `target_fields` + `target_placeholders` 双层结构：`target_fields` 固定记录该案例需要校验的目标，例如 `target.moon_sidereal_longitude_deg`、`target.vimshottari_start_date`、`target.shadbala_components`；当这些字段被真实外部来源填入并且证据包状态升为 `external_verified` 后，队列生成器会保留这些值，不会再把它们降级成 `draft`。这保证了“人工/JHora/PyJHora/VedAstro 采集 → JSON 填写 → 队列生成 → validator 复核”的路径可复验。
+
+当外部证据包被填写回队列 JSON 后，用证据验证器做第二层防线：
+
+```bash
+python3 scripts/oracle_evidence_validator.py \
+  --queue-file /path/to/filled_external_oracle_collection_queue.json
+```
+
+该验证器输出 `external_oracle_evidence_validation`，会检查 `evidence_packet` 必填元数据、`target_placeholders` 是否已填、是否覆盖 `target_fields`、是否包含外部 artifact，以及是否错误使用本仓库本地引擎输出。只有状态为 `external_verified` 且证据完整的包才会进入可复核状态；通过 validator 不等于允许生产调参。
+
+证据包通过 validator 之后，再运行边界差异审计，比较本地引擎与外部 Dasha/Shadbala 目标值：
+
+```bash
+python3 scripts/oracle_boundary_audit.py \
+  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json
+```
+
+审计报告中的 `template_comparisons` 会列出 external-verified template 的 Dasha 起点差异、Shadbala 七曜分量/总分差异、每个分量的 Rupa 容差、单位说明和 `global_scaling_check.recommendation: reject_global_scaling`，并继续保持 `production_tuning_recommended: false`，防止用单个样本或全局倍率调生产常数。
+
+公开 benchmark 看板用于长期展示能力状态、oracle readiness 和“是否可宣称全球第一”的诚实边界：
+
+```bash
+python3 scripts/public_benchmark_dashboard.py \
+  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
+  --format markdown \
+  --output docs/benchmark/public_jyotish_benchmark_dashboard.md
+```
+
+当前看板固定输出 `can_claim_global_first: false`，直到外部 oracle 样本、差异审计和长期公开 benchmark 都达到生产调参标准。
+
+外部 oracle 总控 closure 看板会合并 Dasha、Shadbala 与 Tajika/Sahams 三条硬闭环战线，给出总任务数、已验证数、第一优先级和下一条执行命令：
+
+```bash
+python3 scripts/oracle_closure_master_dashboard.py \
+  --dasha-oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
+  --tajika-oracle-file references/oracle/tajika_annual_oracle_cases.json \
+  --format markdown \
+  --output docs/benchmark/jyotish_external_oracle_closure_master_dashboard.md
+```
+
+当前总控看板输出 `total_tasks: 12`、`external_verified_tasks: 12`、`can_claim_current_target_set_closure: true`，但 `can_claim_global_oracle_closure: false` 与 `production_tuning_allowed: false` 仍保持锁定。含义是当前目标集已闭合，不能夸大成全球 oracle、预测准确率或生产调参闭环。
+
+Dasha 外部 oracle 最短闭环状态板用于把“大运外部真值”从 Shadbala 绝对值大包中拆出来，优先推进第一条可验证边界日期：
+
+```bash
+python3 scripts/dasha_oracle_closure_status.py \
+  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
+  --format markdown \
+  --output docs/benchmark/dasha_external_oracle_closure_status.md
+```
+
+当前第一优先级是 `external_template_steve_jobs_dasha_lahiri`。该状态板只要求 `target.vimshottari_start_date` 和外部证据 metadata，不要求同时填完 Shadbala 七曜六分量；这样可以先完成 Dasha oracle 的第一条闭环，再单独推进 Shadbala 绝对值闭环。
+
+第一条外部证据包的交互辅助命令：
+
+```bash
+python3 scripts/first_oracle_packet_assistant.py \
+  --front dasha \
+  --format markdown \
+  --output docs/benchmark/first_dasha_oracle_packet_assistant.md
+```
+
+同一个助手也支持：
+
+```bash
+python3 scripts/first_oracle_packet_assistant.py --front tajika_sahams --format markdown --output docs/benchmark/first_tajika_oracle_packet_assistant.md
+python3 scripts/first_oracle_packet_assistant.py --front shadbala --format markdown --output docs/benchmark/first_shadbala_oracle_packet_assistant.md
+```
+
+该助手不会生成或猜测 JHora/PyJHora 真值，只会列出当前 packet 还缺哪些字段、可用外部来源、apply 命令和 validator 命令。
+
+如需先看三条硬闭环 front 的统一排序入口，而不是分别运行三个助手：
+
+```bash
+python3 scripts/oracle_packet_assistant_index.py \
+  --format markdown \
+  --output docs/benchmark/first_oracle_packet_assistant_index.md
+```
+
+该索引会固定列出 `dasha`、`tajika_sahams`、`shadbala` 三条 front 的首包 case、缺失字段数、operator card 与推荐执行顺序，方便直接判断当前最短闭环路径。
+
+Shadbala 外部绝对值闭环使用独立状态板，专门追踪七曜的六分量与总 Rupa：
+
+```bash
+python3 scripts/shadbala_oracle_closure_status.py \
+  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
+  --format markdown \
+  --output docs/benchmark/shadbala_external_absolute_value_closure_status.md
+```
+
+当前第一优先级是 `external_template_synthetic_north_china_shadbala_raman`。除了同一 oracle 行里的 `target.moon_sidereal_longitude_deg`，还必须填写 Sun/Moon/Mars/Mercury/Jupiter/Venus/Saturn 的 `sthana`、`dig`、`kala`、`chesta`、`naisargika`、`drik`、`total_rupa`；验证器会检查分量和总分，不允许用一个全局倍率把本地输出硬缩放成外部值。
+
+Tajika/Sahams 年运系统使用独立的外部 oracle 队列，专门追踪 Varshaphala、太阳回归、Muntha、Year Lord、Mudda Dasha、Sahams 与 Tajika Yogas 的外部验证状态：
+
+```bash
+python3 scripts/tajika_annual_oracle_queue.py \
+  --oracle-file references/oracle/tajika_annual_oracle_cases.json \
+  --format markdown
+```
+
+公开年运看板可这样生成：
+
+```bash
+python3 scripts/tajika_annual_benchmark_dashboard.py \
+  --oracle-file references/oracle/tajika_annual_oracle_cases.json \
+  --format markdown \
+  --output docs/benchmark/tajika_sahams_annual_benchmark_dashboard.md
+```
+
+当前 Tajika/Sahams 看板固定输出 `can_claim_tajika_sahams_closure: false`：本地 skill 已有年运计算与解释骨架，但太阳回归精确时刻、Varsha Lagna、Muntha、Mudda Dasha、Punya/Rajya/Vivah Saham 和 Tajika Yogas 仍需 JHora/PyJHora/书例级外部证据后，才能宣称年运闭环。
+
+年运第一条最短闭环状态板：
+
+```bash
+python3 scripts/tajika_annual_closure_status.py \
+  --oracle-file references/oracle/tajika_annual_oracle_cases.json \
+  --format markdown \
+  --output docs/benchmark/tajika_sahams_annual_closure_status.md
+```
+
+如需导出可填写的年运证据包：
+
+```bash
+python3 scripts/tajika_annual_oracle_queue.py \
+  --oracle-file references/oracle/tajika_annual_oracle_cases.json \
+  --write-packet-dir references/oracle/artifacts/pending_packets \
+  --format json
+```
+
+填完 `external_template_steve_jobs_varshaphala_1984_lahiri.json` 后，可合并回年运 oracle：
+
+```bash
+python3 scripts/tajika_annual_oracle_queue.py \
+  --oracle-file references/oracle/tajika_annual_oracle_cases.json \
+  --apply-packet references/oracle/artifacts/pending_packets/external_template_steve_jobs_varshaphala_1984_lahiri.json \
+  --format json
+```
+
+`full-reading` 也会输出 `ai_prompt_pack`：这是给网页/app、skill 或后端 AI 代理使用的结构化 Prompt/RAG 上下文包。它不会硬编码断语，而是携带 D1/D9/Dasha/Shadbala/Ashtakavarga 的证据快照、推荐检索文档和边界提示，要求大模型基于计算证据交叉验证，避免单一配置下结论。