pre-deploy

@rules/parallel-remediation.md @rules/tracked-remediation.md

预部署技能

证明代码仓库已准备好部署；或者只修复经复现、且阻碍验证的质量或构建问题。

<output_language>

默认情况下，所有面向用户的交付内容、保存的产物、报告、计划、生成的文档、摘要、交接说明、提交／消息草稿和验证说明均使用韩语，即使本规范技能文件是用英语编写的。

保留源代码标识符、CLI 命令、文件路径、架构键、JSON/YAML 字段名、API 名称、包名称、专有名词，以及必须使用指定语言或原语言的引用源文。

仅在用户明确提出要求、现有目标产物为保持一致必须使用其他语言，或机器可读契约要求使用准确的英文词元时，才使用其他语言。如果存在本地化模板或参考资料（例如 *.ko.md 或 *.ko.json），面向用户的产物应优先采用它们。

</output_language>

<request_routing>

正向触发条件

• “运行预部署检查”或“检查是否已准备好部署。”
• “让这个仓库达到可部署状态”或“修复部署前的阻碍。”
• “在发布前运行最终的 lint／类型检查／构建验证。”
• “在部署前验证这个 Node/Rust/Python 工作区。”

不在范围内

• 具体的部署失败日志、平台构建失败、仅出现在 CI 环境中的不匹配，或生产部署问题。转交部署修复流程，要求根据日志修正平台或构建配置。
• 有复现步骤的运行时错误或应用行为异常。转交缺陷修复流程，要求提供最小代码改动以及证明问题已解决的复现过程。
• 与经复现的预部署阻碍无关的新功能、广泛重构或推测性清理。转交给 execute 或相关实现技能。
• 根目录中没有 package.json、Cargo.toml、pyproject.toml、requirements.txt、setup.py、Pipfile 或 poetry.lock 标记文件的不受支持仓库。

边界情况

• 如果用户只要求验证，则运行检查并报告阻塞项，不要编辑文件。
• 如果初始检查发现一个明显且风险较低的阻塞项，则使用 Fix-now。
• 如果故障涉及多个技术栈、工作区，或存在不明确的依赖／配置链，则使用跟踪式修复，并在条件允许时并行处理。
• 如果故障实际是部署平台或运行时应用问题，则停止部署前修复，转交处理，而不是接手不属于本任务的问题。

</request_routing>

<instruction_contract>

字段	约定
意图	证明已做好部署准备，或针对已复现的 lint／类型检查／构建阻塞项进行范围明确的修复。
触发条件	用户要求部署前检查、确认可部署、最终质量门禁或本地技术栈验证时启用。
范围	负责目标根目录验证、技术栈检测、部署检查基线、已复现阻塞项的分类／修复、修复跟踪及就绪情况报告。
权限	用户和项目指令优先于此技能；本地工具链输出、技术栈标记和验证脚本均作为证据。
证据	编辑前使用技术栈检测、完整初始部署检查输出、失败命令日志、相关配置及针对性复查输出。
工具	使用仓库本地脚本、本地读取／编辑操作，以及仅用于独立任务线的有限子 Agent；这不代表允许进行部署或对生产环境产生副作用。
流程	不循环：每个请求只进行一轮范围明确的验证 -> 分类 -> 修复 -> 复验。只有出现新复现的阻塞项时才重新进入流程；在证明就绪、遇到不受支持的技术栈或需要转交时停止。
输出	用韩语提供就绪情况报告，说明范围、检测到的技术栈、模式、阻塞项、修复、验证命令、跳过的检查及风险。
验证	首先运行完整的 skills/pre-deploy/scripts/deploy-check.mjs；在声称已就绪前再次运行，并在修复后执行针对性检查。
停止条件	证明已做好部署准备、报告仅验证模式下的阻塞项、报告不受支持的技术栈，或遇到需要转交／权限阻塞时停止。

</instruction_contract>

<argument_validation>

• 如果未提供参数，则默认使用当前仓库根目录。
• 如果用户指定子目录或工作区，则确认其存在，将命令切换到该目录，并从那里重新检测技术栈。
• 如果用户提出仅验证、仅报告、仅审计或类似要求，则不要编辑文件。
• 声称此技能适用前，始终先从目标根目录检测技术栈。
• 如果未检测到受支持的技术栈，则立即停止并报告 pre-deploy 不适用；不要进入虚假的修复循环。

</argument_validation>

## 可用脚本

运行脚本时，请将当前工作目录设为目标根目录，以确保检测准确。如果目标根目录是仓库根目录，请使用以下相对于仓库的路径；如果目标是子目录/工作区，请通过绝对路径或正确的相对路径返回仓库根目录来调用相同脚本：

脚本	用途
skills/pre-deploy/scripts/stack-detect.mjs	检测项目技术栈（node、rust、python）
`skills/pre-deploy/scripts/deploy-check.mjs [--parallel	--sequential]`
skills/pre-deploy/scripts/lint-check.mjs	运行特定于技术栈的质量检查
skills/pre-deploy/scripts/build-run.mjs	运行特定于技术栈的构建阶段
skills/pre-deploy/scripts/pm-detect.mjs	检测 Node 包管理器（npm/yarn/pnpm/bun）

注意：

• 辅助脚本会根据当前工作目录检测技术栈和包管理器。
• 如果同时配置了 Node 类型检查和 lint 命令，lint-check.mjs 已会并发运行这些相互独立的命令；不要再借助额外 Agent 重复内部并行处理。
• deploy-check.mjs 默认使用 --parallel，以缩短总耗时，同时保留两条命令的日志和失败信息。对于资源受限的运行器，或无法安全共用缓存的工具，请使用 --sequential 或 PRE_DEPLOY_MODE=sequential。
• 每次质量检查只读取一次 Node 包脚本；Python compileall 的回退检查会排除生成文件、依赖、版本控制和虚拟环境目录。
• 将跳过的检查视为“未配置”或“工具不可用”，而不是通过。

自适应结构化推理

在实施之前，先进行一轮内部结构化推理，并根据故障情况调整推理深度：

复杂度	推理深度	信号
简单	3 步	单个技术栈、单条失败命令、根因明确、修复风险低
中等	5 步	单个技术栈中存在多个相关故障，对配置或依赖有中等影响
复杂	7 步以上	涉及多个技术栈／工作区、修复策略不明确、共享配置、依赖链或 CI／部署边界

推荐流程：分类 -> 阅读确切的故障输出 -> 确定根因 -> 选择有针对性的验证 -> 决定直接修复、并行处理、跟踪整改或移交。

</mandatory_reasoning>

<complexity_classification>

在首次完整部署检查失败后进行分类：

复杂度	信号	处理路径
简单	单项检查失败、单个技术栈、文件／配置负责人明确、存在一条安全的修复路径	立即修复
中等	单个技术栈或工作区内有多项故障，且足够独立，可针对性修复	立即修复并使用 TodoWrite 跟踪
复杂	多个技术栈故障、共享配置、monorepo／构建图问题、修复方案不确定，或可能产生跨领域副作用	跟踪整改；使用子 Agent 前先阅读 rules/parallel-remediation.md

无法确定时，按更高复杂度分类。保留证据并明确责任归属，胜过悄然进行大范围改动。

</complexity_classification>

<execution_modes>

• 仅验证：运行检测和 deploy-check.mjs，报告检测到的技术栈、通过／失败／跳过的检查，以及阻碍项。不做任何编辑。
• 立即修复：对于简单／中等且已复现的阻碍项，创建 TodoWrite 条目，进行针对性修复，重新运行有针对性的检查，然后重新运行完整部署检查。
• 并行整改：对故障分组后，仅针对相互独立的诊断任务或互不重叠的编辑任务使用有限范围的子 Agent／后台 Agent。由主 Agent 负责整合和最终验证。先阅读 rules/parallel-remediation.md。
• 跟踪整改：对于复杂情况，先阅读 rules/tracked-remediation.md，然后创建或恢复 .hyper/pre-deploy/flow.json，并包含 detect、baseline、triage、fix、verify、report 阶段。
• 移交：将平台部署故障转交给基于日志的部署整改流程；将运行时应用程序错误转交给基于复现的缺陷修复流程；将无关的实施请求转交给 execute。

</execution_modes>

完整验证证明

从仓库根目录运行：

skills/pre-deploy/scripts/deploy-check.mjs --parallel

除非目标根目录没有受支持的技术栈，否则不要跳过此初始命令。它用于建立基线并捕获确切的阻碍项。 并行模式是默认的快速路径。它会等待两个阶段完成，且任一阶段失败都会导致整体失败；绝不会将其中一个阶段成功视为已就绪的证明。如果并发工具链争用内存、CPU 或共享构建缓存，请使用 --sequential。

逐步验证

从仓库根目录运行：

# 1) quality checks
skills/pre-deploy/scripts/lint-check.mjs

# 2) build phase
skills/pre-deploy/scripts/build-run.mjs

修复后可使用逐步命令进行针对性复查，但最终就绪声明仍要求完整运行 deploy-check.mjs。

## 技术栈行为摘要

• Node.js：类型检查／lint（如果已配置）+ 构建脚本（如果已配置）
• Rust：cargo fmt --check + cargo clippy + cargo check + cargo build --release
• Python：lint（如果可用，则使用 ruff／flake8）+ 类型／语法检查（mypy 或 compileall）+ 构建（poetry build 或 python -m build，回退到 compileall）
• 不受支持的仓库：停止并报告检测到的不受支持技术栈错误，不要继续进行修复

<implementation_rules>

• 编辑前先阅读确切的命令输出；不要猜测失败原因。
• 按技术栈、命令和优先级将失败项转为 TodoWrite 事项。
• 除非能够证明失败彼此独立，否则先修复第一个／根本原因，再处理连锁错误。
• 每次编辑仅针对已复现的阻塞问题及其直接依赖。
• 每次编辑后，重新运行范围最小的相关检查。
• 如果使用子 Agent，为每个工作流明确目标、范围、负责人、输出和停止条件；绝不要让两个工作流同时编辑同一文件或共享配置。
• 负责人必须综合子 Agent 的结果、检查最终差异，并直接运行最终验证命令。

</implementation_rules>

<completion_report>

使用以下报告格式：

## Done

**Scope**: [repo root or workspace]
**Stacks detected**: [node/rust/python]
**Mode**: [validate-only/fix-now/parallel remediation/tracked remediation/handoff]
**Initial blockers**: [none or summarized failures]
**Fixes applied**: [changed files or none]
**Validation**:
- `skills/pre-deploy/scripts/deploy-check.mjs`: [passed/failed/not run with reason]
- Skipped/not configured checks: [list]
**Remaining risks**: [none or explicit caveats]

只有在最后一次完整运行 deploy-check.mjs 通过后，才能说“已准备好部署”。

</completion_report>

执行检查清单：

• 已验证目标根目录或工作区
• 已检测到受支持的技术栈，或已报告不受支持的技术栈并停止
• 对于受支持的技术栈，已首先完整运行 skills/pre-deploy/scripts/deploy-check.mjs
• 已按技术栈／命令／优先级跟踪失败项
• 编辑前已收集根本原因证据
• 已在适当的深度完成结构化推理
• 如果使用并行工作流，各工作流均彼此独立且范围明确
• 每次修复后均已运行针对性验证
• 在声明已准备就绪前，完整部署检查已通过
• 已单独报告跳过的检查和通过的检查

禁止事项：

• 未通过完整部署检查却声称已准备好部署
• 未复现失败就编辑，除非用户明确要求在此技能范围之外执行实现工作
• 将跳过的检查视为已通过
• 检测到不受支持的技术栈后仍继续操作
• 将特定产品的子 Agent 语法视为所有运行时都支持的必需语法
• 让子 Agent 编辑重叠文件，或负责最终的就绪判定