light-project-structure

项目结构生命周期

管理可见项目树及其迁移证据。不要把整洁的目录误认为可复现研究。

迁移现有仓库前，请先阅读 references/project-lifecycle-resource-map.md。 该文件定义了各项产物、策略、访问级别、来源记录和跨技能所有权。小型配置的最低要求请参阅 references/structure-profiles.json， 明确的项目/文件策略请参阅 templates/project-policy.template.json。 交付前，使用 scripts/structure_governance_gate.py 验证配置选择、现有项目的只读安全性、模板残留、机密扫描、环境诊断、授权绑定、已应用清单绑定和回滚证据。

不可妥协的边界

1. 将清点视为只读访问，而非移动授权。
2. 绝不自动覆盖、删除、运行 git rm --cached、初始化 DVC、改写配置或移动符号链接。
3. 绝不将 --force 视为同意。生命周期流程不提供强制绕过。
4. 保留所有 .light/ 内容。只有 memory-pm 可以创建或编辑 passport、项目卡片、决策日志、版本历史、术语和交接文件。
5. 对缺失的事实保留 UNKNOWN。data/raw 这样的路径不能证明其大小、敏感性、不可变性、可重新计算性或 Git 策略。
6. 不要将此覆盖层变成 DAG 节点。不得输出 light.findings.v1；不得添加 STAGE_GATES、ROUTES、阶段编号或反向边。
7. 说明结构符合性并不能证明数据质量、实验可复现性、统计有效性或论文质量。
8. 交付生成或迁移后的目录树前，绝不遗留未解决的模板占位符、未处理的机密扫描命中项，或缺失的必需 Python/R/环境检查。

选择模式

情况	模式
目标目录为空，且用户需要一个起始目录树	使用一个明确的配置运行 scaffold
现有仓库、monorepo 软件包或非 Git 目录	执行 intake，然后停在决策环节
用户查看计划后批准了确切的移动操作	创建授权，然后执行 apply
需要撤销已执行的移动操作	根据已应用清单执行 rollback

不要为非空目录创建脚手架。不要将固定的 23 目录树改造后套用于 R、纯论文、多语言、自定义或 monorepo 项目。

阶段 1 — 信息收集与需求

收集以下信息；无法确定时保留为 UNKNOWN：

• 项目类型，以及所选根目录是 Git 根目录、monorepo 子根目录，还是 非 Git 目录；
• 交付物、计算环境、数据量、远程存储、 协作者、CI、许可证和保留期限；
• Git 根目录、分支、已跟踪／未跟踪／已忽略状态、未提交的更改、 子模块、符号链接、大文件和敏感路径信号。

检查观察到的技术特征和用户声明的交付物后，选择最精简的配置：

• python-research
• r-research
• mixed-research
• paper-only
• existing-custom

配置是可扩展的最低要求，不是合规判定。 所选配置并不能证明项目的情况。intake 会分别记录观察到的文件／配置 信号与策略声明的制品类型，推荐一种配置；如果选择了不同配置却没有具体的 profile_selection_reason，则治理门禁会失败。

将策略模板复制到源根目录之外，填写已知的项目事实，并且仅在有证据时添加 文件规则。合法的已跟踪制品包括小型公开样例、经审查的基准文件、DVC 指针、 最终论文图表、发布制品，或项目策略要求的审计证据。大型／敏感源数据、模型 和结果通常需要使用 DVC／对象存储，但应通过决策确定，而非仅凭目录名称判定。

运行：

python scripts/scaffold.py intake <root> --out <evidence-dir> \
  --profile mixed-research --policy <project-policy.json>

该命令会将证据写入 --out，并验证源快照和 Git 状态未发生变化。

intake 还会输出资源映射中列出的技术特征、环境检查器、模板残留扫描、密钥 扫描和治理报告。工具检查依据观察到或明确声明的制品类型，而不只是所选配置。 如果项目需要 Python、R、Quarto、DVC、LaTeX 或其他本地工具，请在策略中记录 这些要求。只有在需要额外的临时检查时，才使用独立的检查器命令：

python scripts/structure_governance_gate.py --doctor python r

阶段 2 — 审查试运行结果

阅读资源映射中列出的信息收集制品。检查：

• 每一行清单都有定位信息／哈希／大小／Git 状态，以及明确的或标记为 UNKNOWN 的所有者、生成者、可重新计算性、敏感性、分类、 目标和策略依据；
• 技术特征标明其定位信息，并区分观察到的证据与 policy.project.artifact_types；所选配置与推荐配置一致，或有具体的用户覆盖理由；
• 重复项只是证据，绝不是自动删除指令；
• 符号链接、已存在的目标和多个来源映射到同一目标的移动操作均被阻止；
• 在试运行计划和治理门禁中阻止 ../、绝对路径、盘符路径、UNC 路径 或其他逃出根目录的操作路径，而不是留待应用时处理；
• monorepo 子根目录使用相对于该子根目录的路径，不将整个 Git 根目录视为项目；
• .light/ 得到保留，且没有移动操作；
• 不会仅因大型已跟踪样例位于 raw 目录下就将其判定为不合规；
• 对大型、可重新计算或敏感的制品，提示进行存储策略决策；
• 相关时，提供模板来源信息、残留占位符扫描、密钥扫描和环境检查器结果； .env 忽略状态不等于密钥扫描结果。

展示：

1. 推荐的配置及其原因；
2. 安全操作 ID；
3. 被阻止的冲突和未知项；
4. 分别列出移动／重命名、覆盖（不支持）、删除、 git rm --cached、配置重写和 DVC 初始化的决策；
5. 计划的 SHA-256。

然后停止。询问用户授权哪些操作 ID。不要预先填写用户的 答复。

在将某种结构标示为已就绪之前，对交付包运行治理门禁：

python scripts/structure_governance_gate.py \
  --input templates/project-structure-governance.example.json

随附示例刻意采用失败即关闭的方式：它尝试在现有 R 项目上搭建脚手架、保留模板 占位符、报告密钥值、遗漏 R、使用强制模式、移动 .light/、重复操作 ID、应用 删除、移动符号链接，并造成覆盖风险。

第 3 阶段 — 绑定授权

用户选择后，创建授权文档：

{
  "schema": "light.project-structure.v2.authorization",
  "authorization_id": "<user-created stable authorization id>",
  "plan_sha256": "<exact migration-plan plan_sha256>",
  "approved_action_ids": ["move-0001"],
  "authorized_by": "<user-supplied identifier>",
  "authorized_at": "<YYYY-MM-DD>"
}

不要包含被阻止或未知的操作。authorization_id 和 authorized_by 必须是用户提供的具体值，而不是模板文本； authorized_at 不能是未来时间。计划变更后必须重新授权。授权不能解决覆盖问题，也不能绕过符号链接阻止规则。

第 4 阶段 — 执行、验证、回滚、重新执行

python scripts/scaffold.py apply \
  --plan <migration-plan.json> \
  --authorization <authorization.json> \
  --manifest-out <applied-manifest.json> \
  --as-of <YYYY-MM-DD>

python scripts/scaffold.py rollback \
  --manifest <applied-manifest.json> \
  --rollback-out <rollback-manifest.json>

apply 会重新验证源哈希和绝对路径包含关系，创建缺失的目标父目录，拒绝已存在的目标，仅移动普通文件，记录前后 SHA-256，并写入一份已执行清单，其中通过定位符和文件 SHA-256 绑定确切的计划文件和授权文件。在规划阶段，逃逸出所选根目录的路径应已标记为阻止；即使此类路径进入 apply，apply 仍会安全失败。rollback 会验证目标哈希，并拒绝覆盖重新出现的源文件；它使用已执行清单安全还原，且不要求原始计划文件或授权文件仍然存在。

回滚后：

1. 将源快照和 Git 状态与接收时的状态进行比较；
2. 验证未跟踪草稿和 .light/ 内容仍逐字节一致；
3. 仅在授权仍符合预期时重新执行；
4. 报告未解决的冲突，并将手动 Git/DVC 决策单独列出。

全新项目脚手架

仅用于空目标：

python scripts/scaffold.py scaffold <target> --profile r-research --name <name>

该命令会在 .project-structure-provenance.json 中记录配置文件和生成器的哈希。这是一次性生成，不适合安全地更新模板。对于托管模板的演进，请评估 Copier 或 Cruft，并审查本地修改和冲突；不要声称漂移检测能够保证合并成功。

所有权交接

• 需要 .light/ 记忆时，请让 memory-pm 运行 pm.py init；不要在此处代做。
• 将数据质量、沿袭和发布设计交给 data-engineering。
• 将运行清单和可执行的可复现性工作交给 experiment-coding。
• 让 file-reading 理解提供的仓库/材料；只有此技能负责移动文件。
• 如有用，可让 orchestrator 使用交付内容；不要创建门禁。

验证

运行脚本自检：

python scripts/scaffold.py --selftest
python scripts/structure_governance_gate.py --selftest

该自检涵盖只读源文件的接收流程、已跟踪的夹具策略、生成的环境/模板/机密/治理报告、未跟踪草稿、.light/ 保留、授权绑定、已执行清单对计划文件/授权文件的绑定、真实移动/哈希证据、回滚、重新执行、非 Git 模式、单体仓库子根目录处理、配置文件脚手架幂等性，以及尽力而为的 Windows 符号链接分支。

交付前，请验证：

• 接收过程中未修改源文件。
• 用户在执行前已看到冲突、未知项、操作 ID 和计划摘要。
• 已执行的移动与授权 ID 完全一致，且包含前后哈希。
• 已执行清单通过定位符和文件 SHA-256 绑定确切的迁移计划文件和授权文件。
• 未覆盖任何目标，也未移动任何符号链接。
• 计划/已执行的源路径或目标路径均未逃逸出所选项目根目录。
• 未跟踪的工作和 .light/ 内容在移动和回滚后均保留。
• 夹具/黄金文件/DVC 指针按策略而非路径分类。
• 存在模板残留扫描、机密扫描、环境诊断和配置文件选择理由；观测到的/声明的签名支持该配置文件，且在声称适用时检查了 R/Python 依赖要求。
• structure_governance_gate.py 对实际交付包检查通过。
• 已记录模板来源/版本/哈希/参数及更新限制。
• 交付内容未声称项目结构能够证明可复现性。