fix(gx): enforce symlink parity pre-commit + document scripts layout convention (#553)

G5 — Symlink parity check now runs pre-commit
.githooks/pre-commit (the gitguardex local shim) now invokes
scripts/check-script-symlinks.sh before delegating to `gx hook run
pre-commit`. A contributor who accidentally replaces a paired symlink
with a regular file gets instant local feedback instead of waiting for
CI to fail minutes later. The check is guarded by an existence test on
scripts/check-script-symlinks.sh, so consumer repos (where that script
is not scaffolded) silently skip the parity step.

G6 — Document the scripts/ ↔ templates/scripts/ layout convention
A long comment above TEMPLATE_FILES in src/context.js spells out the
two patterns that coexist in this repo, eliminating the "which side is
canonical?" ambiguity that motivated G6:

  1. PAIRED files (10): tracked on both sides; scripts/<file> is a
     symlink into ../templates/scripts/<file> per PR #548. Edit the
     templates/ copy.
  2. SCAFFOLD-ONLY files: tracked only under templates/; scaffolded
     into gitignored scripts/<file> by `gx setup`. Edit the templates/
     copy.

Future contributors adding a new file know exactly which list to
update (check-script-symlinks.sh's required_symlinks vs the
multiagent-safety .gitignore block).

Verified G5 live: breaking a symlink and re-running the hook produces
the FAIL output + "aborting commit" exit 1, matching the CI behavior.

Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

.githooks/pre-commit

@@ -1,6 +1,21 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# When run inside the gitguardex repo itself, also enforce the
+# scripts/ <-> templates/scripts/ symlink parity invariant locally.
+# CI (.github/workflows/ci.yml) runs the same check; this gives
+# instant local feedback on broken symlinks instead of waiting for
+# the PR check to fail minutes later. Consumer repos don't have
+# scripts/check-script-symlinks.sh (it's not in the scaffold list),
+# so the test below silently noops there.
+hook_repo_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [[ -n "$hook_repo_root" && -x "${hook_repo_root}/scripts/check-script-symlinks.sh" ]]; then
+  if ! "${hook_repo_root}/scripts/check-script-symlinks.sh"; then
+    echo "[gitguardex-shim] scripts/<->templates/scripts/ symlink parity check failed; aborting commit." >&2
+    exit 1
+  fi
+fi
+
 if [[ -n "${GUARDEX_CLI_ENTRY:-}" ]]; then
   node_bin="${GUARDEX_NODE_BIN:-node}"
   exec "$node_bin" "$GUARDEX_CLI_ENTRY" 'hook' 'run' 'pre-commit' "$@"

openspec/changes/agent-claude-g5-g6-symlink-precommit-gitignore-cleanu-2026-05-11-12-34/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-11

openspec/changes/agent-claude-g5-g6-symlink-precommit-gitignore-cleanu-2026-05-11-12-34/notes.md

@@ -0,0 +1,16 @@
+# agent-claude-g5-g6-symlink-precommit-gitignore-cleanu-2026-05-11-12-34 (minimal / T1)
+
+Branch: `agent/<your-name>/<branch-slug>`
+
+Describe the change in a sentence or two. Commit message is the spec of record.
+
+## Handoff
+
+- Handoff: change=`agent-claude-g5-g6-symlink-precommit-gitignore-cleanu-2026-05-11-12-34`; branch=`agent/<your-name>/<branch-slug>`; scope=`TODO`; action=`continue this sandbox or finish cleanup after a usage-limit/manual takeover`.
+- Copy prompt: Continue `agent-claude-g5-g6-symlink-precommit-gitignore-cleanu-2026-05-11-12-34` on branch `agent/<your-name>/<branch-slug>`. Work inside the existing sandbox, review `openspec/changes/agent-claude-g5-g6-symlink-precommit-gitignore-cleanu-2026-05-11-12-34/notes.md`, continue from the current state instead of creating a new sandbox, and when the work is done run `gx branch finish --branch agent/<your-name>/<branch-slug> --base dev --via-pr --wait-for-merge --cleanup`.
+
+## Cleanup
+
+- [ ] Run: `gx branch finish --branch agent/<your-name>/<branch-slug> --base dev --via-pr --wait-for-merge --cleanup`
+- [ ] Record PR URL + `MERGED` state in the completion handoff.
+- [ ] Confirm sandbox worktree is gone (`git worktree list`, `git branch -a`).

src/context.js

@@ -137,6 +137,26 @@ function toDestinationPath(relativeTemplatePath) {
   throw new Error(`Unsupported template path: ${relativeTemplatePath}`);
 }
 
+// scripts/ ↔ templates/scripts/ layout convention (single source of truth):
+//
+// 1. PAIRED files (10): tracked on both sides; scripts/<file> is a symlink
+//    to ../templates/scripts/<file> per PR #548. See
+//    scripts/check-script-symlinks.sh for the exact list. CI + the
+//    .githooks/pre-commit shim both enforce that no symlink is ever
+//    replaced with a regular file. Edit only the templates/scripts/ copy;
+//    the symlink propagates.
+//
+// 2. SCAFFOLD-ONLY files (the 4 below + workflows + vscode extension):
+//    tracked only under templates/; scaffolded into gitignored
+//    scripts/<file> (or .githooks/<file>, etc.) by `gx setup`. Consumer
+//    repos receive a regular file copy at the destination; gitguardex
+//    itself receives the same copy and ignores it via the
+//    multiagent-safety .gitignore block. Edit only the templates/ copy.
+//
+// If a file you're about to add fits pattern (1), also add it to
+// scripts/check-script-symlinks.sh's required_symlinks list. If it fits
+// pattern (2), append the destination path to .gitignore's multiagent-
+// safety block (auto-managed by syncManagedGitignoreLines below).
 const TEMPLATE_FILES = [
   'scripts/agent-session-state.js',
   'scripts/guardex-docker-loader.sh',