docs: bound YAML-first cleanup stages
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user