docs: bound YAML-first cleanup stages

.agents/skills/unidesk-ymalops/SKILL.md

@@ -9,7 +9,7 @@ description: UniDesk YAML-first 运维正规化技能。用户提到 ymal-first/
 
 本技能用于推进 UniDesk 的 `ymal-first 正规化`：把运维参数、节点/lane/service 归属、公开暴露、Secret 绑定、容量/版本/endpoint 等可调事实收敛到 YAML；代码只负责读取、校验形状、渲染计划、执行薄的 domain CLI。
 
-长期跟踪 issue 是 `pikasTech/unidesk#390`。如果任务持续超过一个工作段，使用 `bun scripts/cli.ts gh issue comment create 390 --repo pikasTech/unidesk --body-stdin` 追加进度、卡点和验收证据。
+当前收敛跟踪 issue 是 `pikasTech/unidesk#390`。#390 是固定 R1-R5 的关闭计划，不是继续追加 Round 的长期队列；只能为固定 R1-R5 创建对应子 issue，不得新增 R6 或“继续 Round”。如果任务持续超过一个工作段，使用 `bun scripts/cli.ts gh issue comment create 390 --repo pikasTech/unidesk --body-stdin` 追加进度、卡点和验收证据。
 
 ## Required Reading
 
@@ -30,6 +30,7 @@ description: UniDesk YAML-first 运维正规化技能。用户提到 ymal-first/
 - 受控 CLI 输出只能披露对象名、key 名、sourceRef、targetKey、缺失项、fingerprint、字节数和执行摘要；不得打印 base64 payload、解码值、完整 DSN、API key 或可复制凭据。
 - 不做新的全局大 orchestrator。优先保留 domain CLI，把公共能力抽到 ops helper，domain CLI 只表达领域动作。
 - 不为了“防回归”新增合同测试、重型 preflight、历史 guard 或 feature flag。旧门禁阻碍最新 ymal-first 目标时，优先拆除。
+- 对已经冻结范围的正规化 issue，新发现事项只能归入 `must-fix-in-current-plan`、`keep-domain-special` 或 `parked-out-of-scope`；不得因为新 grep 命中继续追加阶段。
 
 ## Workflow
 
@@ -41,6 +42,7 @@ description: UniDesk YAML-first 运维正规化技能。用户提到 ymal-first/
 6. 抽公共 ops primitives：在增加新 service 分支前，优先复用或扩展公共 helper。
 7. 保持 domain CLI 薄：`platform-infra`、`server`、`gc`、`agentrun`、`hwlab` 等入口只组合 YAML、helper 和执行动作，不复制底层 Kubernetes/FRP/Caddy/Secret 逻辑。
 8. 验证原入口：CLI/config 改动默认只跑语法、help/命令形态、plan/dry-run 或对应 sync/validate；涉及真实运行面的收口要跑原 CLI 入口，不新增合同测试。
+9. 有限收口：当 issue 已经冻结阶段，完成当前阶段后只更新父 issue 的进展和下一固定阶段；不要把候选扫描结果转成新的 Round。
 
 ## Common Refactor Targets
 

docs/reference/yaml-first-ops.md

@@ -117,6 +117,12 @@ When adding YAML-first ops to an existing domain, follow this order:
 
 Large domain command files must be split by responsibility before receiving more operational logic. Typical split boundaries are target resolution, manifest rendering, Secret sync, public exposure, database bridge, rollout, probes, cleanup and status summarization.
 
+## Finite Governance Slices
+
+YAML-first cleanup work must not become an open-ended sequence of rounds. Once an issue is used to close a broad normalization area, freeze a bounded phase list before implementation and keep all child issues inside that list. New findings after the freeze must be classified into the existing scope, kept as domain-specific differences, or parked out of scope; they must not create another phase merely because a search found more candidates.
+
+A shared helper extraction stops when the repeated mechanism has a stable helper, the remaining differences are true domain behavior, or the remaining candidates are outside the frozen scope. Do not continue extracting only to make every domain file look identical. The final audit should list completed changes, kept domain differences, parked risks and validation evidence, then close the issue instead of opening a follow-up round by default.
+
 ## Anti-Patterns
 
 Avoid these patterns:
@@ -131,6 +137,7 @@ Avoid these patterns:
 - writing long-term docs that duplicate current YAML values as prose
 - using contract tests or hidden guards to freeze policy values that should remain YAML-controlled
 - preserving legacy command branches after the latest YAML-first path supersedes them
+- extending a frozen cleanup issue by appending new rounds instead of classifying discoveries as in-scope, domain-specific or parked
 
 ## Documentation Boundary