fix(best-practices): restore canonical content, dedupe, sync script, spec exemplar

- best-practices/v1: replace 9 stale symlinks (into planning/v1) with real files
  synced byte-identical from the canonical best-practices project; add INDEX.md,
  scripting.md, mechanical-test-generation.md (canonical had drifted heavily,
  e.g. api-design.md 463->807 lines)
- planning/v1: delete duplicated best-practices/ copy (requires: inheritance
  confirmed via spec/harness.md HC-1/HC-7)
- scripts/sync-best-practices.sh: idempotent re-sync from canonical checkout
- code-methodology/v1: INDEX.md + scripting.md references now resolve; point
  test-writing tasks at mechanical-test-generation.md
- spec-writing/v1: worked spec exemplar (module layout table, Why: lines, exact
  error messages, parametrize pattern table) + CLAUDE.md pointer + mount entry

scripts/sync-best-practices.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# Run after /distill-best-practices updates the canonical repo; then commit the CRS
+# and PUT the attachment to force reload.
+#
+# Syncs the enumerated best-practices docs from the canonical
+# ~/dev/claude/projects/best-practices/ repo into this repo's harness context
+# directory/directories. Prints a per-file changed/unchanged summary.
+#
+# Usage: scripts/sync-best-practices.sh
+set -euo pipefail
+
+# ── Colors ────────────────────────────────────────────────────────────────
+if [[ -t 1 ]]; then
+  C_GREEN=$'\033[0;32m'
+  C_YELLOW=$'\033[0;33m'
+  C_RED=$'\033[0;31m'
+  C_RESET=$'\033[0m'
+else
+  C_GREEN=""
+  C_YELLOW=""
+  C_RED=""
+  C_RESET=""
+fi
+
+# ── Paths ─────────────────────────────────────────────────────────────────
+CANONICAL_DIR="${HOME}/dev/claude/projects/best-practices"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+# Destination context dirs that carry a synced copy of the docs.
+# best-practices/v1 is the canonical mount target; add further dirs here only
+# if a future context deliberately keeps its own synced copy (see SYNC-NOTE.md
+# convention) rather than relying on harness `requires:` inheritance.
+DEST_DIRS=(
+  "${REPO_ROOT}/harnesses/contexts/best-practices/v1/best-practices"
+)
+
+# Docs to sync (without .md extension).
+DOCS=(
+  api-design
+  database-selection
+  docker
+  kubernetes
+  llm-code-security
+  secrets-management
+  security-architecture
+  spec-driven-development
+  test-driven-development
+  scripting
+  mechanical-test-generation
+)
+
+# ── Preconditions ────────────────────────────────────────────────────────
+if [[ ! -d "${CANONICAL_DIR}" ]]; then
+  echo "${C_RED}ERROR: canonical best-practices dir not found: ${CANONICAL_DIR}${C_RESET}" >&2
+  exit 1
+fi
+
+changed_count=0
+unchanged_count=0
+missing_count=0
+
+for dest_dir in "${DEST_DIRS[@]}"; do
+  mkdir -p "${dest_dir}"
+  echo "== Syncing into ${dest_dir#"${REPO_ROOT}"/} =="
+
+  for doc in "${DOCS[@]}"; do
+    src="${CANONICAL_DIR}/${doc}.md"
+    dst="${dest_dir}/${doc}.md"
+
+    if [[ ! -f "${src}" ]]; then
+      echo "  ${C_RED}MISSING${C_RESET}   ${doc}.md (not found in canonical repo)"
+      missing_count=$((missing_count + 1))
+      continue
+    fi
+
+    if [[ -f "${dst}" ]] && cmp -s "${src}" "${dst}"; then
+      echo "  ${C_YELLOW}unchanged${C_RESET} ${doc}.md"
+      unchanged_count=$((unchanged_count + 1))
+    else
+      cp "${src}" "${dst}"
+      echo "  ${C_GREEN}changed${C_RESET}   ${doc}.md"
+      changed_count=$((changed_count + 1))
+    fi
+  done
+done
+
+echo
+echo "Summary: ${C_GREEN}${changed_count} changed${C_RESET}, ${C_YELLOW}${unchanged_count} unchanged${C_RESET}, ${C_RED}${missing_count} missing${C_RESET}"
+
+if [[ "${missing_count}" -gt 0 ]]; then
+  echo "${C_RED}One or more docs were missing from the canonical repo — check DOCS list and canonical filenames.${C_RESET}" >&2
+  exit 1
+fi
+
+exit 0