docs: record retirement — superseded by j4k-align

.oxfmtrc.json

@@ -11,6 +11,7 @@
     ".clawpatch/",
     ".codex/",
     "AGENTS.md",
-    "CLAUDE.md"
+    "CLAUDE.md",
+    "archive/**"
   ]
 }

AGENTS.md

@@ -6,6 +6,46 @@ Before taking any action, read @README.md for project context.
 
 Use `askpplx` for real-time web search via Perplexity. Verify external facts—documentation, API behavior, library versions, best practices—before acting on them. A lookup costs far less than debugging hallucinated code. Run `npx -y askpplx --help` if unsure of the available options.
 
+# Rule: Safe Command Execution
+
+## Store commands in arrays, not strings
+
+When Bash expands a string variable, quotes inside become literal characters and whitespace triggers word splitting:
+
+```bash
+# BAD: quotes are literal, spaces split words
+CMD="echo \"hello world\""
+$CMD  # outputs: "hello world" (with literal quotes)
+
+# GOOD: array preserves argument boundaries
+CMD=(echo "hello world")
+"${CMD[@]}"  # outputs: hello world
+```
+
+## Never interpolate variables into shell strings
+
+Variables interpolated into shell strings — `sh -c`, `bash -c`, `eval`, `ssh host` — are reparsed by the shell. Characters like `$(...)`, backticks, or `;` in the value execute as code, a classic injection vector:
+
+```bash
+# BAD: if VAR contains $(malicious), it executes
+sh -c "$VAR --write"
+
+# GOOD: direct execution, no shell interpretation
+"${CMD[@]}" --write
+
+# GOOD: with xargs, execute the array directly
+find . -name '*.js' -print0 | xargs -0 "${CMD[@]}" --write --
+```
+
+When you need shell features (pipes, redirects), use the `exec "$@"` pattern to pass arguments as positional parameters instead of interpolating them:
+
+```bash
+# GOOD: arguments passed as $@, not interpolated into the string
+xargs -0 sh -c 'exec "$@"' _ "${CMD[@]}" --write --
+```
+
+The `_` occupies `$0` (the script name), leaving `$@` for the command and arguments. Any string works as the placeholder; `_` is conventional.
+
 # Rule: Avoid Leaky Abstractions
 
 Design interfaces around what callers need, not how the system works internally. An abstraction is leaky when using it correctly requires knowledge of underlying storage, infrastructure, or error behavior. Keep signatures consistent, return domain types instead of backend artifacts, and inject infrastructure dependencies through constructors rather than method parameters.
@@ -331,7 +371,7 @@ For Node.js 22.6–22.17, use `--experimental-strip-types`. Older versions requi
 
 # Rule: Use `repoq` for Repository Queries
 
-Use `repoq` for reading repository state instead of piping `git` or the forge CLI through `awk`/`jq`/`grep`. Each command handles edge cases (detached HEAD, unborn branches, missing auth) and returns validated JSON. Use raw `git` for commit/push/merge, and the repo's forge CLI for forge-side mutations (PRs, issues, releases) — `gh` for GitHub or `fgj` for Forgejo, per the detected provider. Run `npx -y repoq --help` if unsure of the available subcommands.
+Use `repoq` for reading repository state instead of piping `git` or the forge CLI through `awk`/`jq`/`grep`. Each command handles edge cases (detached HEAD, unborn branches, missing auth) and returns validated JSON. Use raw `git` for commit/push/merge, and the repo's forge CLI for forge-side mutations (PRs, issues, releases) — `gh` for GitHub or `fgj` for Forgejo, per the detected provider. Run `npx -y repoq@latest --help` if unsure of the available subcommands; the explicit tag prevents `npx` from reusing a stale cached release.
 
 # Rule: Discriminated Unions
 

README.md

@@ -1,5 +1,11 @@
 # sync-rules
 
+> **⚠️ Retired (2026-07-29).** This tool is superseded by **j4k-align**
+> (`j4k/align` on `code.j4k.dev`), which now generates every agent instruction
+> file. Do not install or run `sync-rules` — a run would overwrite
+> j4k-align-generated files with this repository's stale corpus rendering.
+> See [`RETIREMENT.md`](./RETIREMENT.md) for the full retirement record.
+
 A CLI tool to synchronize AI coding assistant rule files between a central repository and multiple projects.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

RETIREMENT.md

@@ -0,0 +1,23 @@
+# sync-rules is retired
+
+Retired 2026-07-29. Agent instruction files (`AGENTS.md`, `CLAUDE.md`, the
+workstation globals) are now generated by **j4k-align** (`j4k/align` on
+`code.j4k.dev`) via `j4k-align agents --fix`, from the rule corpus in that
+repository's `rules/` directory. The full migration record is
+`docs/sync-rules-retirement-plan.md` in `j4k/align`.
+
+- Deployed version read from the npm registry at cutover: **5.11.5**.
+- The final `config.json` (verbatim from
+  `~/Library/Preferences/sync-rules/config.json` at retirement) is archived at
+  [`archive/config.json`](./archive/config.json).
+- The last sync-rules renders of the five workstation global files are archived
+  under [`archive/global-targets/`](./archive/global-targets/). These are the
+  bytes live on the workstation immediately before the j4k-align regeneration
+  (the 2026-07-27 corpus re-sync render); the Phase-0 baseline tar named by the
+  retirement plan was no longer present on the retiring machine, and its
+  per-file hashes remain recorded in j4k-align's `docs/pre-cutover-hashes.json`.
+
+Phase 5 of the retirement plan deprecates the npm package on the registry
+(never unpublishing it) and archives this repository once this record is on
+`main`. Do not run the CLI — a run would overwrite j4k-align-generated files
+with this repository's stale corpus rendering.