protect-my-hair/nucleus-marketplace/target-repo-setup

Target Repo Setup

用于目标产品仓库的 Nucleus V2 初始化。它是 Skill package 入口，确定性本地能力由 scripts/target_repo_setup.py 的显式子命令执行。人读说明先使用中文动作；CLI 子命令、JSON 字段和 approval scope 保持英文机器契约。

最短操作顺序

1. 执行目标仓库只读检查（run-preflight），原始报告写到目标仓库外部。
2. 归一化只读检查结果（normalize-preflight）；未审批时只写 .nucleus/runs/<workflowRunId>/**。
3. 生成初始化计划、规则块候选差异、docs/specs/** 规范模板候选和模板候选产物（build-plan、check-boundary、build-candidates）。
4. 生成运行结果包（build-result）：先读 .nucleus/runs/<workflowRunId>/summary.md，机器事实源仍是 .nucleus/runs/<workflowRunId>/result.json。
5. 缺少人工审批事实时停在 NEEDS_HUMAN_REVIEW；只有审批事实有效时，才能写 AGENTS.md 的 Nucleus 管理规则块、允许目录和缺失的默认 docs/specs/** 规范模板。
6. 正式特性/测试骨架不由初始化步骤默认选择路径；必须由目标仓库特性树评审给出明确目标路径（targetPath）后，才允许单独执行提升命令。
7. 如需检查、安装、配置或激活宿主工具，单独使用 $host-tool-setup；本 Skill 的成功不代表宿主工具可用。

对人交付口径

运行结束后必须先读 .nucleus/runs/<workflowRunId>/summary.md 和 result.json，再按 references/human-interaction.md 输出结论。最终回复不能只列状态（status）、检查项（gate）或工具状态；必须明确“已经完成什么、还没有做什么、需要用户决定什么、下一步怎么做”。

人审前子代理预审

到达 setup plan review 或 template candidate review 前，必须按 workflow 的 subagentPreReview 调度独立 reviewer 子代理；未取得“材料可提交人工审查”预审结论时，不得请求人工审批或评审通过。

本地子命令

运行 python3 scripts/target_repo_setup.py list-subcommands 查看完整能力。当前实现：

• 只读检查和运行证据：run-preflight、normalize-preflight、build-plan、check-boundary、build-candidates、build-result。
• 审批后初始化写入：resolve-approval、write-managed-block、init-assets。
• 评审后正式写入：promote-feature-skeleton、promote-test-skeleton。

边界

• 目标是目标产品仓库，不是 Nucleus 插件仓库。
• SKILL.md、scripts/、references/、assets/ 是 Claude Code / Codex 共享的 Skill 主体。
• agents/openai.yaml 只是 Codex-only optional metadata；Claude Code 不应依赖它执行本 Skill。
• 标准过程路径是 .nucleus/**，测试过程证据路径是 .nucleus/tests/**。
• 正式开发规范事实源位于 docs/specs/**；初始化只在 init-assets 审批后写缺失的默认规则模板，已有文件不覆盖，后续补充必须走目标仓库评审。
• 正式产品能力写入只面向 docs/features/** 和 tests/**，且必须经过 review gate。
• docs/requirement/** 是受保护需求事实源；普通 setup 和普通开发不得写。
• legacy risk path 只读探测：.autocode/**、.claude/notepads/**、docs/bugfix/**。命中时登记风险并阻塞确认。

何时读取资源

• workflow step、artifact、approval 和 command policy：读 references/workflow-contract.md。
• 写入边界或 plannedWrites 判断：读 references/repo-asset-boundaries.md。
• managed block marker、重复 marker、partial marker 或 dirty conflict：读 references/managed-block.md。
• 审批事实、result status 和 changedFiles 证据：读 references/approval-and-result.md。
• blocker code、恢复建议和 result 映射：读 references/blocker-matrix.md。
• 机器词和中文显示名：读 references/terminology.md。
• 对人交付格式、审批提示和反例：读 references/human-interaction.md。
• 候选内容只从 assets/ 取，不把 asset 当作已批准正式写入。

阻塞规则

必须 ALERT_AND_BLOCK：

• 目标仓库只读检查报告（preflight report）缺失、结构错误或已阻塞。
• plannedWrites 越界，或计划写 legacy risk path。
• Nucleus 管理规则块边界标记（managed block marker）重复、残缺、hash 不匹配或无法安全定位。
• 缺少 setup-plan-review.subagentPreReview 且材料可提交人工审查的预审结论，或缺少后续人工审批事实，却要写 AGENTS.md、CLAUDE.md、docs/features/** 或 tests/**。
• 尝试把宿主工具检查、安装、配置、激活、索引或回滚纳入本 Skill。
• hooks 被当作关键检查项（gate）的替代品，而不是增强检查项。