Squashed 'docs/standards/playbook/' content from commit e504a68

git-subtree-dir: docs/standards/playbook
git-subtree-split: e504a689dcf2e2fdeeb64097930347d504e68f5f

scripts/sync_standards.bat

@@ -0,0 +1,223 @@
+@echo off
+setlocal enabledelayedexpansion
+
+rem Sync standards snapshot to project root.
+rem - Copies <snapshot>\.agents\<AGENTS_NS> -> <project-root>\.agents\<AGENTS_NS>
+rem - Updates <project-root>\.gitattributes (managed block by default)
+rem Existing targets are backed up before overwrite.
+rem
+rem Multi rulesets:
+rem   sync_standards.bat tsl cpp
+rem Notes:
+rem - When syncing multiple rulesets, .gitattributes is synced only once (first ruleset).
+
+set "SCRIPT_DIR=%~dp0"
+for /f "delims=" %%R in ('git -C "%SCRIPT_DIR%" rev-parse --show-toplevel 2^>nul') do set "ROOT=%%R"
+if "%ROOT%"=="" set "ROOT=%cd%"
+for %%I in ("%ROOT%") do set "ROOT=%%~fI"
+
+for %%I in ("%SCRIPT_DIR%..") do set "SRC=%%~fI"
+set "AGENTS_SRC_ROOT=%SRC%\.agents"
+set "GITATTR_SRC=%SRC%\.gitattributes"
+set "AGENTS_NS=%AGENTS_NS%"
+if "%AGENTS_NS%"=="" set "AGENTS_NS=tsl"
+echo %AGENTS_NS%| findstr /r "[\\/]" >nul && (
+  echo ERROR: invalid AGENTS_NS=%AGENTS_NS%
+  exit /b 1
+)
+echo %AGENTS_NS%| findstr /c:".." >nul && (
+  echo ERROR: invalid AGENTS_NS=%AGENTS_NS%
+  exit /b 1
+)
+set "AGENTS_ROOT=%ROOT%\.agents"
+set "AGENTS_DST=%AGENTS_ROOT%\%AGENTS_NS%"
+set "GITATTR_DST=%ROOT%\.gitattributes"
+set "SYNC_GITATTR_MODE=%SYNC_GITATTR_MODE%"
+if "%SYNC_GITATTR_MODE%"=="" set "SYNC_GITATTR_MODE=block"
+
+rem Multi rulesets: only on outer invocation.
+if "%SYNC_STANDARDS_INNER%"=="" (
+  if not "%~1"=="" (
+    set "FIRST=1"
+    set "SYNC_FIRST=%SYNC_GITATTR_MODE%"
+    for %%L in (%*) do (
+      if "!FIRST!"=="1" (
+        set "FIRST=0"
+        set "SYNC_STANDARDS_INNER=1"
+        set "AGENTS_NS=%%~L"
+        set "SYNC_GITATTR_MODE=!SYNC_FIRST!"
+        call "%~f0"
+      ) else (
+        set "SYNC_STANDARDS_INNER=1"
+        set "AGENTS_NS=%%~L"
+        set "SYNC_GITATTR_MODE=skip"
+        call "%~f0"
+      )
+    )
+    exit /b 0
+  )
+)
+
+set "AGENTS_SRC=%AGENTS_SRC_ROOT%\%AGENTS_NS%"
+if not exist "%AGENTS_SRC%" (
+  rem Backward-compatible fallback: older snapshots used <snapshot>\.agents\* directly.
+  if exist "%AGENTS_SRC_ROOT%\index.md" if exist "%AGENTS_SRC_ROOT%\auth.md" (
+    set "AGENTS_SRC=%AGENTS_SRC_ROOT%"
+  ) else (
+    echo ERROR: Standards snapshot not found at "%AGENTS_SRC%".
+    echo Hint: set AGENTS_NS to one of the subdirs under "%AGENTS_SRC_ROOT%" (e.g. tsl/cpp).
+    exit /b 1
+  )
+)
+if not exist "%AGENTS_SRC%" (
+  echo ERROR: Standards snapshot not found at "%AGENTS_SRC%".
+  echo Run: git subtree add --prefix docs/standards/playbook ^<standards-url^> ^<branch^> --squash
+  exit /b 1
+)
+
+if /I "%SRC%"=="%ROOT%" (
+  echo Skip: snapshot root equals project root.
+  goto AfterGitAttr
+)
+
+if not exist "%AGENTS_ROOT%" mkdir "%AGENTS_ROOT%"
+
+if exist "%AGENTS_DST%" (
+  set "RAND=%RANDOM%"
+  pushd "%AGENTS_ROOT%"
+  ren "%AGENTS_NS%" "%AGENTS_NS%.bak.!RAND!"
+  popd
+  echo Backed up existing %AGENTS_NS% agents -> %AGENTS_NS%.bak.!RAND!
+)
+
+xcopy "%AGENTS_SRC%\\*" "%AGENTS_DST%\\" /e /i /y >nul
+if errorlevel 1 (
+  echo ERROR: failed to copy .agents
+  exit /b 1
+)
+
+echo Synced .agents\%AGENTS_NS% from standards.
+
+if not exist "%AGENTS_ROOT%\index.md" (
+  > "%AGENTS_ROOT%\index.md" echo # .agents（多语言）
+  >> "%AGENTS_ROOT%\index.md" echo.
+  >> "%AGENTS_ROOT%\index.md" echo 本目录用于存放仓库级/语言级的代理规则集。
+  >> "%AGENTS_ROOT%\index.md" echo.
+  >> "%AGENTS_ROOT%\index.md" echo 建议约定：
+  >> "%AGENTS_ROOT%\index.md" echo.
+  >> "%AGENTS_ROOT%\index.md" echo - `.agents/tsl/`：TSL 相关规则集（由 `sync_standards.*` 同步；适用于 `.tsl`/`.tsf`）
+  >> "%AGENTS_ROOT%\index.md" echo - `.agents/cpp/`：C++ 相关规则集（由 `sync_standards.*` 同步；适用于 C++23/Modules）
+  >> "%AGENTS_ROOT%\index.md" echo - `.agents/python/` 等：其他语言的规则集（按需增加）
+  >> "%AGENTS_ROOT%\index.md" echo.
+  >> "%AGENTS_ROOT%\index.md" echo 规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。
+  >> "%AGENTS_ROOT%\index.md" echo.
+  >> "%AGENTS_ROOT%\index.md" echo 入口建议从：
+  >> "%AGENTS_ROOT%\index.md" echo.
+  >> "%AGENTS_ROOT%\index.md" echo - `.agents/tsl/index.md`（TSL 规则集入口）
+  >> "%AGENTS_ROOT%\index.md" echo - `.agents/cpp/index.md`（C++ 规则集入口）
+  >> "%AGENTS_ROOT%\index.md" echo - `docs/standards/playbook/docs/`（人类开发规范快照：`tsl/`、`cpp/`、`python/`、`common/`）
+  echo Created .agents\index.md
+)
+
+:SyncGitAttr
+if exist "%GITATTR_SRC%" (
+  if /I "%SYNC_GITATTR_MODE%"=="skip" (
+    echo Skip: .gitattributes sync ^(SYNC_GITATTR_MODE=skip^).
+    goto AfterGitAttr
+  )
+
+  if /I "%SYNC_GITATTR_MODE%"=="overwrite" (
+    for %%I in ("%GITATTR_SRC%") do set "GITATTR_SRC_F=%%~fI"
+    for %%I in ("%GITATTR_DST%") do set "GITATTR_DST_F=%%~fI"
+    if /I "!GITATTR_SRC_F!"=="!GITATTR_DST_F!" (
+      echo Skip: .gitattributes source equals destination.
+      goto AfterGitAttr
+    )
+
+    if exist "%GITATTR_DST%" (
+      set "RAND=%RANDOM%"
+      set "BAK_NAME=.gitattributes.bak.!RAND!"
+      ren "%GITATTR_DST%" "!BAK_NAME!"
+      echo Backed up existing .gitattributes -> !BAK_NAME!
+    )
+    copy /y "%GITATTR_SRC%" "%GITATTR_DST%" >nul
+    echo Synced .gitattributes from standards ^(overwrite^).
+    goto AfterGitAttr
+  )
+
+  if /I not "%SYNC_GITATTR_MODE%"=="block" (
+    echo ERROR: invalid SYNC_GITATTR_MODE=%SYNC_GITATTR_MODE% ^(use block^|overwrite^|skip^) 
+    exit /b 1
+  )
+
+  rem block mode: maintain a managed block inside the destination file
+  set "BEGIN=# BEGIN playbook .gitattributes"
+  set "END=# END playbook .gitattributes"
+  set "BEGIN_OLD=# BEGIN tsl-playbook .gitattributes"
+  set "END_OLD=# END tsl-playbook .gitattributes"
+  set "TMP_FILE=%TEMP%\\gitattributes.%RANDOM%.tmp"
+
+  if exist "%GITATTR_DST%" (
+    set "RAND=%RANDOM%"
+    set "BAK_NAME=.gitattributes.bak.!RAND!"
+    ren "%GITATTR_DST%" "!BAK_NAME!"
+    echo Backed up existing .gitattributes -> !BAK_NAME!
+    set "DST_IN=%ROOT%\\!BAK_NAME!"
+  ) else (
+    set "DST_IN="
+  )
+
+  set "IN_BLOCK=0"
+  set "DONE=0"
+
+  if not "%DST_IN%"=="" (
+    > "!TMP_FILE!" (
+      for /f "usebackq delims=" %%L in ("!DST_IN!") do (
+        set "LINE=%%L"
+        if "!LINE!"=="%BEGIN%" (
+          if "!DONE!"=="0" (
+            echo %BEGIN%
+            type "%GITATTR_SRC%"
+            echo %END%
+            set "DONE=1"
+          )
+          set "IN_BLOCK=1"
+        ) else if "!LINE!"=="%BEGIN_OLD%" (
+          if "!DONE!"=="0" (
+            echo %BEGIN%
+            type "%GITATTR_SRC%"
+            echo %END%
+            set "DONE=1"
+          )
+          set "IN_BLOCK=1"
+        ) else if "!LINE!"=="%END%" (
+          set "IN_BLOCK=0"
+        ) else if "!LINE!"=="%END_OLD%" (
+          set "IN_BLOCK=0"
+        ) else (
+          if "!IN_BLOCK!"=="0" echo(!LINE!
+        )
+      )
+      if "!DONE!"=="0" (
+        echo.
+        echo %BEGIN%
+        type "%GITATTR_SRC%"
+        echo %END%
+      )
+    )
+  ) else (
+    > "!TMP_FILE!" (
+      echo %BEGIN%
+      type "%GITATTR_SRC%"
+      echo %END%
+    )
+  )
+
+  copy /y "!TMP_FILE!" "%GITATTR_DST%" >nul
+  del /q "!TMP_FILE!" >nul 2>nul
+  echo Updated .gitattributes from standards ^(managed block^).
+)
+
+:AfterGitAttr
+echo Done.
+endlocal

scripts/sync_standards.ps1

@@ -0,0 +1,179 @@
+# Sync standards snapshot to project root.
+# - Copies <snapshot>/.agents/<AGENTS_NS> -> <project-root>/.agents/<AGENTS_NS>
+# - Updates <project-root>/.gitattributes (managed block by default)
+# Existing targets are backed up before overwrite.
+[CmdletBinding()]
+param(
+  # Sync multiple rulesets in one run:
+  #   -Langs tsl,cpp
+  #   -Langs @("tsl","cpp")
+  [Parameter(Mandatory = $false)]
+  [string[]]$Langs
+)
+
+$ErrorActionPreference = "Stop"
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$Src = (Resolve-Path (Join-Path $ScriptDir "..")).Path
+
+$Root = (git -C $ScriptDir rev-parse --show-toplevel 2>$null)
+if (-not $Root) { $Root = (Get-Location).Path }
+$Root = (Resolve-Path $Root).Path
+
+$AgentsSrcRoot = Join-Path $Src ".agents"
+$GitAttrSrc = Join-Path $Src ".gitattributes"
+
+if (-not (Test-Path $AgentsSrcRoot)) {
+  throw "Standards snapshot not found at $AgentsSrcRoot. Run: git subtree add --prefix docs/standards/playbook <url> <branch> --squash"
+}
+
+$timestamp = Get-Date -Format "yyyyMMddHHmmss"
+
+# Multi rulesets: only on the outer invocation.
+if (-not $env:SYNC_STANDARDS_INNER -and $Langs -and $Langs.Count -gt 0) {
+  $oldInner = $env:SYNC_STANDARDS_INNER
+  $oldAgentsNs = $env:AGENTS_NS
+  $oldMode = $env:SYNC_GITATTR_MODE
+
+  $syncModeFirst = $env:SYNC_GITATTR_MODE
+  if (-not $syncModeFirst) { $syncModeFirst = "block" }
+
+  $first = $true
+  foreach ($ns in $Langs) {
+    if (-not $ns) { continue }
+
+    $env:SYNC_STANDARDS_INNER = "1"
+    $env:AGENTS_NS = $ns
+    if ($first) {
+      $first = $false
+      $env:SYNC_GITATTR_MODE = $syncModeFirst
+    } else {
+      $env:SYNC_GITATTR_MODE = "skip"
+    }
+
+    & $MyInvocation.MyCommand.Path
+  }
+
+  $env:SYNC_STANDARDS_INNER = $oldInner
+  $env:AGENTS_NS = $oldAgentsNs
+  $env:SYNC_GITATTR_MODE = $oldMode
+  exit 0
+}
+
+$AgentsNs = $env:AGENTS_NS
+if (-not $AgentsNs) { $AgentsNs = "tsl" }
+if ($AgentsNs -match '[\\/]' -or $AgentsNs -match '\.\.') {
+  throw "Invalid AGENTS_NS=$AgentsNs"
+}
+$AgentsSrc = Join-Path $AgentsSrcRoot $AgentsNs
+if (-not (Test-Path $AgentsSrc)) {
+  # Backward-compatible fallback: older snapshots used <snapshot>/.agents/* directly.
+  if ((Test-Path (Join-Path $AgentsSrcRoot "index.md")) -and (Test-Path (Join-Path $AgentsSrcRoot "auth.md"))) {
+    $AgentsSrc = $AgentsSrcRoot
+  } else {
+    throw "Agents ruleset not found: $AgentsSrc (set AGENTS_NS to one of the subdirs under $AgentsSrcRoot, e.g. tsl/cpp)."
+  }
+}
+$AgentsRoot = Join-Path $Root ".agents"
+$AgentsDst = Join-Path $AgentsRoot $AgentsNs
+
+if ($Src -ieq $Root) {
+  Write-Host "Skip: snapshot root equals project root."
+  Write-Host "Done."
+  exit 0
+}
+
+New-Item -ItemType Directory -Path $AgentsRoot -Force | Out-Null
+
+if (Test-Path $AgentsDst) {
+  $bak = (Join-Path $AgentsRoot "$AgentsNs.bak.$timestamp")
+  Move-Item $AgentsDst $bak
+  Write-Host "Backed up existing $AgentsNs agents -> $(Split-Path -Leaf $bak)"
+}
+
+New-Item -ItemType Directory -Path $AgentsDst -Force | Out-Null
+Copy-Item (Join-Path $AgentsSrc "*") $AgentsDst -Recurse -Force
+Write-Host "Synced .agents/$AgentsNs from standards."
+
+$AgentsIndex = Join-Path $AgentsRoot "index.md"
+if (-not (Test-Path $AgentsIndex)) {
+@'
+# .agents（多语言）
+
+本目录用于存放仓库级/语言级的代理规则集。
+
+建议约定：
+
+- `.agents/tsl/`：TSL 相关规则集（由 `sync_standards.*` 同步；适用于 `.tsl`/`.tsf`）
+- `.agents/cpp/`：C++ 相关规则集（由 `sync_standards.*` 同步；适用于 C++23/Modules）
+- `.agents/python/` 等：其他语言的规则集（按需增加）
+
+规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。
+
+入口建议从：
+
+- `.agents/tsl/index.md`（TSL 规则集入口）
+- `.agents/cpp/index.md`（C++ 规则集入口）
+- `docs/standards/playbook/docs/`（人类开发规范快照：`tsl/`、`cpp/`、`python/`、`common/`）
+'@ | Set-Content -Path $AgentsIndex -Encoding UTF8
+  Write-Host "Created .agents/index.md"
+}
+
+$GitAttrDst = Join-Path $Root ".gitattributes"
+if (Test-Path $GitAttrSrc) {
+  $mode = $env:SYNC_GITATTR_MODE
+  if (-not $mode) { $mode = "block" }
+  switch ($mode.ToLowerInvariant()) {
+    "skip" {
+      Write-Host "Skip: .gitattributes sync (SYNC_GITATTR_MODE=skip)."
+      break
+    }
+    "overwrite" {
+      if ($GitAttrSrc -ieq $GitAttrDst) {
+        Write-Host "Skip: .gitattributes source equals destination."
+        break
+      }
+      if (Test-Path $GitAttrDst) {
+        $bak = "$GitAttrDst.bak.$timestamp"
+        Move-Item $GitAttrDst $bak
+        Write-Host "Backed up existing .gitattributes -> $bak"
+      }
+      Copy-Item $GitAttrSrc $GitAttrDst -Force
+      Write-Host "Synced .gitattributes from standards (overwrite)."
+      break
+    }
+    "block" {
+      $begin = "# BEGIN playbook .gitattributes"
+      $end = "# END playbook .gitattributes"
+      $beginOld = "# BEGIN tsl-playbook .gitattributes"
+      $endOld = "# END tsl-playbook .gitattributes"
+      $src = Get-Content -Path $GitAttrSrc -Raw
+      $block = $begin + "`r`n" + $src.TrimEnd() + "`r`n" + $end + "`r`n"
+
+      $dst = ""
+      if (Test-Path $GitAttrDst) {
+        $bak = "$GitAttrDst.bak.$timestamp"
+        Move-Item $GitAttrDst $bak
+        Write-Host "Backed up existing .gitattributes -> $bak"
+        $dst = Get-Content -Path $bak -Raw
+      }
+
+      $pattern = "(?ms)^(" + [regex]::Escape($begin) + "|" + [regex]::Escape($beginOld) + ")\\R.*?^(" + [regex]::Escape($end) + "|" + [regex]::Escape($endOld) + ")\\R?"
+      if ($dst -and ($dst -match $pattern)) {
+        $new = [regex]::Replace($dst, $pattern, $block)
+      } elseif ($dst) {
+        $new = $dst.TrimEnd() + "`r`n`r`n" + $block
+      } else {
+        $new = $block
+      }
+
+      $new | Set-Content -Path $GitAttrDst -Encoding UTF8
+      Write-Host "Updated .gitattributes from standards (managed block)."
+      break
+    }
+    default {
+      throw "Invalid SYNC_GITATTR_MODE=$mode (use block|overwrite|skip)"
+    }
+  }
+}
+
+Write-Host "Done."

scripts/sync_standards.sh

@@ -0,0 +1,200 @@
+#!/usr/bin/env sh
+set -eu
+
+# Sync standards snapshot to project root.
+# - Copies <snapshot>/.agents/<AGENTS_NS> -> <project-root>/.agents/<AGENTS_NS>
+# - Updates <project-root>/.gitattributes (managed block by default)
+# Existing targets are backed up before overwrite.
+#
+# Multi rulesets:
+#   sh .../sync_standards.sh tsl cpp
+#   sh .../sync_standards.sh --langs tsl,cpp
+# Notes:
+# - When syncing multiple rulesets, .gitattributes is synced only once (first ruleset).
+
+SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)"
+SRC="$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd -P)"
+ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || pwd)"
+ROOT="$(CDPATH= cd -- "$ROOT" && pwd -P)"
+AGENTS_SRC_ROOT="$SRC/.agents"
+GITATTR_SRC="$SRC/.gitattributes"
+
+if [ ! -d "$AGENTS_SRC_ROOT" ]; then
+  echo "ERROR: Standards snapshot not found at $AGENTS_SRC_ROOT" >&2
+  echo "Run: git subtree add --prefix docs/standards/playbook <standards-url> <branch> --squash" >&2
+  exit 1
+fi
+
+timestamp="$(date +%Y%m%d%H%M%S 2>/dev/null || echo bak)"
+
+if [ "$SRC" = "$ROOT" ]; then
+  echo "Skip: snapshot root equals project root."
+  echo "Done."
+  exit 0
+fi
+
+# Parse multi rulesets only on the outer invocation.
+if [ "${SYNC_STANDARDS_INNER:-}" != "1" ]; then
+  langs=""
+  if [ "${1:-}" = "--langs" ]; then
+    langs="${2:-}"
+    shift 2
+  fi
+  if [ -z "${langs:-}" ] && [ "$#" -gt 0 ]; then
+    langs="$*"
+  fi
+  if [ -n "${langs:-}" ]; then
+    sync_mode_first="${SYNC_GITATTR_MODE:-block}"
+
+    first=1
+    old_ifs="${IFS}"
+    IFS=', '
+    set -- $langs
+    IFS="${old_ifs}"
+
+    for ns in "$@"; do
+      [ -n "$ns" ] || continue
+      if [ "$first" -eq 1 ]; then
+        first=0
+        SYNC_STANDARDS_INNER=1 AGENTS_NS="$ns" SYNC_GITATTR_MODE="$sync_mode_first" sh "$0"
+      else
+        SYNC_STANDARDS_INNER=1 AGENTS_NS="$ns" SYNC_GITATTR_MODE=skip sh "$0"
+      fi
+    done
+    exit 0
+  fi
+fi
+
+: "${AGENTS_NS:=tsl}"
+case "$AGENTS_NS" in
+  ""|*/*|*\\*|*..*)
+    echo "ERROR: invalid AGENTS_NS=$AGENTS_NS" >&2
+    exit 1
+    ;;
+esac
+
+AGENTS_SRC="$AGENTS_SRC_ROOT/$AGENTS_NS"
+if [ ! -d "$AGENTS_SRC" ]; then
+  # Backward-compatible fallback: older snapshots used <snapshot>/.agents/* directly.
+  if [ -f "$AGENTS_SRC_ROOT/index.md" ] && [ -f "$AGENTS_SRC_ROOT/auth.md" ]; then
+    AGENTS_SRC="$AGENTS_SRC_ROOT"
+  else
+    echo "ERROR: agents ruleset not found: $AGENTS_SRC" >&2
+    echo "Hint: set AGENTS_NS to one of the subdirs under $AGENTS_SRC_ROOT (e.g. tsl/cpp)." >&2
+    exit 1
+  fi
+fi
+
+AGENTS_ROOT="$ROOT/.agents"
+AGENTS_DST="$AGENTS_ROOT/$AGENTS_NS"
+mkdir -p "$AGENTS_ROOT"
+
+if [ -e "$AGENTS_DST" ]; then
+  mv "$AGENTS_DST" "$AGENTS_ROOT/$AGENTS_NS.bak.$timestamp"
+  echo "Backed up existing $AGENTS_NS agents -> $AGENTS_NS.bak.$timestamp"
+fi
+
+cp -R "$AGENTS_SRC" "$AGENTS_DST"
+echo "Synced .agents/$AGENTS_NS from standards."
+
+AGENTS_INDEX="$AGENTS_ROOT/index.md"
+if [ ! -f "$AGENTS_INDEX" ]; then
+  cat >"$AGENTS_INDEX" <<'EOF'
+# .agents（多语言）
+
+本目录用于存放仓库级/语言级的代理规则集。
+
+建议约定：
+
+- `.agents/tsl/`：TSL 相关规则集（由 `sync_standards.*` 同步；适用于 `.tsl`/`.tsf`）
+- `.agents/cpp/`：C++ 相关规则集（由 `sync_standards.*` 同步；适用于 C++23/Modules）
+- `.agents/python/` 等：其他语言的规则集（按需增加）
+
+规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。
+
+入口建议从：
+
+- `.agents/tsl/index.md`（TSL 规则集入口）
+- `.agents/cpp/index.md`（C++ 规则集入口）
+- `docs/standards/playbook/docs/`（人类开发规范快照：`tsl/`、`cpp/`、`python/`、`common/`）
+EOF
+  echo "Created .agents/index.md"
+fi
+
+echo "Synced agents ruleset to $AGENTS_DST."
+
+GITATTR_DST="$ROOT/.gitattributes"
+if [ -f "$GITATTR_SRC" ]; then
+  : "${SYNC_GITATTR_MODE:=block}"
+  case "$SYNC_GITATTR_MODE" in
+    skip)
+      echo "Skip: .gitattributes sync (SYNC_GITATTR_MODE=skip)."
+      ;;
+    overwrite)
+      if [ "$(CDPATH= cd -- "$(dirname -- "$GITATTR_SRC")" && pwd -P)/$(basename -- "$GITATTR_SRC")" = "$GITATTR_DST" ]; then
+        echo "Skip: .gitattributes source equals destination."
+      else
+        if [ -e "$GITATTR_DST" ]; then
+          mv "$GITATTR_DST" "$ROOT/.gitattributes.bak.$timestamp"
+          echo "Backed up existing .gitattributes -> .gitattributes.bak.$timestamp"
+        fi
+        cp "$GITATTR_SRC" "$GITATTR_DST"
+        echo "Synced .gitattributes from standards (overwrite)."
+      fi
+      ;;
+    block)
+      begin="# BEGIN playbook .gitattributes"
+      end="# END playbook .gitattributes"
+      begin_old="# BEGIN tsl-playbook .gitattributes"
+      end_old="# END tsl-playbook .gitattributes"
+
+      if [ -e "$GITATTR_DST" ]; then
+        mv "$GITATTR_DST" "$ROOT/.gitattributes.bak.$timestamp"
+        echo "Backed up existing .gitattributes -> .gitattributes.bak.$timestamp"
+      fi
+
+      tmp="${GITATTR_DST}.tmp.${timestamp}"
+      if [ -f "$ROOT/.gitattributes.bak.$timestamp" ]; then
+        src_dst="$ROOT/.gitattributes.bak.$timestamp"
+      else
+        src_dst=""
+      fi
+
+      if [ -n "$src_dst" ]; then
+        awk -v begin="$begin" -v end="$end" -v begin_old="$begin_old" -v end_old="$end_old" -v src="$GITATTR_SRC" '
+          function emit_src() {
+            print begin
+            while ((getline line < src) > 0) print line
+            close(src)
+            print end
+          }
+          BEGIN { in_block=0; done=0 }
+          $0 == begin || $0 == begin_old { in_block=1; if (!done) { emit_src(); done=1 } ; next }
+          $0 == end   || $0 == end_old   { in_block=0; next }
+          !in_block   { print }
+          END {
+            if (!done) {
+              if (NR > 0) print ""
+              emit_src()
+            }
+          }
+        ' "$src_dst" >"$tmp"
+      else
+        {
+          printf "%s\n" "$begin"
+          cat "$GITATTR_SRC"
+          printf "\n%s\n" "$end"
+        } >"$tmp"
+      fi
+
+      mv "$tmp" "$GITATTR_DST"
+      echo "Updated .gitattributes from standards (managed block)."
+      ;;
+    *)
+      echo "ERROR: invalid SYNC_GITATTR_MODE=$SYNC_GITATTR_MODE (use block|overwrite|skip)" >&2
+      exit 1
+      ;;
+  esac
+fi
+
+echo "Done."