fix(#4096): honor --dry-run in todo complete and write completion keys inside the frontmatter fence (#4325)

* fix(#4096): honor --dry-run in todo complete and upsert completion keys inside the frontmatter fence

* review(#4096): tighten todo complete flag rejection to any dash-prefixed token

* chore(#4096): backfill PR number in changeset

---------

Co-authored-by: sim <sim@local>

docs/CLI-TOOLS.md

@@ -1161,8 +1161,17 @@ active window are still outstanding.
 
 ```bash
 # Complete a todo
-node gsd-tools.cjs todo complete <filename>
+node gsd-tools.cjs todo complete <filename> [--dry-run]
+```
 
+`--dry-run` previews the completion (a `dry_run`/`would_*` JSON payload naming
+the source, the destination, and the frontmatter keys it would set) without
+moving the file or touching anything on disk. A real completion moves the todo
+from `todos/pending/` to `todos/completed/` and upserts `completed:` and
+`status: completed` inside the file's frontmatter block. Unknown flags are
+rejected loudly.
+
+```bash
 # UAT audit — scan all phases for unresolved items
 node gsd-tools.cjs audit-uat
 

docs/ja-JP/CLI-TOOLS.md

@@ -396,7 +396,7 @@ node gsd-tools.cjs progress [json|table|bar]
 node gsd-tools.cjs progress --json
 
 # TODO を完了にする
-node gsd-tools.cjs todo complete <filename>
+node gsd-tools.cjs todo complete <filename> [--dry-run]
 
 # UAT 監査 — 全フェーズの未解決項目をスキャン
 node gsd-tools.cjs audit-uat

docs/ko-KR/CLI-TOOLS.md

@@ -396,7 +396,7 @@ node gsd-tools.cjs progress [json|table|bar]
 node gsd-tools.cjs progress --json
 
 # 할 일 완료
-node gsd-tools.cjs todo complete <filename>
+node gsd-tools.cjs todo complete <filename> [--dry-run]
 
 # UAT 감사 — 모든 단계에서 미해결 항목 스캔
 node gsd-tools.cjs audit-uat

docs/pt-BR/CLI-TOOLS.md

@@ -398,7 +398,7 @@ node gsd-tools.cjs progress [json|table|bar]
 node gsd-tools.cjs progress --json
 
 # Conclui uma tarefa
-node gsd-tools.cjs todo complete <filename>
+node gsd-tools.cjs todo complete <filename> [--dry-run]
 
 # Auditoria UAT — verifica todas as fases em busca de itens não resolvidos
 node gsd-tools.cjs audit-uat

docs/zh-CN/CLI-TOOLS.md

@@ -396,7 +396,7 @@ node gsd-tools.cjs progress [json|table|bar]
 node gsd-tools.cjs progress --json
 
 # 完成待办事项
-node gsd-tools.cjs todo complete <filename>
+node gsd-tools.cjs todo complete <filename> [--dry-run]
 
 # UAT 审计——扫描所有阶段的未解决事项
 node gsd-tools.cjs audit-uat