feat: Deliver validated initial CIF preparation and workflow guidance

.agents/skills/diffractscout-cif-reference/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: diffractscout-cif-reference
+description: Generate and verify theoretical XRD peak tables and Excel from local CIFs in DiffractScout. Use for CIF reference exports, not experimental fitting or general code edits.
+---
+
+# 本地 CIF 理论峰表
+
+从用户指定的本地 CIF 生成可追溯理论峰表，交付 Excel 与保留来源、设置和完整性信息的结果包。使用现有 `quick-export`、`verify` 和 `inspect`；不另写衍射引擎。
+
+## 输入与选择
+
+- 定位用户指定文件或目录，核对 CIF 身份、有效数据块和原文件哈希。输出使用新目标，与输入目录分离；保留原始 CIF。
+- 使用已授权的辐射条件和扫描范围。仅对普通实验室快速参考、且用户未指定实验条件的请求，可以声明采用 `Cu Ka`（λ=1.5406 Å）、2θ=5–120° 的程序默认值。
+- 同步辐射或与实测谱比较缺少波长/能量时，先完成文件清点，再询问该关键条件。波长为 Å、能量为 keV，二者选择一种；预设与显式覆盖的规则见 [CLI](../../../docs/CLI.md)。
+- 只要峰表时使用 `--no-patterns`；没有合适弹性输入或未请求弹性时使用 `--no-elasticity`。需要谱图或弹性时按请求选择已有选项，不把这些简化参数强加给用户。
+
+## 执行示例
+
+从仓库根目录使用装有依赖的 Python。Windows 已验证系统环境可用 `py -3`；虚拟环境使用其 `Scripts/python.exe`。如下是实验室参考示例，输入、输出和辐射条件按实际请求替换：
+
+```powershell
+py -3 scripts/diffractscout_entry.py quick-export "sample.cif" -o "outputs/sample.xlsx" --source "Cu Ka" --two-theta-min 5 --two-theta-max 120 --no-elasticity --no-patterns
+py -3 scripts/diffractscout_entry.py verify "outputs/sample_bundle"
+py -3 scripts/diffractscout_entry.py inspect "outputs/sample_bundle"
+```
+
+`-o sample.xlsx` 同时产生 `sample_bundle/`。以命令返回的实际路径为准。请求的 `.xlsx` 或对应的 `<stem>_bundle/` 任一已存在时，选择新的输出名称；不要自动覆盖、删除旧结果或更改 manifest 使校验通过。
+
+默认文本输出已包含运行摘要。只有需要机器解析时使用 `--json`；完整导出 JSON 可能含大量中间计算，应保存到结果包外的新日志文件，再读取需要的字段，避免把整个响应塞入上下文。
+
+## 核验与交付
+
+- 查看退出码和逐物相诊断。校验成功只说明包的完整性；仍需检查是否有可分析物相、反射，以及失败或警告的 CIF。错误诊断不能被“Excel 已创建”掩盖。
+- 对照 `provenance.json`、`phase_summary.csv`、`peak_reference.csv` 和工作簿的 `Peaks`、`Diagnostics`，检查输入身份、辐射条件、扫描范围、峰数和单位是否一致。
+- 命名源模式下，`analysis_settings.wavelength_A=null` 表示没有显式波长覆盖；已解析的有效波长从 `phase_summary.csv` 的 `wavelength_A` 读取，不能把设置空值当成未指定辐射条件。
+- 用导出波长与 d 独立检查 Bragg 几何，并检查 `q=2π/d`、`g=1/d`；强度通道、系统消光与弹性方向的含义按 [科学约定](../../../docs/SCIENTIFIC_CONTRACTS.md) 解读。未出现的峰还可能涉及范围、阈值或重叠，不能直接视作物相不存在。
+- `sample.xlsx` 是结果包中工作簿的副本；交付前核对副本与包内 `results.xlsx` 的哈希。需要编辑时另存副本，保留可验证的包内文件。
+- 给出 Excel 和结果包的实际位置、采用的条件、核验结果及具体警告。说明它是 CIF 平均结构的运动学理论参考；实验物相识别、定量结果或机制结论需要各自的实验依据。
+
+完成边界是用户要求的参考文件已经产生并核验。原始输入缺损或关键条件未解决时明确报告缺口，继续完成可独立执行的部分；不把诊断包或空峰表报为完整参考。

.github/pull_request_template.md

@@ -8,19 +8,21 @@ List the files, numerical contracts, data schemas, providers, or user workflows
 
 ## Scientific evidence
 
-Provide analytical checks, independent comparisons, public/synthetic fixtures, units, tolerances, and interpretation of any changed result.
+For changed numerical behavior or scientific contracts, provide analytical
+checks, relevant independent comparisons, public/synthetic fixtures, units,
+tolerances, and interpretation of changed results. Otherwise state that this
+section does not apply.
 
 ## Validation
 
-- [ ] `ruff check src tests scripts`
-- [ ] `python -m compileall -q src tests scripts`
-- [ ] `pytest --cov=diffractscout --cov-fail-under=65`
-- [ ] `diffractscout demo -o outputs/pr_demo`
-- [ ] `diffractscout benchmark -o outputs/pr_benchmark`
-- [ ] `diffractscout verify outputs/pr_demo`
-- [ ] `python scripts/joss_readiness.py --output outputs/pr_readiness` completes in non-strict mode
+List the relevant local checks and results, and explain any skipped check that
+affects confidence in this change. Use [the workflow guide](../docs/AGENT_WORKFLOW.md)
+to choose checks; required CI checks remain the merge gate. Full release and
+JOSS preflights apply when preparing their respective candidates.
+
+- [ ] Checks appropriate to the changed behavior completed and reported
 - [ ] Documentation, validation evidence, and changelog updated when applicable
-- [ ] No API keys, restricted data, build artifacts, or local paths committed
+- [ ] No API keys, restricted data, generated build artifacts, or private local paths committed
 
 ## Compatibility and provenance
 

AGENTS.md

@@ -0,0 +1,42 @@
+# DiffractScout 项目协作约定
+
+本项目是独立的 Python 科研软件仓库：Windows 桌面、CLI 和 API 共用理论衍射与可追溯导出流程。以下是本仓库的具体约定，适用于 Astra 和其他编码 agent。
+
+## 执行与范围
+
+- 用户当前请求和已有授权决定任务范围。修改、修复、构建请求应持续完成调查、实现和适当验证；只有用户要求“只审阅”“先给方案”等时才停在审阅或方案阶段。
+- 已确定在本仓库工作时，直接读取相关文件；上级工作区的 MAP 只在定位项目或变更项目清单时使用。文档按下表选择，不必每次重读整个 README、架构、发布和投稿资料。
+- 先查看工作区改动，保留用户已有工作。只修改与任务相关的内容，不覆盖未提交修改，不原地改写原始实验数据或用户 CIF。
+- 本地检查、派生输出和请求范围内的修复无需逐步确认。缺失信息会实质改变科学正确性或目标时才提问，并先完成不依赖答案的工作。
+- 发布、共享、合并、删除远端分支和不可逆 Git 操作遵循用户的明确授权与审批要求；执行前完成可审阅的准备工作。不要把审查、技能调用或普通测试另设为批准门槛。
+- 独立调查、审查或验证能明显提高效率时可用子 agent；共享写入范围保持串行，主线程复核关键科研结论。简单任务直接完成，不强制固定模型、人数或 reviewer 链。
+
+## 按任务读取
+
+| 当前任务 | 相关入口 |
+| --- | --- |
+| 安装、使用与文档导航 | [README](README.md)、[中文说明](README.zh-CN.md)、[文档索引](docs/README.md) |
+| 开发环境、检查范围、完成标准 | [贡献指南](CONTRIBUTING.md)、[工作流](docs/AGENT_WORKFLOW.md) |
+| 跨模块调用或职责调整 | [架构](docs/ARCHITECTURE.md) |
+| 数值、单位、物理定义、结果字段 | [科学约定](docs/SCIENTIFIC_CONTRACTS.md)、[API](docs/API.md)、相关模块与测试 |
+| CLI、桌面或工作簿行为 | [CLI](docs/CLI.md)、[GUI](docs/GUI.md)、[Excel](docs/EXCEL.md) 中与任务有关的部分 |
+| 发布候选或 JOSS 投稿 | [发布流程](docs/RELEASE.md) 或 [投稿入口](docs/joss/README.md)，仅在对应任务中加载 |
+
+## 科研与实现约束
+
+- CLI、GUI、API 使用共享 settings 和 `pipeline.py`；保留兼容入口、规范字段和来源记录。优先修复现有路径，避免另建数值实现。
+- 核对 CIF 身份与哈希、辐射条件、扫描范围和单位：`2theta` 为度，`d` 和波长为 Å，`q=2π/d`、`g=1/d` 为 Å⁻¹。强度通道、弹性 Voigt 与坐标系定义以科学约定为准。
+- 缺失数据保留缺失；数据库失败不能写成“没有候选”。系统消光、强度阈值、重叠和空间群推断分别核查，不能凭峰表缺项断言物相不存在。
+- 理论峰表、合成基准和测试通过分别支持软件定义与数值实现；实验物相识别、定量相分数和机制结论需要相应实验依据。明确区分实验事实、数据解释、机制推断和作者主张。
+- 派生输出使用新目标，保持输入输出分离。已有结果包按程序的完整性校验和事务规则处理；不要为了重跑而自动删除输出、绕过锁或加入覆盖参数。
+
+## 验证与交付
+
+- 选择能验证改动的检查：纯文档检查链接和差异；代码检查受影响测试；科学核心增加解析基准；共享接口、打包或发布再扩大范围。具体命令见工作流。
+- 默认测试使用离线临时夹具。修复请求范围内的失败后重跑受影响检查；检查通过后，只有新改动、失败或未解决问题才扩大或重复验证。GUI 验证需要可用的 Tk 显示环境。
+- 数值定义变化补充有意义的回归证据，更新科学约定；不兼容输出变化更新 schema。领域审阅要求见贡献指南；工程检查不替代科研接受。
+- 交付说明实际改动、验证结果和具体缺口；跳过或未执行的检查不能报为通过。历史计划和审计快照按日期解释，不自动转成每个任务的待办清单。
+
+## 项目技能
+
+本仓库技能放在 `.agents/skills/`，按请求匹配加载。[$diffractscout-cif-reference](.agents/skills/diffractscout-cif-reference/SKILL.md) 用于从本地 CIF 生成并核验理论峰表与 Excel；普通代码修改或文档修正直接走上述入口。

CHANGELOG.md

@@ -6,6 +6,10 @@ All notable changes are recorded here. The project follows semantic versioning a
 
 ### Added
 
+- `fetch-prototypes` and `adapt` for symmetry-prototype CIFs and caller-supplied composition or cited lattice edits. Alpha (194), beta (229), and alpha-double-prime (63) selection stays outside `discover` / `run`. Literature numbers are supplied by the caller; the package does not extract them. The alpha-double-prime fallback is the public-domain COD 1523304 Ti–20 at% Nb scaffold.
+- `prepare-cifs` and the desktop Initial CIFs dialog produce checked starting models with raw sources, provenance, per-phase lattice/chemistry assumptions, a theoretical peak preview and a verified manifest. Chemically resolved P1 atoms can be standardized into their verified parent symmetry; multiorbit compounds are rejected and subsequent ranked candidates are tried. All three Ti families have attributed offline scaffolds. Cited phase parameters can override lattice, internal coordinates and bulk chemistry; no literature values are invented.
+- `adapt` links symmetry-equivalent conventional cell axes and rejects conflicts. Formula, Z and formula mass now follow expanded occupied sites; stale atom-type/geometry tables are removed from derivatives. Interstitial percentages are not substituted onto metal sites.
+
 - Windows desktop acceptance target and UTF-8 command-line output, including
   redirected inherited exports on non-Chinese Windows installations.
 

CONTRIBUTING.md

@@ -11,14 +11,29 @@ Contributions are welcome through GitHub issues and pull requests.
 
 ## Development setup
 
+Windows / PowerShell:
+
+```powershell
+git clone https://github.com/D-sudoasd/DiffractScout.git
+cd DiffractScout
+py -3 -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e ".[test]"
+.\.venv\Scripts\python.exe -m pytest -q --ignore=tests/test_gui.py
+```
+
+Bash:
+
 ```bash
 git clone https://github.com/D-sudoasd/DiffractScout.git
 cd DiffractScout
 python -m venv .venv
-python -m pip install -e ".[test]"
-pytest -q
+.venv/bin/python -m pip install -e ".[test]"
+.venv/bin/python -m pytest -q --ignore=tests/test_gui.py
 ```
 
+Use that same environment for subsequent commands below. GUI interaction
+tests need a working Tk display; see the [GUI guide](docs/GUI.md).
+
 Normal development and test work only needs `.[test]`. Before running the
 complete local release preflight, install the additional release tooling with:
 
@@ -36,15 +51,25 @@ Tests must not depend on a live Materials Project API unless they are explicitly
 
 ## Pull-request requirements
 
-- Add or update tests for changed numerical behavior.
+- Use change-specific local checks from the [workflow guide](docs/AGENT_WORKFLOW.md).
+  Documentation-only changes normally need `python scripts/check_docs.py`
+  and `git diff --check`; code changes need the affected tests and lint checks.
+- Add or update meaningful tests for changed numerical behavior or contracts.
 - Update `docs/SCIENTIFIC_CONTRACTS.md` when a definition or assumption changes.
 - Update the schema version when a machine-readable output contract changes incompatibly.
 - Preserve missing values; do not replace absent scientific data with guessed numbers.
 - Add source and unit metadata for new numerical fields.
-- Run `python -m diffractscout benchmark -o outputs/pr_benchmark` for scientific-core changes.
-- Run `python scripts/check_release.py --skip-wheel`; use the full release check before a tagged release.
+- Run the analytic benchmark for scientific-core changes, using a fresh output
+  directory; record settings, tolerances and any changed result. Do not
+  overwrite earlier evidence merely to rerun a check.
+- Required CI checks remain the PR gate. Broaden local checks for shared
+  interfaces, dependencies or packaging. Use the complete
+  `python scripts/check_release.py` for release candidates; `--skip-wheel`
+  still runs the full tests, demo and benchmark and is not a routine shortcut.
 - Update `docs/evidence/impact_evidence.json` only for completed, traceable public records; never infer impact from private or prospective activity.
-- For GUI changes, run the Xvfb smoke command in `docs/GUI.md` and update reference screenshots when the layout changes.
+- For GUI changes, exercise affected interactions with a working Tk display;
+  Linux contributors can use the Xvfb commands in `docs/GUI.md`. Record any
+  unavailable GUI checks and update reference screenshots when layout changes.
 - Explain any result differences in the pull-request description.
 
 ## Validation and evidence contributions
@@ -55,6 +80,21 @@ Real-material, independent-software, or external-installation reports should use
 
 A change involving structure factors, systematic absences, tensor conventions, coordinate transforms, elastic moduli, database semantics, or uncertainty handling requires review by a contributor with relevant domain expertise.
 
+Complete the authorized implementation and numerical evidence before requesting
+that review. Documentation corrections that do not change these meanings do
+not automatically require scientific review. Synthetic benchmarks and passing
+tests do not establish experimental validity.
+
+## Working with coding agents
+
+Project instructions are in [AGENTS.md](AGENTS.md); task-specific documents are
+listed in the [documentation guide](docs/README.md). The repository skill
+[$diffractscout-cif-reference](.agents/skills/diffractscout-cif-reference/SKILL.md)
+handles local CIF peak-table exports. Load skills when their workflow applies,
+preserve existing user changes, and continue through appropriate verification
+when implementation has been requested. A read-only review request remains
+read-only.
+
 ## Release process
 
 The maintainer updates the changelog and version, runs the complete tests, analytic benchmark, demo, readiness audit, and package validation, creates an annotated Git tag, publishes release notes, and archives the tagged source with Zenodo or an equivalent repository. See `docs/RELEASE.md`.

MANIFEST.in

@@ -1,6 +1,8 @@
 include pyproject.toml MANIFEST.in
 include README.md README.zh-CN.md LICENSE NOTICE.md AUTHORS.md CITATION.cff CHANGELOG.md
 include CONTRIBUTING.md CODE_OF_CONDUCT.md SECURITY.md GOVERNANCE.md SUPPORT.md ROADMAP.md
+include AGENTS.md
+recursive-include .agents/skills *.md
 include 启动DiffractScout.bat quick_export_diffractscout.bat
 recursive-include docs *.md *.svg *.png *.json
 recursive-include paper *.md *.bib *.svg *.png *.sh *.py
@@ -12,6 +14,7 @@ recursive-include tests *.py
 recursive-include tests *.json
 recursive-include src/diffractscout/compat LICENSE
 recursive-include src/diffractscout/benchmark_data *.cif *.json
+recursive-include src/diffractscout/prototype_data *.cif
 
 recursive-include docs/joss *.md *.json
 include scripts/check_joss_artifacts.py

NOTICE.md

@@ -19,3 +19,20 @@ recorded in `docs/COMPAT_SOURCE_INVENTORY.json`. Original MIT license texts ship
 `diffractscout/compat/cif2peaks/LICENSE` and `diffractscout/compat/phasescout/LICENSE`.
 PhaseScout imports and writable storage paths were adapted for package isolation.
 Inherited CLI output is explicitly configured as UTF-8 for Windows pipe compatibility.
+
+`src/diffractscout/prototype_data/cod_1523304_ti_nb_cmcm.cif` is a copy of the
+public-domain Crystallography Open Database entry 1523304 (Brown, Clark,
+Eastabrook, and Jepson, Nature (London) 201 (1964) 914–915). `fetch-prototypes`
+uses it as a Ti–20 at% Nb Cmcm symmetry scaffold. Its lattice parameters and
+Nb occupancy remain those of that entry until a caller edits a derivative with
+`adapt` and supplies the replacement values.
+
+`prepare-cifs` additionally packages COD 1522498 (McHargue, Adair and Hammond,
+1953, Ti–2.6 at% Nb hcp), with its public-domain header intact, and COD 9008554 /
+AMCSD 0011232 (Wyckoff, *Crystal Structures* 1, 1963, pp. 7–83, beta Ti at
+1173 K). The latter file retains its attribution requirement: use within the
+scientific community requires proper attribution to the source work. Its
+temperature and lattice are source conditions, not room-temperature values
+for a target alloy. Original source files and citations remain in each initial
+CIF bundle; generated CIFs explicitly identify their source and starting-model
+status.