# HW 最新产物同步

本流程只处理 `operation=sync_code_artifacts`。它从平台已登记的会玩固定分支同步最新 Git 文件，
从 dev 配置中心读取最新活动配置，并更新平台现有产物。不得进入 Step 7-12，不修改业务代码，
不创建分支，不提交或推送，不运行 Go 编译，不读写 workflow checkpoint，不改变任何阶段状态。

## 输入与路径

必须提供 `pipeline=true`、`region=HW`、正整数 `act_id`、活动信息、可用 analysis/server 产物路径和
当前活动工作区根目录。以活动信息的 `server_branches` 为唯一仓库与分支事实源：

- 仓库必须唯一匹配 `hw/wespy-http-go`；分支不得从活动名称推断。
- `activity_module_dir` 必须是安全的仓库相对 `app/activity/...` 路径。
- 使用平台 `repos` 挂载提供的共享 Git 仓库，允许软链接；由设计业务适配层使用明确 repository_path（缺省优先旧平台 repos/hw/wespy-http-go，再兼容固定挂载 repos/huiwan-wespy-http-go）和匹配的remote/common directory，
  沿用旧平台路径 `<workspace_root>/worktrees/hw/wespy-http-go/<登记分支>` 创建或复用本活动 worktree。不 clone，不进入其它活动分支。
- `analysis_artifact_dir` 优先取当前活动已登记 `requirement_doc` 的父目录，否则使用
  `<workspace_root>/artifacts/analysis`；`server_artifact_dir` 固定为
  `<workspace_root>/artifacts/server`，不依赖生产 handoff。两个产物目录都必须位于当前活动工作区，
  禁止符号链接跳到其他活动目录。

任一身份或路径无法唯一确定时返回 `blocked`，列出缺失字段，不尝试其他仓库或目录。

## 1. 同步固定分支

加载 `server__activity-design-generator` 的 `huiwan/references/server-preparation.md`，使用
`operation=prepare_sync_worktree` 的纯 Git 模式；禁止使用会初始化 checkpoint 的完整 server prepare。
在当前活动 cwd 写入仅含 `pipeline=true/stage=server/region=HW`、平台 `activity_id`、`act_id`、
完整原样 `activity_info` 的请求；脚本直接解析其中 `server_branches` 的链接或记录。
兼容可选 `server_branch`，已提供时必须与解析结果一致，无需补造结构化记录。然后执行：

```bash
python3 "{DESIGN_GENERATOR_SKILL_ROOT}/huiwan/scripts/prepare_server_inputs.py" \
  --request <同步身份请求.json> --worktree-only
```

worktree 不存在时从已登记分支创建本地 checkout；不创建新的远端分支。复用 worktree 时先校验：

1. remote 与登记仓库一致，当前分支与登记分支一致；
2. tracked/untracked 工作区均为空；
3. 本地没有领先提交，且没有分叉；
4. 平台活动ID/act_id、登记分支、Git common directory与本次工作区路径均一致，且Git注册匹配。

失败时返回 `blocked`。不得 stash、reset、rebase、clean、强制 checkout 或 force push；替代处理是报告
实际路径、分支和状态，等待操作者清理后重试。

脚本执行单次目标分支 fetch 和必要的 fast-forward，返回 `before_commit`、`after_commit` 和 `base_repo_root`；
首次创建时 before_commit 为 null。后续 Git 产物及联调快照所需的代码/Contract/API 输入都从
返回的同一 worktree 读取；本轮不得再次 pull。此模式不读取 PRD、checkpoint 或生产 handoff，
五类产物缺失仍由后续步骤分别处理。
绑定 `module_root=Path(worktree_root)/activity_module_dir`，检查 realpath 未越出 worktree 且无
symlink 别名后读取原生产物；输出目录由以上固定规则提供，不从旧 handoff 推导。

## 2. 构建五类产物

五项互相独立。单项缺失或失败记为 `missing|failed` 并继续，不覆盖平台旧产物。

### requirement_doc

HW 同步仅生成候选，不提交 analysis。以下输出必须落在 `<analysis_artifact_dir>/candidate/`，不得覆盖有效需求。调用需求 Skill 评估 impact、核验来源与已有确认后才用 effective_requirement activate；未决保留候选并继续独立同步项。

从 `<module_root>/prd_analysis.md` 和 `<module_root>/requirement_rules.json` 读取。两者都存在时，复用
`activity-requirement-processor/huiwan/scripts/build_requirement_artifact.py`，输出到：

```text
<analysis_artifact_dir>/candidate/requirement_doc.md
<analysis_artifact_dir>/candidate/prd_analysis.md
<analysis_artifact_dir>/candidate/requirement_bundle.json
<analysis_artifact_dir>/candidate/requirement_completion_summary.json
```

构建脚本校验失败时保留旧 `requirement_doc`，不得把 `prd_analysis.md` 直接提交为需求产物。

### design_doc 与 openapi

- `<module_root>/design_doc.md` 映射为 `stage=server,type=design_doc`。
- `<module_root>/openapi.yaml` 映射为 `stage=server,type=openapi`。

文件存在且可读时直接使用原生文件，禁止重新生成或改写；不存在时只提示。没有自定义 route 导致
`openapi.yaml` 不存在属于正常 `missing`，不生成空文件。

### config_json

执行 `act-cli act config get -r HW --act-id <act_id> --raw`，把成功返回的最新 dev 原生配置先写入
临时文件。读取失败时记为 `failed`；不得使用模块内 `activity_info.json` 或平台旧配置替代。

按以下固定命令构建；脚本从 `--out` 的父目录派生同级 `activity_info.json`，调用方不得
单独传入或自行拼接 native 输出路径：

```bash
python3 huiwan/scripts/build_sync_config_snapshot.py \
  --raw <temp-dev-config.json> \
  --module-rel <activity_module_dir> \
  --act-id <act_id> \
  --out <server_artifact_dir>/config_json.json
```

脚本必须先完成 JSON/act_id/bundle 校验，再替换两个正式文件；失败时两个旧文件均保持不变。产物满足：

- `schema_version=hw-artifact-bundle/v2`、`kind=config`；
- 恰好包含一份 `native_path=<activity_module_dir>/activity_info.json` 的原生配置正文及 SHA-256；
- metadata 记录 `artifact_mode=dev-readback-snapshot-v1`、`region=HW`、`act_id`、
  `source=dev_config`、同步时间和 `modules` 投影。

该快照只表达“同步时 dev 的最新配置”，不包含或冒充 Step 5 的 G2、审批、写入和 checkpoint 证明，
也不使配置阶段变为完成。只有脚本返回 `ok=true` 时才提交 `config_json`。

### integration_doc

产物类型固定为 `stage=server,type=integration_doc`，仅提交文档正文。

在临时目录写入 `hw_integration_inputs.json`，其唯一 module 固定使用：

- `technical_design=<module_root>/design_doc.md`；
- `code_dir=<module_root>`、`code_contract=<module_root>/hw_code_contract.json`、
  `api_manifest=<module_root>/hw_api_manifest.json`，均来自 `after_commit`。

调用 `activity-integration-doc` 的同步快照模式，输出正式文档/bundle 和临时 OpenAPI 副本：

```bash
python3 <activity-integration-doc>/huiwan/scripts/validate_hw_integration.py \
  --inputs <temp>/hw_integration_inputs.json \
  --report <temp>/integration_validation_report.json \
  --sync-snapshot \
  --after-commit <after_commit> \
  --act-id <act_id>

python3 <activity-integration-doc>/huiwan/scripts/build_integration_artifact.py \
  --inputs <temp>/hw_integration_inputs.json \
  --validation-report <temp>/integration_validation_report.json \
  --out <server_artifact_dir>/integration_doc.md \
  --bundle-out <server_artifact_dir>/integration_bundle.json \
  --openapi-out <temp>/integration_openapi.yaml \
  --sync-snapshot \
  --after-commit <after_commit> \
  --act-id <act_id>
```

快照模式必须校验 `act_id`、唯一 §9、真实 Go route/handler、Code Contract、API manifest
和 OpenAPI 一致性，且 bundle metadata 绑定 `artifact_mode=sync-readback-snapshot-v1`、`after_commit`和各输入
SHA-256。同步校验通过即视为正式联调终态；文档正文保持原始 §9，不增加模式前缀或隐藏 marker。它不得
读取、创建或更新 workflow checkpoint。

validator 或 builder 失败时，旧 `integration_doc.md` 和 `integration_bundle.json` 必须保持不变。临时 OpenAPI
只用于验证 bundle 绑定，不覆盖、不替代、不重复提交前述独立 `openapi` 产物。

## 3. 提交与返回

业务 Skill 只返回 `updated` 清单、完整产物路径与内容 hash，不调用 `submit_artifact`。
Production Flow 主线不提交 HW `requirement_doc`，只汇报本地候选/生效状态；`design_doc`、`openapi`、
`config_json`、`integration_doc` 使用 `stage=server`。Git 项和 `integration_doc` 按文件 SHA-256 判断幂等；
config 项按 bundle 内原生配置
`files[0].sha256` 判断，忽略每次变化的 `synced_at`。与平台已登记原生内容相同的项记为
`unchanged`，不重复提交。
提交失败只由主线重试该提交，不重复调用 Git 准备 helper/fetch、配置读取或产物构建。

同步完成后由 production-flow-server 按既有规则刷新活动视图。不得改变 `done|partial|blocked` 等已有
阶段状态，也不得自动运行方案、配置发布、代码、正式联调或测试流程。

返回 `<server_artifact_dir>/sync_code_artifacts_summary.json`，至少包含：

- 仓库、`remote_name`、登记分支、`base_repo_root`、`git_common_dir`、`worktree_root`、`before_commit`、`after_commit`；
- dev 配置读取时间和配置 hash；
- 五项的 `source`、`source_path`、`commit_sha`（Git/联调项）、`sha256`、
  `status=updated|unchanged|missing|failed`、错误及 `file_path`；提交回执由主线取得，业务 Skill 不伪造或等待回执；
- `integration_doc` 另记录 snapshot input hash、bundle/document SHA-256、OpenAPI 适用性和静态校验结果；
- 空生产 Go 目录按合法纯组件场景继续生成，并在校验 summary/bundle 中记录 warning；
- `status=done`（所有适用项均为 updated/unchanged/not_applicable）或 `status=partial`（任一适用项
  missing/failed）。`hw_api_manifest.json` 明确 `custom_routes=false` 时，缺少 OpenAPI 记为
  `not_applicable`；否则缺少 OpenAPI 记为 `missing`。

## 完成自查

- Git 产物和联调代码/Contract/API 输入均来自本轮唯一一次 Git 准备 helper 返回的 `after_commit`。
- `requirement_doc` 由既有构建脚本生成，`config_json` 是已 verify 的 v2 config bundle。
- `integration_doc` 由无 checkpoint 同步快照模式生成，且不提交 `integration_bundle.json`。
- 缺失/失败项未覆盖旧产物，成功项的路径、hash 和目标 stage/type 已完整返回给主线。
- 没有业务代码改动、Git 交付、Go 编译、checkpoint/阶段状态变化或下游自动执行。