batchlens-bio 0.1.0__tar.gz

batchlens_bio-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.DS_Store
+artifacts/

batchlens_bio-0.1.0/ARCHITECTURE_DRAFT.md

@@ -0,0 +1,108 @@
+# BatchLens — architecture draft
+
+> 2026-09-12 状态更新：用户已授权完成首个项目并创建/上传仓库；受限 MVP 已实现，本地验证通过，远程发布待认证。以下保留规划背景；当前行为以 README、docs/input-schema.md、docs/methods.md 和 docs/decisions.md 为准。外部 G0/G1 验证并未完成。
+
+2026-09-12；架构与实现对照。以 [PRODUCT_SPEC.md](PRODUCT_SPEC.md) 的 metadata-only v0.1.0 为边界。
+
+## 1. 系统结构
+
+```text
+CSV/TSV samples + YAML design
+       + optional observations / assay links
+  → safe loaders → typed metadata validation
+  → unit/relationship audit → descriptive coverage
+  → supported-design gate → encoded X + explicit contrasts
+  → linear algebra diagnostics → versioned findings
+  → result.json / tables / offline report.html / manifest.json
+```
+
+没有网络服务、数据库、LLM、表达矩阵分析或 integration backend。加载、规则、计算、报告分层；HTML 只消费结构化结果，不能另做一遍科学计算。
+
+## 2. 技术选择与取舍
+
+| 部分 | 首版选择 | 理由 / 验证事项 |
+|---|---|---|
+| Runtime | Python 3.12–3.13 | 与当前 Python 组学生态衔接；只承诺测试过的平台 |
+| CLI | 标准库 argparse | 命令少，无需额外 CLI framework |
+| 表格 | pandas | 显式 dtype 读取、连接和覆盖表；不得把 ID 推断成数字 |
+| 线性代数 | NumPy（SVD；无 SciPy 运行依赖） | SVD rank/null space；成熟实现，重点测诊断契约 |
+| Schema/config | Pydantic v2 + PyYAML safe loader | 严格类型、未知字段拒绝、JSON schema；禁止执行 YAML 标签 |
+| Formula | 声明式 additive terms 自行组装哑变量 | 不开放 Python/R 表达式求值；只做有限编码，不新造统计模型框架 |
+| 报告 | Jinja2 + 少量内嵌 CSS/SVG | 离线单文件 HTML；无需 JS/CDN 或浏览器服务 |
+| Build | pyproject.toml + Hatchling | wheel/sdist；CI 从制品安装，实际解析依赖后确定范围 |
+| QA | pytest、Ruff、mypy、build、twine check | 科学反例优先；格式检查不替代数值与流程测试 |
+
+依赖版本在实现门后做 resolver/安装验证再落定，不能把调研时 latest 全部直接锁死。开发环境保存精确锁文件；库依赖给经测试的兼容区间。首版不依赖 scIB/Scanpy/AnnData，所以也不承诺它们的计算能力。
+
+## 3. 领域对象和粒度
+
+`StudySpec`：schema_version、design_mode、sample_id/unit_id 列名、变量 role/type/reference、target、adjust_for、contrasts、可选表映射。
+
+`SampleTable`：一行一个 sample。`UnitRegistry`：用户声明的实验单位及取样关系。`AssayLinks`：sample ↔ assay，可多对多；slide、section、run 是显式属性/实体，不强加普遍成立的 donor→sample→library→slide 单链。`ObservationTable`：cell/spot 标识及 sample 外键，仅覆盖检查。
+
+需要区分三种数：表行数、distinct sample 数、distinct experimental unit 数。多个 technical replicates 不能增加最后一种。相同 unit 在配对的两个 target 水平出现是设计信息，不是错误；同一个 unit 重复切片也不是多个独立人。
+
+v0.1.0 数值分析粒度：
+
+- `independent`：所选样本中每个 unit 恰一行，target 为分类变量。
+- `paired`：恰两个 target 水平，每个 unit 每水平恰一行，显式 unit fixed block；重复取样的协方差/检验不在本工具中拟合。
+- 不满足上述结构仍生成层级和覆盖 findings，contrast 为 `NOT_ASSESSED`。不自动挑一张切片、不平均技术重复、不把 unit 自动插入 independent 模型。
+- 样本跨多个 batch：链接表保留全部关系；若无法给所声明 sample-level 模型一个唯一 batch 值，数值阶段 `NOT_ASSESSED`。未来在真实需求证实后支持其他分析粒度；首版不可取多数 batch 伪造简单设计。
+
+这样可以识别真实复杂性，同时避免首版变成任意重复测量模型引擎。
+
+## 4. 设计矩阵与 contrast 的算法契约
+
+固定截距；分类变量按显式 reference 作 treatment coding；数值协变量显式声明并记录中心/尺度处理。首版目标是一个分类变量的水平差，加性调整可含多个分类或数值协变量；不支持交互、随机效应、样条、任意公式函数。paired 模式加 unit block，但仍检测 batch 与 unit 等列依赖。
+
+设 `X` 为 n×p 设计矩阵。SVD 给 rank r 和列依赖；默认绝对奇异值阈值 `eps * max(n,p) * s_max`，输出实际阈值、dtype 和 singular values。近奇异结果单独标 numerical sensitivity，不能伪装成完全混杂。连续变量尺度与条件数必须一同解释。
+
+目标 `cᵀβ` 可估计当且仅当 c 在 X 的行空间内，即对 `Null(X)` 中所有 v 有 `cᵀv=0`。用 SVD row-space projector 的残差 `||c - P_row c||₂ / max(1,||c||₂)` 与记录的数值容差判断（首版拟定 1e-10，并以尺度/奇异边界反例验证）。不直接用某次广义逆输出的 β 值当“估计”。
+
+普通 pairwise contrast：从同一 nuisance profile 的 target 两个水平编码行之差生成 c；加性模型保证 nuisance 抵消，仍记录比较方向与编码。若水平不存在、目标恒定或配置引用错误，输出输入错误。多 contrast 逐一判断。设计矩阵秩亏可能只影响 nuisance；**不能把所有比较一律判失败**。
+
+秩亏时给具体列依赖、相关样本组合和受影响 contrast；可估计时也显示模型的加性假设。残差自由度 `n-r` 是设计行层面的诊断，不是 biological replication 或 power。
+
+描述性覆盖：各 target×batch 的 sample 数和 distinct-unit 数、空组合、unit 与 batch/target 的关系。Cramér's V 可作为后续选项；首版不需要依赖一个“混杂分数”才能完成任务，也不套用通用 0.8 红线。
+
+## 5. 规则契约
+
+| Rule ID | 触发 / 证据 | 结论 |
+|---|---|---|
+| BL-META-001 | 必需字段缺失、主键重复冲突、外键悬空 | validation error；定位行/列 |
+| BL-UNIT-001 | 同一 unit 多个 sample/技术观测 | 展示重复结构；是否不支持由 design_mode 决定，不自动认定违规 |
+| BL-UNIT-002 | 某 target 水平 distinct unit <2 | 缺乏组内生物学重复 warning；不作功效推断 |
+| BL-COVER-001 | 指定 target×batch 组合缺失 | coverage warning；单独不等于不可估计 |
+| BL-DESIGN-001 | rank(X)<p | 展示依赖；严重性由受影响目标与数值证据决定 |
+| BL-CONTRAST-001 | c 不属于 row(X) | critical / NON_ESTIMABLE，只针对声明比较 |
+| BL-SUPPORT-001 | 输入设计超出支持粒度/语法 | warning / NOT_ASSESSED，返回已完成的描述结果 |
+| BL-NUMERIC-001 | 数值边界或极端尺度 | warning，解释对容差的敏感性，保留诊断量 |
+
+每项 finding 包含 `rule_id, rule_version, severity, scope, message, evidence_refs, limitations, suggested_next_step`。原始 ID 到共享别名的映射不随 report 默认导出。所有来自用户的字符串 HTML escape。
+
+## 6. 输出契约与可复现性
+
+`result.json` 含 schema/tool/ruleset versions、run_status、declared_design、counts、matrix_diagnostics、contrasts、findings、not_assessed。`tables/` 导出覆盖、编码、依赖证据；`manifest.json` 记录内容哈希、依赖版本、配置与运行时间。
+
+核心 result 的排序固定，时间戳和绝对路径不进入确定性核心。输入哈希同时记录 raw bytes hash 与规范化 metadata hash，区分换行/排序变化和语义变化。对等数据行顺序不应改变科学结果。HTML 与 JSON 共用同一结果对象。
+
+目标目录须不存在，父目录须存在；不提供递归清理/默认覆盖。用同文件系统临时输出目录，文件写完后排他创建目标目录并搬入文件，最后写 COMPLETE；这不是原子目录替换；失败保留可定位的临时产物并清楚说明，不能批量删除。所有删除严格遵守用户一次一个明确文件路径的规则。
+
+## 7. 当前仓库结构
+
+```text
+batchlens-bio/
+  PRODUCT_SPEC.md  COMPETITOR_ANALYSIS.md  ARCHITECTURE_DRAFT.md  ROADMAP.md
+  README.md  LICENSE  CITATION.cff  CHANGELOG.md  CONTRIBUTING.md
+  pyproject.toml  uv.lock
+  src/batchlens/
+    __init__.py  __main__.py  cli.py  config.py
+    metadata.py  design.py  audit.py  reporting.py
+    resources/report.html.j2  resources/demo/
+  tests/test_science.py  tests/test_inputs.py  tests/test_cli.py
+  docs/  examples/public_spatiallibd.py
+  scripts/package_smoke.py  scripts/verify_r_oracle.R
+  .github/workflows/ci.yml  release.yml  pypi.yml
+```
+
+Core 不依赖 portfolio 其他项目；dataset 与模板须纳入 wheel/sdist 的 package data。未来 adapter 只能经已稳定的 metadata/result 接口接入，不在首版设计抽象 plugin SDK。

batchlens_bio-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 — 2026-09-12
+
+- Metadata-only CLI with strict sample/design/optional observation and assay validation.
+- Experimental-unit counts, target/batch coverage, independent and simple paired support checks.
+- Explicit contrast estimability with SVD diagnostics; unsupported structures remain NOT_ASSESSED.
+- Offline HTML, versioned JSON, tables, input/output hashes and completion marker.
+- Seven packaged synthetic demos and an opt-in public spatial metadata example.
+- Scientific regression fixtures, independent R oracle, clean-install smoke checks and release workflows.
+
+Exploratory alpha: external user validation and independent scientific review remain pending. No expression correction, causal inference or power guarantee. The GitHub release records publication assets and execution evidence; PyPI publication is tracked separately.

batchlens_bio-0.1.0/CITATION.cff

@@ -0,0 +1,10 @@
+cff-version: 1.2.0
+message: "Cite the software version and the statistical methods relevant to your analysis."
+title: "BatchLens Bio: experimental-design and batch-confounding audits"
+type: software
+authors:
+  - name: "BatchLens contributors"
+version: 0.1.0
+license: MIT
+abstract: "Metadata-only audits of experimental units, batch coverage and additive-model contrast estimability."
+repository-code: "https://github.com/guatou904/batchlens-bio"

batchlens_bio-0.1.0/CLI_DESIGN.md

@@ -0,0 +1,94 @@
+# BatchLens — CLI design
+
+> 2026-09-12 状态更新：用户已授权完成首个项目并创建/上传仓库；受限 MVP 已实现，本地验证通过，远程发布待认证。以下保留规划背景；当前行为以 README、docs/input-schema.md、docs/methods.md 和 docs/decisions.md 为准。外部 G0/G1 验证并未完成。
+
+2026-09-12；validate / audit / demo 已实现。命令行输入路径相对调用目录解析；设计 YAML 不包含输入文件路径。
+
+## 命令面
+
+```sh
+batchlens --version
+batchlens validate --samples samples.tsv --design design.yaml
+batchlens audit --samples samples.tsv --design design.yaml --out audit-001
+batchlens audit --samples samples.tsv --design design.yaml --observations cells.tsv --assays assay-links.tsv --out audit-002
+batchlens demo --case confounded-time --out demo-confounded
+batchlens demo --case balanced --out demo-balanced
+```
+
+只保留 validate / audit / demo；不加入 integrate、correct、recommend-method、auto-fix。demo 运行随包附带的 synthetic metadata，并走与 audit 相同的路径。正常输出摘要到 stdout，进度和错误到 stderr；主要机器接口是输出目录中的 JSON，避免终端文本成为 API。
+
+## 样本与配置示例
+
+以下独立设计有四个独立实验单位，D0/D7 与 run 完全混杂；数字仅为说明契约的 synthetic 示例。
+
+```text
+sample_id  unit_id  time  run
+s1         u1       D0    A
+s2         u2       D0    A
+s3         u3       D7    B
+s4         u4       D7    B
+```
+
+实际输入须为 CSV 或制表符分隔 TSV；上表的对齐空格不是文件分隔约定。
+
+```yaml
+schema_version: "1.0"
+design_mode: independent
+sample_id: sample_id
+unit_id: unit_id
+variables:
+  time:
+    role: target
+    type: categorical
+    levels: [D0, D7]
+    reference: D0
+  run:
+    role: batch
+    type: categorical
+    levels: [A, B]
+    reference: A
+target: time
+adjust_for: [run]
+contrasts:
+  - id: D7_vs_D0
+    numerator: D7
+    denominator: D0
+```
+
+固定截距隐含于受限加性模型，报告明确展示 `1 + time + run`。role 为 batch 的变量必须出现在 adjust_for；不得省略已声明技术因素而悄悄发“通过”。用户可以明确更改其声明，但报告必须反映改后的目标和限制。
+
+paired 模式：同一 unit 在两个 target 水平各一行，`design_mode: paired`；unit block 自动作为该模式的公开契约加入并显示。缺配对、每个 unit×target 多个样本、多个配对因子仅给描述检查与 NOT_ASSESSED，不自动删除样本。
+
+## 终端摘要草图
+
+```text
+BatchLens audit completed
+Experimental units: 4; samples: 4
+Declared model: 1 + time + run
+D7_vs_D0: NON_ESTIMABLE
+Evidence: time[D7] and run[B] are identical design columns.
+Scope: the requested time effect cannot be separated from run in this model.
+Report: demo-confounded/report.html
+JSON: demo-confounded/result.json
+```
+
+用语限定在“指定模型的比较”；不说“数据废了”，也不建议直接删除 run 后继续声称控制了批次。
+
+## 错误和 CI 契约
+
+`--fail-on critical|warning|none`，audit/demo 默认 `critical`；配置错误总失败。报告完成后才根据科学 finding 决定退出码，使 CI 失败仍能保留 artifact。
+
+| 退出码 | 含义 |
+|---|---|
+| 0 | 执行完成，没有达到 --fail-on 的 finding；不代表科学有效 |
+| 1 | 非预期内部执行失败；错误不应伪装成 finding |
+| 2 | 参数、输入、schema 或输出路径错误 |
+| 3 | 报告成功生成，但至少一项达到 --fail-on 阈值 |
+
+NON_ESTIMABLE 对应 critical；NOT_ASSESSED 对应 warning。严格流水线使用 `--fail-on warning`，避免把未评估误当通过。`--fail-on none` 只改变退出行为，不删除 findings。validate 成功也不表示比较可估计。
+
+`--out` 已存在即拒绝（包括空目录），要求父目录已存在；不设计 `--force` 自动删除旧结果。输入路径和异常中的敏感值控制在本地错误日志；共享 HTML 不含默认绝对路径。
+
+## 文档与兼容性
+
+CLI 示例是发布 DoD 的可执行验收脚本来源；`--help` 包含 required columns、退出码、输出文件和限制链接。配置 schema 与输出 schema 独立版本化；新增字段可兼容，改变含义必须记录迁移。首版错误提示英文以便 GitHub issue 复现，提供中文解释指南；不把国际化框架加入 MVP。

batchlens_bio-0.1.0/COMPETITOR_ANALYSIS.md

@@ -0,0 +1,79 @@
+# BatchLens — competitor analysis
+
+调研日期：2026-09-11。方法：GitHub README/官方文档、PyPI JSON 元数据、Bioconductor vignette 与原始论文。属于 desk research；没有安装跑分、系统功能穷举或用户访谈。未在文档看到某项功能 ≠ 对方没有该功能。活跃度、版本是时间快照，不拿 Stars 代替需求。
+
+## 1. 结论先行
+
+BatchLens 不应让研究者放弃 scIB/kBET/LISI。它应在整合和下游比较之前审计实验设计。真正需要比较的最近替代品是 **BatchQC + ExploreModelMatrix + 团队自己的 sample-sheet notebook**。如果相对这三者只有 Python CLI 和好看的 HTML，独立项目理由仍然偏弱。
+
+可辩护的方向是领域专用产品交付：明确实验单位与技术观测的区别，把用户的具体比较、模型限制、层级冲突和机器可读 finding 连在一起。方法学来自已有统计学；价值需要真实任务验证，不能用“首个”宣传。
+
+## 2. GitHub / ecosystem 比较
+
+| 工具 / 一手来源 | 已确认能力 | 与 BatchLens 的关系 / 取舍 |
+|---|---|---|
+| [scIB](https://github.com/theislab/scib) / [指标 API](https://scib.readthedocs.io/en/latest/api/scib.metrics.metrics.html) | 整合 benchmark，包括 batch removal 和 bio-conservation；接收 batch/label 和整合前后数据 | 保留为整合评价方案；不重写其指标，不声称只看混合 |
+| [scib-metrics](https://github.com/YosefLab/scib-metrics) / [Benchmarker](https://scib-metrics.readthedocs.io/en/latest/generated/scib_metrics.benchmark.Benchmarker.html) | Python-only 加速指标与多 embedding benchmark；官方提醒数值不能直接与原 scIB 混比 | “不用 R”“自动汇总指标”已不是差异点；未来如接入必须记录实现、版本和参数 |
+| [kBET](https://github.com/theislab/kBET) | 邻域 batch 比例检验；官方也讨论分群计算、抽样、重复运行与输出统计 | 不能称其无局部检查或无不确定性；它不把独立实验单位和目标 contrast 作为核心产品输入 |
+| [LISI](https://github.com/immunogenomics/LISI) | 局部标签多样性指标，可对 batch/生物标签计算 | 评价局部表示结构；不能从混合指标恢复完全混杂设计的缺失信息 |
+| [CellMixS](https://github.com/almutlue/CellMixS) / [论文](https://pmc.ncbi.nlm.nih.gov/articles/PMC7994321/) | 单细胞 batch bias 探索、细胞级 mixing 和整合前后结构比较、可视化 | “局部诊断”“细胞分层”已有先例；表达层诊断不应进入首版竞争 |
+| [BatchQC](https://github.com/wejlab/BatchQC) / [vignette](https://bioconductor.org/packages/release/bioc/vignettes/BatchQC/inst/doc/BatchQC_Intro.html) | 实验设计展示、confounding statistics、表达诊断和校正 | 最直接竞争者之一；不能宣称现有工具不检查混杂。要实测专用层级/contrast 报告能否节省任务时间 |
+| [ExploreModelMatrix](https://github.com/csoneson/ExploreModelMatrix) / [vignette](https://csoneson.github.io/ExploreModelMatrix/articles/ExploreModelMatrix.html) | sample table + formula，展示 rank、系数解释、协同出现和相关结构；支持静态图 | 最强设计解释替代品；BatchLens 的统计功能不能被称为创新，须证明领域输入契约与 headless findings 的价值 |
+| [DESeq2](https://bioconductor.org/packages/release/bioc/vignettes/DESeq2/inst/doc/DESeq2.html#model-matrix-not-full-rank) | 明确处理设计矩阵不满秩，解释完全混杂、嵌套与缺失水平 | 已有成熟错误检查与教育材料；BatchLens 争取更早、跨工具、无需 expression 的交付流程 |
+| [MultiQC](https://github.com/MultiQC/MultiQC) | 聚合多样本生信输出为报告 | 可作为后续报告入口；不为“统一 HTML”另建大平台 |
+| 普通 R/Python notebook | 交叉表、rank、人工解释可低成本实现 | 成本最低的替代品；必须和维护一个模板相比，而不只和手工 Excel 相比 |
+
+上述“产品输入/流程差别”是文档范围内的观察，不是竞品不可实现的证明。决定前对前三个最近替代方案按相同案例实际试用。
+
+## 3. 为什么还需要 BatchLens：具体对照
+
+| 科研问题 | 适用现有工具 | BatchLens 候选增量 |
+|---|---|---|
+| Harmony/scVI 等表示的批次混合和生物保留怎样？ | scIB / scib-metrics | 首版不回答；指向现有工具 |
+| time 与 processing run 完全重合，D7−D0 能在指定模型下估计吗？ | ExploreModelMatrix / DESeq2 设计检查 | 在读入 sample sheet 时返回 contrast 结论、依赖证据和稳定 finding ID |
+| 3 donors、12 sections、5 万 spots，我有多少独立重复？ | 人工 metadata 检查 / 定制脚本 | 在声明的实验单位下显示层级计数，避免把技术重复当生物学 n |
+| 一个无关协变量重复编码，是否所有比较都不可估计？ | 线性模型/contrast 专业工具 | 对每个 contrast 检查，不用 rank 单一红灯误导研究者 |
+| 分析流水线需要可存档、可 diff 的设计限制记录 | 自写 notebook/report / BatchQC | JSON/TSV + rule version + input hash + exit policy；是否值得独立包待验证 |
+
+不够强的卖点：Python 重写、自动出图、一键运行、LLM 解释、多指标总分。足够值得验证的组合：领域层级正确、指定比较正确、诊断证据可追溯、失败可机器识别。
+
+## 4. PyPI 与安装生态快照
+
+以下为当日直接请求 `https://pypi.org/pypi/<name>/json` 的返回值；只是声明兼容性，未经安装测试。
+
+| 包 | 版本 | Requires-Python | 对规划的影响 |
+|---|---|---|---|
+| [scib](https://pypi.org/project/scib/) | 1.1.7 | >=3.9 | 不把整个 benchmark 栈拉入 metadata 工具 |
+| [scib-metrics](https://pypi.org/project/scib-metrics/) | 0.6.1 | >=3.12 | 如果未来接入，需要单独验证版本/平台 |
+| [anndata](https://pypi.org/project/anndata/) | 0.13.3.post0 | >=3.12 | h5ad 适配以后再加；首版可直接导出 obs metadata |
+| [scanpy](https://pypi.org/project/scanpy/) | 1.12.4 | >=3.12 | 无需为样本表体检安装完整分析环境 |
+| [multiqc](https://pypi.org/project/multiqc/) | 1.35 | !=3.14.1,>=3.9 | 可以文件集成，暂不做插件 |
+| [pydeseq2](https://pypi.org/project/pydeseq2/) | 0.5.4 | >=3.11 | 下游 DE 仍交给专用工具 |
+
+技术选择据此采用 Python 3.12–3.13 的小依赖核心（尚待 clean-install 验证）。没有 R/JAX/GPU 的首版来自任务收窄，不等于同功能比 scIB 更轻。
+
+### GitHub 活跃度核验
+
+当日直接查询公开 GitHub REST `repos/{owner}/{repo}`。`pushed_at` 可能包含任意分支活动，不等于正式 release 或维护质量；没有据此估计用户数。
+
+| 仓库 | 默认分支 | archived | pushed_at（UTC） |
+|---|---|---|---|
+| theislab/scib | main | false | 2026-04-27 20:13:28 |
+| YosefLab/scib-metrics | main | false | 2026-09-10 07:58:54 |
+| wejlab/BatchQC | devel | false | 2026-08-28 19:16:48 |
+| csoneson/ExploreModelMatrix | devel | false | 2026-04-28 17:58:45 |
+| almutlue/CellMixS | devel | false | 2024-09-04 10:32:12 |
+
+README、开发分支与 Bioconductor release 文档可能存在版本差异，实际对照要固定具体版本。GitHub license 字段的 `NOASSERTION`/null 不是无许可证结论，需查看发行版本 LICENSE/DESCRIPTION。
+
+## 5. 名称与许可风险
+
+PyPI `batchlens`、`batchlens-bio` 在本次 JSON 查询都返回 HTTP 404；不代表名字已保留、未来一定可注册，或没有其他品牌冲突。检索发现 [BatchLens 云系统批作业可视化论文（2021）](https://arxiv.org/abs/2112.15300)，因此建议对外使用 **BatchLens Bio** 作为候选消歧名称、发行名候选 `batchlens-bio`，产品规划名称仍保留用户指定的 BatchLens。发布前再核验，不在本阶段自行注册。
+
+依赖优先使用公开 API，避免复制现有工具代码。scIB、scib-metrics、kBET、LISI 等许可证不同；选定实际依赖/引用代码后记录许可证和 attribution。当前只提出许可证评估任务，不作法律结论。
+
+## 6. 证据缺口与决定
+
+还缺：真实 sample/time/batch 案例的最小元数据；用户对独立 CLI 的偏好；现有工具同任务耗时；对诊断措辞的统计评审；多对多技术观测是否为首版必要输入。没有证明首创、市场规模或真实采用。
+
+Decision：继续非代码验证；不启动产品实现。若差异主要可由一个通用模板覆盖，降为 biomed-agent-recipes 的设计体检 recipe；若层级验证与机器接口在多次真实任务中有明确增量，再独立实现。见 [VALIDATION_PLAN.md](VALIDATION_PLAN.md)。

batchlens_bio-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing
+
+Keep changes within metadata-only experimental-design audits. Show a real task and independently checkable example before adding formats/models. Do not add batch correction or unsupported causal conclusions.
+
+Use Python 3.12/3.13 and `uv sync --locked`. Run Ruff, mypy, pytest; build wheel/sdist and test installation outside the checkout. On macOS, if hidden-file flags prevent loading editable `.pth` files, use `uv sync --no-editable` and `uv run --no-editable ...`; do not alter global Python behavior.
+
+Scientific changes need hand-computable counterexamples and independent expected results. The R oracle is optional locally and required in its CI job. Never silently drop samples or adjust models. Record ambiguous/unsupported inputs.
+
+Issue reports should include versions, command, exit code and minimal synthetic reproducer, without patient IDs, credentials, private paths or unpublished data. Update schema/CLI migration notes, rule IDs and evidence pointers. Generated `docs/design.schema.json` must match the configuration model.
+
+No recursive cleanup commands. Existing outputs are never overwritten. Before publishing, follow the release checklist and distinguish executed evidence from pending user validation, scientific review, remote CI and PyPI publication.

batchlens_bio-0.1.0/DEMO_DATA_STRATEGY.md

@@ -0,0 +1,50 @@
+# BatchLens — synthetic/public demo strategy
+
+> 2026-09-12 状态更新：用户已授权完成首个项目并创建/上传仓库；受限 MVP 已实现，本地验证通过，远程发布待认证。以下保留规划背景；当前行为以 README、docs/input-schema.md、docs/methods.md 和 docs/decisions.md 为准。外部 G0/G1 验证并未完成。
+
+2026-09-11；本文件定义数据计划，未生成或下载数据。首版体检不需要 expression 矩阵，demo 应围绕 metadata 的可辨识性和重复层级，而非漂亮 UMAP。
+
+## 1. 默认 synthetic demo（随包、离线、可重复）
+
+| case | 人为构造 | 期望结果 |
+|---|---|---|
+| balanced | target×run 交叉、有独立 units | ESTIMABLE；仍说明不保证 power/causality |
+| confounded-time | D0 仅 A、D7 仅 B | NON_ESTIMABLE，有确切列依赖 |
+| partial-overlap | 三个交叉组合，第四个空缺 | 加性模型 ESTIMABLE + coverage warning |
+| redundant-nuisance | batch 与 machine 重复，target 完全交叉 | rank deficient，但 target ESTIMABLE |
+| spatial-replicates | 3 units、12 sections、很多 spots | 正确计数；复杂 sample-level 推断 NOT_ASSESSED |
+| paired | 每个 unit 在两水平各一行 | 正确 block/contrast；缺失配对变体 NOT_ASSESSED |
+| metadata-errors | 冲突 sample、未知外键、缺失 unit | validate 失败，清楚定位错误 |
+| mixed-assays | 一个 sample 跨 run / 一个 library 混多个 sample | 保留映射；不能自动把 batch 压成一个值 |
+
+默认规模小于 100 sample，覆盖表可肉眼检查。随机数据如需生成采用固定 seed 并记录生成器版本；用于验收的设计表与期望标签固定，不靠随机碰巧制造混杂。测试和 demo 共用科学 fixtures，但用户 demo 必须走真实 CLI。发行包内置数据总量目标 <1 MB。
+
+synthetic 标签必须出现在文件说明和报告页；不能把人为删组合后的数据叫真实发现。先发布最核心 balanced/confounded-time 两个可运行 demo，其余作为科学 fixtures；完整演示清单由 Release 检查覆盖。
+
+## 2. 公开数据候选及状态
+
+| 来源 | 可演示价值 | 已核实 / 尚待核实 |
+|---|---|---|
+| [spatialLIBD 官方仓库](https://github.com/LieberInstitute/spatialLIBD) | subject、section、spot 不同层级；官方 study design 描述 3 subjects 与相邻切片重复 | 已核实项目及设计说明；未提取 metadata，数据许可/再分发条件、精确字段和版本尚待核验 |
+| [10x Human Breast Cancer Visium](https://www.10xgenomics.com/datasets/human-breast-cancer-visium-fresh-frozen-whole-transcriptome-1-standard) | 空间 assay 元数据格式和有限 biological replication 的教学 | 已核实官方数据页；不当作多 donor disease/control benchmark；字段与下载条款未审计 |
+| [GSE96583 候选](https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE96583) | 单细胞多样本设计候选，待重核后决定 | 本次 GEO 页面被浏览器验证拦截；不据此断言确切 donor/run/condition 映射或许可 |
+
+首选推进 spatialLIBD 的 metadata 教学案例；若不足以演示 target 对比，明确展示层级检查，不编造 condition/batch。scRNA 公共案例保持候选，不为凑两个模态虚构批次标签。GEO 可公开访问不自动等于所有附件允许任意再分发。
+
+## 3. 获取与出处契约
+
+公开数据作为可选、显式下载路径，不在安装或离线 demo 中自动联网。每个正式案例记录：accession/DOI、原始 URL、提取日期、上游版本/文件名、SHA256、许可/使用条款、字段映射、过滤规则、哪些标签来自原文、哪些人为构造。缺失 run 用 unknown 表达，不能拿 donor ID 冒充 run。
+
+能再分发且体积很小的 sample metadata 可以随案例发布；否则只提供用户自行获取和提取的步骤。表达矩阵、组织切片图和患者信息不随 package 分发。合成的对照删减必须单独标记 `derived-synthetic-scenario`，保持原始设计可查。
+
+## 4. 公开数据不是统计 gold standard
+
+真实数据没有通用“无 batch effect”标签；public demo 证明输入/输出与出处可复现，不证明诊断灵敏度。科学正确性的主证据来自人工可计算反例和独立 oracle。不能以一张 UMAP 作为结论真值。
+
+## 5. v0.1.0 验收
+
+- [ ] 离线 synthetic demo 从已安装发行包运行，输出完整报告。
+- [ ] 至少一个来源/条款已核验的 public metadata 教学案例可按说明复现；如果不能再分发，提供独立获取说明与固定哈希。
+- [ ] public 核心字段缺失明确说明，报告不捏造实验设计。
+- [ ] synthetic 预期结论与实际输出逐项相符，HTML 可读。
+- [ ] CI 默认不依赖外站；可选公开数据验收单独记录，外站失败不伪造成功。

batchlens_bio-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BatchLens contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

batchlens_bio-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: batchlens-bio
+Version: 0.1.0
+Summary: Experimental-design and batch-confounding audits for single-cell and spatial metadata
+Project-URL: Repository, https://github.com/guatou904/batchlens-bio
+Project-URL: Issues, https://github.com/guatou904/batchlens-bio/issues
+Project-URL: Documentation, https://github.com/guatou904/batchlens-bio#readme
+Project-URL: Changelog, https://github.com/guatou904/batchlens-bio/blob/main/CHANGELOG.md
+Author: BatchLens contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: confounding,experimental-design,single-cell,spatial-transcriptomics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: <3.14,>=3.12
+Requires-Dist: jinja2<4,>=3.1.5
+Requires-Dist: numpy<3,>=2.0
+Requires-Dist: pandas<4,>=2.2
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: pyyaml<7,>=6.0.2
+Description-Content-Type: text/markdown
+
+# BatchLens Bio
+
+**Experimental-design and batch-confounding audits for single-cell and spatial metadata.**
+
+BatchLens checks declared experimental units, target-by-batch coverage and whether a specific contrast is estimable under an additive fixed-effects model. It produces an offline HTML report, JSON findings and auditable tables. It never fits or corrects expression data.
+
+**Status:** exploratory alpha. External user validation and independent scientific review are not yet completed. See the [release page](https://github.com/guatou904/batchlens-bio/releases) and [validation record](docs/validation-record.md) for publication and test evidence. PyPI distribution is tracked separately.
+
+## Why another tool?
+
+Keep using scIB/kBET/LISI for integration evaluation. Good embedding mixing cannot recover information absent from an experimental design. If D0 samples were processed only in run A and D7 only in run B, `time + run` cannot distinguish the time effect from run.
+
+BatchQC and ExploreModelMatrix already provide valuable confounding/design diagnostics. BatchLens offers a narrowly scoped Python CLI that connects experimental-unit checks, explicit contrasts, machine-readable findings and offline delivery. It is a workflow tool using established linear algebra, not a new statistical method. See [competitor research](COMPETITOR_ANALYSIS.md).
+
+## Install and try
+
+Python 3.12 or 3.13; CI passes on Linux and macOS. Windows is not yet tested or supported. Install from the source repository:
+
+```sh
+git clone https://github.com/guatou904/batchlens-bio.git
+cd batchlens-bio
+python -m venv .venv
+# macOS / Linux
+source .venv/bin/activate
+python -m pip install .
+batchlens demo --case balanced --out demo-balanced
+batchlens demo --case confounded-time --out demo-confounded --fail-on none
+```
+
+Open `demo-confounded/report.html` in your browser. Every demo is synthetic, runs offline and is included in the wheel. The report shows `NON_ESTIMABLE`; `--fail-on none` allows this intentional demonstration to exit successfully without hiding the finding.
+
+![Actual synthetic confounding report](docs/demo-preview.png)
+
+[Downloadable offline report preview](docs/demo.html) · [Reproduce the public spatial example](docs/public-data.md)
+
+Other cases: `partial-overlap`, `redundant-nuisance`, `paired`, `spatial-replicates`, `mixed-assays`. Each output path must be **new** and have an existing parent. Existing files are never overwritten or deleted.
+
+## Your metadata
+
+Prepare a CSV/TSV with one row per sample and a YAML design declaration. IDs are strings; declare the true experimental unit rather than assuming every cell or spot is independent.
+
+```sh
+batchlens validate --samples samples.tsv --design design.yaml
+batchlens audit --samples samples.tsv --design design.yaml --out audit-001
+batchlens audit --samples samples.tsv --design design.yaml \
+  --observations cells.tsv --assays assays.tsv --out audit-002
+```
+
+The [input guide](docs/input-schema.md) specifies columns and includes a complete configuration. Export only metadata from your analysis environment; h5ad, expression matrices and spatial images are not required or read.
+
+## Understand the result
+
+| Contrast status | Meaning |
+|---|---|
+| `ESTIMABLE` | Algebraically estimable under the declared model; **not** a power, biological validity or causality pass |
+| `NON_ESTIMABLE` | The requested contrast cannot be uniquely determined under that model |
+| `NOT_ASSESSED` | Sampling structure is outside the supported independent/paired model; descriptive checks still run |
+
+Rank deficiency does not necessarily invalidate every contrast. Partial target-by-batch overlap is not automatically complete confounding. More cells or technical sections do not create more experimental units. See [methods](docs/methods.md) and [interpretation](docs/interpretation.md).
+
+## Output and automation
+
+- `report.html`: self-contained, no network or JavaScript required.
+- `result.json`: versioned design, findings, contrast results and numerical evidence.
+- `tables/*.tsv`: sample/unit coverage and optional annotation summaries.
+- `manifest.json`: input/output SHA256 hashes, environment and dependency versions.
+- `COMPLETE`: written last; its absence indicates an incomplete bundle.
+
+IDs are replaced with local aliases; labels/design values can still identify people. Review **all** outputs before sharing. No original ID map, absolute input paths or cell-level rows are exported. TSV formula-like labels are prefixed with an apostrophe for spreadsheet safety; JSON preserves original scientific labels.
+
+Exit codes: `0` completed, `1` internal failure, `2` input/output error, `3` findings exceed policy. `--fail-on critical` is the default. Use `--fail-on warning` in strict CI so unsupported models do not pass silently; `--fail-on none` changes only exit behavior. A successful `validate` command does not test estimability.
+
+## Supported scope
+
+Independent: one sample per declared experimental unit. Paired: one sample at each of two target levels per unit, with an explicit unit block. Categorical target; additive categorical/numeric adjustment. Multi-batch samples and more complex repeated sampling produce `NOT_ASSESSED`, never silent aggregation. No interaction terms, mixed-effects inference, power analysis, causal inference, spatial correlation test or batch correction.
+
+Metadata-only audits cannot verify randomization, independence or unmeasured confounding. The study specification is supplied by the analyst. Near-singular designs require numerical review. Current resource guard: at most 100,000 samples and 256 encoded columns; this is a safety limit, not a performance guarantee.
+
+## Development and verification
+
+```sh
+uv sync --locked --no-editable
+uv run --no-editable pytest
+uv run --no-editable ruff check .
+uv run --no-editable mypy
+uv run --no-editable python -m build
+uv run --no-editable twine check dist/*.whl dist/*.tar.gz
+```
+
+The [validation record](docs/validation-record.md) distinguishes executed tests from pending external evidence. R's `model.matrix`/QR supplies an independent oracle for selected scientific fixtures; see `scripts/verify_r_oracle.R`. The CI and release workflows validate tests, package installation outside the source directory, and demo output. Remote CI success is claimed only with a recorded run URL.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), [CITATION.cff](CITATION.cff), [release checklist](RELEASE_CHECKLIST.md) and [CHANGELOG.md](CHANGELOG.md). MIT-licensed code and synthetic examples; public datasets have their own provenance and terms.
+
+Maintainer: [guatou904](https://github.com/guatou904). Report reproducible installation/scientific issues via [GitHub Issues](https://github.com/guatou904/batchlens-bio/issues); use synthetic inputs and include the software version. The next iteration prioritizes fixes and actual user feedback.

batchlens_bio-0.1.0/PRODUCT_SPEC.md

@@ -0,0 +1,88 @@
+# BatchLens — PRODUCT_SPEC
+
+> 2026-09-12 状态更新：用户已授权完成首个项目并创建/上传仓库；受限 MVP 已实现，本地验证通过，远程发布待认证。以下保留规划背景；当前行为以 README、docs/input-schema.md、docs/methods.md 和 docs/decisions.md 为准。外部 G0/G1 验证并未完成。
+
+状态：ACTIVE（主项目）/ 本地发布候选；2026-09-12。用户确认定位：**单细胞/空间组学“实验设计与批次混杂体检工具”**。
+
+## 1. 存在理由
+
+科研人员仍应使用 scIB / kBET / LISI 评估整合结果。BatchLens 要回答它们之外的一个具体问题：**在声明的样本层级、设计模型和生物学比较下，现有实验设计是否能区分目标效应与批次；哪些重复和覆盖不足会限制解释？**
+
+例：每个时间点有一万细胞，但 D0 全在 run A、D7 全在 run B。即使整合后的 batch mixing 很好，`~ time + run` 仍不能单独识别 time 的效应；新增细胞不提供缺失的交叉设计。BatchLens 应直接显示依赖关系、受影响的 contrast 和样本证据，而不是提供“校正成功”分数。这是实验设计结构检查，不是从 metadata 估计实际 batch effect 大小。[DESeq2 的完整混杂示例](https://bioconductor.org/packages/release/bioc/vignettes/DESeq2/inst/doc/DESeq2.html#model-matrix-not-full-rank)
+
+但此问题并非空白市场：BatchQC 有混杂诊断，ExploreModelMatrix 有设计矩阵分析。因此最大差异化是一个待验证的产品组合：**组学观测层级 → 重复单位检查 → 指定 contrast 的可估计性 → 证据化、可进入 CI 的本地报告**。不宣称新统计方法，不宣称竞品无法用脚本完成。完整比较见 [COMPETITOR_ANALYSIS.md](COMPETITOR_ANALYSIS.md)。
+
+## 2. 用户与任务
+
+| 用户 | 触发场景 | 需要的结果 |
+|---|---|---|
+| 单细胞分析者（主要） | 接到跨 donor、time、run 的样本表；准备整合或 pseudobulk DE | 知道指定比较能否在模型中区分 batch，缺少哪些样本信息 |
+| 空间组学分析者（主要） | 多张 slide/section、很多 spots，准备比较疾病或时间点 | 区分 subject 与 section/spot 的重复关系；看清 condition 与 slide 覆盖 |
+| Core facility / 计算合作者 | 接收项目或交付结果 | 可离线共享、带输入版本的体检附件；定位元数据冲突 |
+| 实验设计者（次要） | 上机前审查样本分配表 | 提前看到完全混杂和空组合；补充跨批次对照的讨论依据 |
+
+需求来源：用户亲历 sample/time/batch confounding；外部采用意愿、发生频率、愿意维护独立 CLI 的程度尚未访谈，不虚构 TAM 或用户数。
+
+## 3. 唯一核心工作流
+
+准备 sample metadata 和显式设计声明 → 校验层级/类型/缺失 → 汇总独立实验单位与技术观测 → 构建设计矩阵 → 检查指定 contrast → 阅读 HTML 并保留 JSON/TSV → 决定补 metadata、调整分析问题或寻求统计复核。
+
+报告状态区分：
+
+- `NON_ESTIMABLE`：指定线性 contrast 在声明模型下不可估计，有矩阵证据。
+- `ESTIMABLE`：通过代数检查；不等于有足够功效、无未测混杂或有因果效应。
+- `NOT_ASSESSED`：该模型/层级超出当前支持范围；未指定比较属于配置错误。
+- Finding 严重度为 `info / warning / critical`；输入错误独立为运行错误，不能混为科学结论。
+
+不输出“数据安全”“可以发表”“不存在 batch effect”的绿灯。不能以删除 batch、删除 donor 或整合为自动修复建议；改变模型就改变可解释的对象。
+
+## 4. v0.1.0 MVP 边界
+
+### Must-have
+
+| 编号 | 功能 | 验收条件 |
+|---|---|---|
+| BL-01 | CSV/TSV 样本表 + YAML 设计声明 | 显式指定 ID、变量角色、类型、参考水平；未知字段/错误引用明确报错 |
+| BL-02 | 实验单位与技术重复核对 | 单独统计 subject/experimental unit、sample、可选 library/section；重复行不增加生物学 n |
+| BL-03 | 批次与目标变量覆盖 | 输出原始计数、distinct-unit 计数、空组合、嵌套关系；关联统计只作描述 |
+| BL-04 | 受限加性固定效应设计矩阵 | SVD rank、列名/编码、依赖证据、数值容差；不拟合 expression 模型 |
+| BL-05 | 一个分类 target 的 pairwise contrasts | 每个 contrast 独立判断可估计性；全矩阵秩亏不能直接宣布所有比较无效 |
+| BL-06 | 简单配对设计检查 | 支持一个 unit block 的两水平配对比较；缺配对明确列出，重复测量不按独立样本处理 |
+| BL-07 | 可选 observation metadata CSV/TSV | cell/spot → sample 的关联检查及 cell type/region 覆盖；不读取表达矩阵 |
+| BL-08 | 可选技术观测关联表 | 支持 sample 与 library/slide 的非一一关系，审计 multiplexing/split sample；未支持的分析分辨率标 NOT_ASSESSED |
+| BL-09 | 离线 HTML + JSON + TSV + manifest | Finding 有 ID、规则版本、证据引用、范围、局限和下一步建议；核心输出确定性 |
+| BL-10 | CLI、测试、demo、文档、CI、包和 Release | [Release checklist](RELEASE_CHECKLIST.md) 全通过 |
+
+### 明确不进入 v0.1.0
+
+scIB/kBET/LISI 计算、UMAP/PCA、自动整合/批次校正、DE/DA、功效或样本量计算、因果效应估计、AI 解释、云服务、GUI、Scanpy/Seurat pipeline、原生 h5ad/SpatialData/图像读取、空间自相关检验、混合效应模型/随机效应、交互项/样条/任意 formula 执行、多物种、多组学自动分析。
+
+空间组学的首版承诺仅为 metadata 的设计与重复层级审计。Cell type / region 覆盖是描述性检查，不自动在每个子群拟合模型或生成有效性评分。
+
+## 5. 输入契约
+
+主表一行一个实际 sample（取样单位/一次采样），`sample_id` 唯一；`unit_id` 表示用户声明的实验单位，可为 donor、animal、organoid 或受随机化的其他单位，不能硬编码 donor 永远是独立单位。重复取样允许同一 unit 多行。必须声明 `design_mode: independent | paired`；复杂层级可读入做覆盖检查，但代数推断限支持范围。
+
+必需：sample ID、unit ID、目标变量、至少一个显式声明的 batch 因子、设计中的所有协变量。分类/数值类型必须声明；`time` 可是采样时间，`processing_date` 是技术日期，两者不自动互换。用户显式声明比较，不按列名猜测 condition 或 batch。
+
+可选 observations 表：`observation_id`、`sample_id`、`cell_type` 或 `region`；所有引用须可连接，未知 sample 报错。observations 只影响覆盖表，不改变设计矩阵的行数或 rank。可选 assay links 表记录 `sample_id, assay_id, slide_id/section_id, batch`，多对多关系必须保留；不能随便取首个 batch 合并。
+
+缺失 unit ID 无法保证重复单位，阻止完整 audit；`validate` 给缺失报告。其他必需字段缺失、sample 冲突、未知类别、未声明数据类型不静默填充。技术观测表与主表冲突也不能静默覆盖。
+
+## 6. 输出与体验
+
+首页先显示用户请求的比较、独立单位数、可估计性、最重要的设计限制；再显示样本/批次覆盖表、矩阵证据、未评估事项。避免把技术运行成功显示成科学检查通过。
+
+所有结论都绑定输入 hash、design 配置、规则集版本和支持范围。共享默认使用别名化 ID，不写绝对输入路径，不嵌入 cell 级表；别名化不保证匿名，分类标签等仍需用户检查。运行全本地、无遥测。技术元数据仍可能敏感。
+
+目标体验（待实测）：整理好 metadata 后，首次从安装到打开 demo ≤10 分钟；1000 sample / 50 设计列的核心 audit ≤10 秒、峰值内存 ≤512 MB（记录硬件）；不对百万 cells 的输入导入作无证据性能承诺。
+
+## 7. 科学与产品风险
+
+秩满仅说明指定模型中的参数结构；不验证随机化、测量正确性、协方差模型、统计功效或未测混杂。元数据关联强不证明存在表达批次效应，关联弱不排除批次效应。没有相关统计检验就不输出 p 值。加性假设不自动适用于交互、连续时间趋势或空间相关。
+
+用户提供的重复单位和 formula 可能错误：报告始终复述其声明和条件性结论。首版宁可 `NOT_ASSESSED`，不能制造 certainty。少于 2 个独立单位的组标缺乏组内生物学重复；2 个并不表示充足，工具不发 power pass。
+
+## 8. Go / no-go
+
+初始规划结论（2026-09-11）：存在理由尚需验证。2026-09-12 按用户后续授权进入受限探索性实现；外部证据仍待完成，见 [VALIDATION_PLAN.md](VALIDATION_PLAN.md)。如果已有工具 + 简短模板能同样清晰地完成场景，应优先贡献上游或收入 recipes，而不是硬建独立包。v0.1.0 后也不因预留 roadmap 自动扩张。