krino: planning — chains, placeholders, conflicts, JSON

1 files changed, 12 insertions, 1 deletions

diff --git a/docs/design.md b/docs/design.md
index 888ab34..092738a 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -313,8 +313,19 @@ When the target already exists:
 A `copy` whose target has identical content is skipped as "already there",
 whatever the policy, so a backup rule can run every time.
 
+A step whose target is the file itself — a rule whose `DEST` resolves to the
+directory the file already sits in, or a `rename` to the name it already has —
+is skipped as "already there" as well, whatever the policy. Without that the
+file's own existence would read as a conflict with itself and the plan would
+rename it to `stem_1` on every run.
+
 Conflicts between files in the same plan are resolved when planning, so the
-plan shows final names. The executor re-checks at execution time; if the
+plan shows final names. An in-plan claim is never displaced: when `overwrite`
+finds a target another step of the same plan has already claimed, it takes the
+next free name instead, because that path will hold the other step's output by
+the time either runs, and displacing it would destroy that step's result. The
+claim set spans the whole run, so two configured directories cannot plan the
+same final name. The executor re-checks at execution time; if the
 name has to change, the log records the actual name.
 
 ## 8. Plan, review, approval