현재 작업 전체 반영

AGENT.md

@@ -27,6 +27,28 @@ SSOT [`docs/dev_dashboard.html`](./docs/dev_dashboard.html). 동작/구조 변
 
 > **"OS·셸·경로·도구를 확정한 뒤에 실행한다. 추정으로 시작하지 않는다."**
 
+### PowerShell 5.1 기본 실행 규칙
+
+- 시작 시 필요하면 `$ErrorActionPreference='Stop'`,
+  `[Console]::OutputEncoding=[System.Text.UTF8Encoding]::new($false)`,
+  `$OutputEncoding=[System.Text.UTF8Encoding]::new($false)`를 먼저 둔다.
+- PowerShell 7/Bash 문법 금지: `? :`, `??`, `&&`, `||`, `ForEach-Object -Parallel`,
+  heredoc(`<<EOF`), `FOO=bar command`. 명시적 `if/else`, `$env:FOO='bar'`를 쓴다.
+- 제어문은 파이프라인 값이 아니다. `foreach { } | ...` 대신
+  `& { foreach (...) { ... } } | ...` 형태로 감싼다.
+- 경로는 `-LiteralPath`/`Resolve-Path -LiteralPath`/`Join-Path`로 처리한다.
+  한글·공백 경로는 외부 CLI 전달 전 ASCII 임시 경로 복사를 우선 검토한다.
+- Windows PowerShell 5.1의 `-Encoding UTF8`은 BOM을 쓴다. UTF-8 no BOM이 필요하면
+  `[IO.File]::WriteAllText($path,$text,[Text.UTF8Encoding]::new($false))`를 쓴다.
+- 네이티브 exe는 문자열 조립 대신 `& $exe @args`로 호출하고 `$LASTEXITCODE`를 확인한다.
+  stderr를 `2>&1`로 합치지 말고 필요하면 stdout/stderr를 분리 캡처한다.
+- JSON API는 `Invoke-RestMethod`/`Invoke-WebRequest`를 우선 사용한다. 진짜 curl은
+  `curl.exe`로 호출한다.
+- 인라인 Python/Node가 BOM/인용 문제를 내면 `python -c`, UTF-8 no BOM 임시 파일,
+  base64 전달을 사용한다. Python은 필요 시 `PYTHONUTF8=1`, `python -X utf8`.
+- `Start-Process`는 필요할 때만 쓰고 `-Wait -PassThru`로 ExitCode와 산출물을 검증한다.
+  GUI 런처 detach 여부를 별도로 확인한다.
+
 ---
 
 ## 규칙 1 — 증거 정직성