dsh-plugin-guide 0.3.29 → 0.3.31

package/scripts/archive-discussions.ps1

@@ -1,162 +1,162 @@
-# dsh-plugin-guide 官方 GitHub Discussions 归档脚本（可复跑，幂等）
-# 输出: downloads/github/harness/discussions/
-#   list.json          全部讨论（title/body/category/answers/labels 等，正文即文档）
-#   comments-<n>.json  精选线程的全部评论（选择规则见下）
-#   _selection.tsv     精选线程清单
-#   README.md          分类统计 + 精选清单
-# 说明: GitHub REST API;未提供 Token 时走匿名配额(60/h,可能不够),建议
-#   $env:GH_TOKEN 或 -Token <token>(经典 PAT,只需 public_repo 读权限)。
-#   选择规则(与 08-14 首版覆盖度一致): Announcements 全部; Q&A/Ideas 评论>=1;
-#   General/Show and tell 评论>=3 且标题不含拉群/招聘/广告词。
-#   传输用 Invoke-WebRequest(而非 curl.exe 数组参数): PS 5.1 下 curl 数组参数
-#   的引号拆分会把 -H 头打碎,导致静默拿到错误对象——本脚本已规避该坑。
-# 参数: -OutDir <dir> 覆盖输出目录; -SkipComments 只刷新 list.json 不拉评论。
-param(
-  [string]$OutDir = '',
-  [string]$Repo = 'deepseek-ai/deepseek-harness',
-  [string]$Token = $env:GH_TOKEN,
-  [switch]$SkipComments
-)
-$ErrorActionPreference = 'Stop'
-$ProgressPreference = 'SilentlyContinue'
-if (-not $OutDir) { $OutDir = Join-Path (Split-Path $PSScriptRoot -Parent) 'downloads\github\harness\discussions' }
-New-Item -ItemType Directory -Force -Path $OutDir | Out-Null
-
-$headers = @{ 'User-Agent' = 'dsh-plugin-guide-research'; 'Accept' = 'application/vnd.github+json' }
-if ($Token) { $headers['Authorization'] = "Bearer $Token" }
-
-function Get-Api([string]$url) {
-  # 返回对象数组;失败/限流时抛错(带状态码),由调用方决定重试或中止。
-  try {
-    $resp = Invoke-WebRequest -Uri $url -Headers $headers -TimeoutSec 60 -UseBasicParsing
-  } catch {
-    $code = if ($_.Exception.Response) { [int]$_.Exception.Response.StatusCode } else { 0 }
-    throw "HTTP $code : $url"
-  }
-  $obj = $null
-  try { $obj = $resp.Content | ConvertFrom-Json } catch { throw "JSON parse failed: $url" }
-  if ($obj -is [System.Management.Automation.PSCustomObject] -and $obj.PSObject.Properties.Name -contains 'message') {
-    throw "API message '$($obj.message)' : $url"
-  }
-  return @($obj)
-}
-
-# ---- 1) 全量 list(按创建序分页;REST 的 direction 参数对 discussions 无效,只能从头翻到尾) ----
-$prevCount = 0
-if (Test-Path (Join-Path $OutDir 'list.json')) {
-  try { $prev = @((Get-Content (Join-Path $OutDir 'list.json') -Raw -Encoding UTF8 | ConvertFrom-Json)); $prevCount = $prev.Count } catch { $prevCount = 0 }
-}
-$all = @()
-$page = 1
-# REST /discussions caps at 5000 rows (50 pages x 100). The cap is explicit so a
-# silent truncation cannot be mistaken for a complete archive: the run reports
-# when it stops at the ceiling, and the README records the ceiling alongside the
-# GraphQL total_count (which is larger).
-$pageCap = 50
-while ($page -le $pageCap) {
-  $items = Get-Api "https://api.github.com/repos/$Repo/discussions?per_page=100&page=$page&sort=created"
-  if ($items.Count -eq 0) { Write-Output "page ${page}: 空页,列表结束"; break }
-  $all += $items
-  Write-Output ("page {0}: +{1} (累计 {2})" -f $page, $items.Count, $all.Count)
-  if ($items.Count -lt 100) { break }
-  $page++
-  Start-Sleep -Milliseconds 500
-}
-if ($all.Count -ge ($pageCap * 100)) {
-  Write-Output "WARN: 列表在第 $pageCap 页触顶(REST 5000 条上限)——归档为前 5000 条,非全量;更全的历史需按 GraphQL UPDATED_AT 分页补抓"
-}
-if ($all.Count -eq 0) { throw 'discussions 列表抓取失败(0 条)' }
-if ($prevCount -gt 0 -and $all.Count -lt [Math]::Floor($prevCount * 0.9)) {
-  throw "列表疑似缩水: 上次 $prevCount 条, 本次仅 $all.Count 条 —— 拒绝覆盖归档,请检查网络/配额后重跑"
-}
-
-# 按 number 去重(分页边界可能重复)
-$uniq = @{}
-foreach ($d in $all) { $uniq[[int]$d.number] = $d }
-$discs = @($uniq.Values | Sort-Object { [int]$_.number })
-$listPath = Join-Path $OutDir 'list.json'
-$discs | ConvertTo-Json -Depth 6 | Set-Content -Path $listPath -Encoding UTF8
-Write-Output "list.json: $($discs.Count) 条 -> $listPath"
-
-# ---- 2) 精选线程 + 评论 ----
-$sel = @()
-foreach ($d in $discs) {
-  $cat = $d.category.name
-  $c = [int]$d.comments
-  $t = [string]$d.title
-  $pick = $false
-  if ($cat -eq 'Announcements') { $pick = $true }
-  elseif ($cat -eq 'Q&A' -and $c -ge 1) { $pick = $true }
-  elseif ($cat -eq 'Ideas' -and $c -ge 1) { $pick = $true }
-  elseif (($cat -eq 'General' -or $cat -eq 'Show and tell') -and $c -ge 3) {
-    # 非社群拉群帖: 标题含拉群/扫码/加群/招聘/广告类词的不收
-    if ($t -notmatch '群|扫码|加群|招聘|内推|广告|投简历|纳新') { $pick = $true }
-  }
-  if ($pick) { $sel += $d }
-}
-$sel = @($sel | Sort-Object { [int]$_.number })
-Write-Output "精选线程: $($sel.Count) 条"
-
-if (-not $SkipComments) {
-  $n = 0
-  foreach ($d in $sel) {
-    $num = [int]$d.number
-    $comments = @()
-    $cp = 1
-    while ($cp -le 20) {
-      $ci = Get-Api "https://api.github.com/repos/$Repo/discussions/$num/comments?per_page=100&page=$cp"
-      if ($ci.Count -eq 0) { break }
-      $comments += $ci
-      if ($ci.Count -lt 100) { break }
-      $cp++
-      Start-Sleep -Milliseconds 300
-    }
-    $comments | ConvertTo-Json -Depth 6 | Set-Content -Path (Join-Path $OutDir "comments-$num.json") -Encoding UTF8
-    $n++
-    if ($n % 20 -eq 0) { Write-Output "comments: $n / $($sel.Count)" }
-    Start-Sleep -Milliseconds 200
-  }
-  Write-Output "comments: 完成 $n 个线程"
-  # 清掉列表里已不存在的旧 comments 文件
-  $keep = New-Object System.Collections.Generic.HashSet[string]
-  foreach ($d in $sel) { [void]$keep.Add("comments-$([int]$d.number).json") }
-  Get-ChildItem $OutDir -Filter 'comments-*.json' | Where-Object { -not $keep.Contains($_.Name) } | Remove-Item -Force
-} else {
-  Write-Output 'comments: 跳过(-SkipComments)'
-}
-
-# ---- 3) _selection.tsv 与 README.md ----
-$selLines = @('number' + "`t" + 'category' + "`t" + 'comments' + "`t" + 'title')
-foreach ($d in $sel) { $selLines += ("{0}`t{1}`t{2}`t{3}" -f $d.number, $d.category.name, $d.comments, ($d.title -replace "`t",' ')) }
-Set-Content -Path (Join-Path $OutDir '_selection.tsv') -Value $selLines -Encoding UTF8
-
-$cats = @{}
-foreach ($d in $discs) { $k = [string]$d.category.name; if (-not $cats.ContainsKey($k)) { $cats[$k] = 0 }; $cats[$k]++ }
-$utc = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')
-$L = @()
-$L += '# 官方 GitHub Discussions 归档（自动生成，见抓取时间）'
-$L += ''
-$L += '> 来源：https://github.com/deepseek-ai/deepseek-harness/discussions （官方仓库 Issues 关闭，Discussions 为反馈主渠道）。'
-$L += '> 抓取：GitHub REST API（list 含每条正文；comments-<n>.json 为精选线程的全部评论）。'
-$L += "> 更新：提供 ``GH_TOKEN`` 后可由 ``scripts/archive-discussions.ps1`` 幂等刷新；抓取时间 $utc (UTC)。"
-$L += ''
-$L += '## 文件'
-$L += ''
-$L += "- list.json — 全部 $($discs.Count) 条讨论（含 title/body/category/answers/labels 等字段，正文即模型可读文档）。"
-$L += "- comments-<n>.json — 精选 $($sel.Count) 条线程的评论（选择规则：Announcements/Q&A/Ideas 评论>=1；General/Show and tell 评论>=3 且非社群拉群帖）。"
-$L += '- _selection.tsv — 精选线程清单（编号/分类/评论数/标题）。'
-$L += ''
-$L += '## 分类统计'
-$L += ''
-foreach ($k in @($cats.Keys | Sort-Object)) { $L += "- $k：$($cats[$k]) 条" }
-$L += ''
-$L += '## 有归档评论的精选线程'
-$L += ''
-$L += '| # | 分类 | 评论 | 标题 |'
-$L += '|---|---|---|---|'
-foreach ($d in $sel) {
-  $title = ($d.title -replace '\|','\|' -replace "[\r\n]",' ')
-  $L += "| [#$($d.number)](https://github.com/deepseek-ai/deepseek-harness/discussions/$($d.number)) | $($d.category.name) | $($d.comments) | $title |"
-}
-Set-Content -Path (Join-Path $OutDir 'README.md') -Value ($L -join "`r`n") -Encoding UTF8
-Write-Output "DONE: list=$($discs.Count) selected=$($sel.Count) -> $OutDir"
+# dsh-plugin-guide 官方 GitHub Discussions 归档脚本（可复跑，幂等）
+# 输出: downloads/github/harness/discussions/
+#   list.json          全部讨论（title/body/category/answers/labels 等，正文即文档）
+#   comments-<n>.json  精选线程的全部评论（选择规则见下）
+#   _selection.tsv     精选线程清单
+#   README.md          分类统计 + 精选清单
+# 说明: GitHub REST API;未提供 Token 时走匿名配额(60/h,可能不够),建议
+#   $env:GH_TOKEN 或 -Token <token>(经典 PAT,只需 public_repo 读权限)。
+#   选择规则(与 08-14 首版覆盖度一致): Announcements 全部; Q&A/Ideas 评论>=1;
+#   General/Show and tell 评论>=3 且标题不含拉群/招聘/广告词。
+#   传输用 Invoke-WebRequest(而非 curl.exe 数组参数): PS 5.1 下 curl 数组参数
+#   的引号拆分会把 -H 头打碎,导致静默拿到错误对象——本脚本已规避该坑。
+# 参数: -OutDir <dir> 覆盖输出目录; -SkipComments 只刷新 list.json 不拉评论。
+param(
+  [string]$OutDir = '',
+  [string]$Repo = 'deepseek-ai/deepseek-harness',
+  [string]$Token = $env:GH_TOKEN,
+  [switch]$SkipComments
+)
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+if (-not $OutDir) { $OutDir = Join-Path (Split-Path $PSScriptRoot -Parent) 'downloads\github\harness\discussions' }
+New-Item -ItemType Directory -Force -Path $OutDir | Out-Null
+
+$headers = @{ 'User-Agent' = 'dsh-plugin-guide-research'; 'Accept' = 'application/vnd.github+json' }
+if ($Token) { $headers['Authorization'] = "Bearer $Token" }
+
+function Get-Api([string]$url) {
+  # 返回对象数组;失败/限流时抛错(带状态码),由调用方决定重试或中止。
+  try {
+    $resp = Invoke-WebRequest -Uri $url -Headers $headers -TimeoutSec 60 -UseBasicParsing
+  } catch {
+    $code = if ($_.Exception.Response) { [int]$_.Exception.Response.StatusCode } else { 0 }
+    throw "HTTP $code : $url"
+  }
+  $obj = $null
+  try { $obj = $resp.Content | ConvertFrom-Json } catch { throw "JSON parse failed: $url" }
+  if ($obj -is [System.Management.Automation.PSCustomObject] -and $obj.PSObject.Properties.Name -contains 'message') {
+    throw "API message '$($obj.message)' : $url"
+  }
+  return @($obj)
+}
+
+# ---- 1) 全量 list(按创建序分页;REST 的 direction 参数对 discussions 无效,只能从头翻到尾) ----
+$prevCount = 0
+if (Test-Path (Join-Path $OutDir 'list.json')) {
+  try { $prev = @((Get-Content (Join-Path $OutDir 'list.json') -Raw -Encoding UTF8 | ConvertFrom-Json)); $prevCount = $prev.Count } catch { $prevCount = 0 }
+}
+$all = @()
+$page = 1
+# REST /discussions caps at 5000 rows (50 pages x 100). The cap is explicit so a
+# silent truncation cannot be mistaken for a complete archive: the run reports
+# when it stops at the ceiling, and the README records the ceiling alongside the
+# GraphQL total_count (which is larger).
+$pageCap = 50
+while ($page -le $pageCap) {
+  $items = Get-Api "https://api.github.com/repos/$Repo/discussions?per_page=100&page=$page&sort=created"
+  if ($items.Count -eq 0) { Write-Output "page ${page}: 空页,列表结束"; break }
+  $all += $items
+  Write-Output ("page {0}: +{1} (累计 {2})" -f $page, $items.Count, $all.Count)
+  if ($items.Count -lt 100) { break }
+  $page++
+  Start-Sleep -Milliseconds 500
+}
+if ($all.Count -ge ($pageCap * 100)) {
+  Write-Output "WARN: 列表在第 $pageCap 页触顶(REST 5000 条上限)——归档为前 5000 条,非全量;更全的历史需按 GraphQL UPDATED_AT 分页补抓"
+}
+if ($all.Count -eq 0) { throw 'discussions 列表抓取失败(0 条)' }
+if ($prevCount -gt 0 -and $all.Count -lt [Math]::Floor($prevCount * 0.9)) {
+  throw "列表疑似缩水: 上次 $prevCount 条, 本次仅 $all.Count 条 —— 拒绝覆盖归档,请检查网络/配额后重跑"
+}
+
+# 按 number 去重(分页边界可能重复)
+$uniq = @{}
+foreach ($d in $all) { $uniq[[int]$d.number] = $d }
+$discs = @($uniq.Values | Sort-Object { [int]$_.number })
+$listPath = Join-Path $OutDir 'list.json'
+$discs | ConvertTo-Json -Depth 6 | Set-Content -Path $listPath -Encoding UTF8
+Write-Output "list.json: $($discs.Count) 条 -> $listPath"
+
+# ---- 2) 精选线程 + 评论 ----
+$sel = @()
+foreach ($d in $discs) {
+  $cat = $d.category.name
+  $c = [int]$d.comments
+  $t = [string]$d.title
+  $pick = $false
+  if ($cat -eq 'Announcements') { $pick = $true }
+  elseif ($cat -eq 'Q&A' -and $c -ge 1) { $pick = $true }
+  elseif ($cat -eq 'Ideas' -and $c -ge 1) { $pick = $true }
+  elseif (($cat -eq 'General' -or $cat -eq 'Show and tell') -and $c -ge 3) {
+    # 非社群拉群帖: 标题含拉群/扫码/加群/招聘/广告类词的不收
+    if ($t -notmatch '群|扫码|加群|招聘|内推|广告|投简历|纳新') { $pick = $true }
+  }
+  if ($pick) { $sel += $d }
+}
+$sel = @($sel | Sort-Object { [int]$_.number })
+Write-Output "精选线程: $($sel.Count) 条"
+
+if (-not $SkipComments) {
+  $n = 0
+  foreach ($d in $sel) {
+    $num = [int]$d.number
+    $comments = @()
+    $cp = 1
+    while ($cp -le 20) {
+      $ci = Get-Api "https://api.github.com/repos/$Repo/discussions/$num/comments?per_page=100&page=$cp"
+      if ($ci.Count -eq 0) { break }
+      $comments += $ci
+      if ($ci.Count -lt 100) { break }
+      $cp++
+      Start-Sleep -Milliseconds 300
+    }
+    $comments | ConvertTo-Json -Depth 6 | Set-Content -Path (Join-Path $OutDir "comments-$num.json") -Encoding UTF8
+    $n++
+    if ($n % 20 -eq 0) { Write-Output "comments: $n / $($sel.Count)" }
+    Start-Sleep -Milliseconds 200
+  }
+  Write-Output "comments: 完成 $n 个线程"
+  # 清掉列表里已不存在的旧 comments 文件
+  $keep = New-Object System.Collections.Generic.HashSet[string]
+  foreach ($d in $sel) { [void]$keep.Add("comments-$([int]$d.number).json") }
+  Get-ChildItem $OutDir -Filter 'comments-*.json' | Where-Object { -not $keep.Contains($_.Name) } | Remove-Item -Force
+} else {
+  Write-Output 'comments: 跳过(-SkipComments)'
+}
+
+# ---- 3) _selection.tsv 与 README.md ----
+$selLines = @('number' + "`t" + 'category' + "`t" + 'comments' + "`t" + 'title')
+foreach ($d in $sel) { $selLines += ("{0}`t{1}`t{2}`t{3}" -f $d.number, $d.category.name, $d.comments, ($d.title -replace "`t",' ')) }
+Set-Content -Path (Join-Path $OutDir '_selection.tsv') -Value $selLines -Encoding UTF8
+
+$cats = @{}
+foreach ($d in $discs) { $k = [string]$d.category.name; if (-not $cats.ContainsKey($k)) { $cats[$k] = 0 }; $cats[$k]++ }
+$utc = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')
+$L = @()
+$L += '# 官方 GitHub Discussions 归档（自动生成，见抓取时间）'
+$L += ''
+$L += '> 来源：https://github.com/deepseek-ai/deepseek-harness/discussions （官方仓库 Issues 关闭，Discussions 为反馈主渠道）。'
+$L += '> 抓取：GitHub REST API（list 含每条正文；comments-<n>.json 为精选线程的全部评论）。'
+$L += "> 更新：提供 ``GH_TOKEN`` 后可由 ``scripts/archive-discussions.ps1`` 幂等刷新；抓取时间 $utc (UTC)。"
+$L += ''
+$L += '## 文件'
+$L += ''
+$L += "- list.json — 全部 $($discs.Count) 条讨论（含 title/body/category/answers/labels 等字段，正文即模型可读文档）。"
+$L += "- comments-<n>.json — 精选 $($sel.Count) 条线程的评论（选择规则：Announcements/Q&A/Ideas 评论>=1；General/Show and tell 评论>=3 且非社群拉群帖）。"
+$L += '- _selection.tsv — 精选线程清单（编号/分类/评论数/标题）。'
+$L += ''
+$L += '## 分类统计'
+$L += ''
+foreach ($k in @($cats.Keys | Sort-Object)) { $L += "- $k：$($cats[$k]) 条" }
+$L += ''
+$L += '## 有归档评论的精选线程'
+$L += ''
+$L += '| # | 分类 | 评论 | 标题 |'
+$L += '|---|---|---|---|'
+foreach ($d in $sel) {
+  $title = ($d.title -replace '\|','\|' -replace "[\r\n]",' ')
+  $L += "| [#$($d.number)](https://github.com/deepseek-ai/deepseek-harness/discussions/$($d.number)) | $($d.category.name) | $($d.comments) | $title |"
+}
+Set-Content -Path (Join-Path $OutDir 'README.md') -Value ($L -join "`r`n") -Encoding UTF8
+Write-Output "DONE: list=$($discs.Count) selected=$($sel.Count) -> $OutDir"

package/scripts/check-docs-drift.ps1

@@ -1,55 +1,55 @@
-# dsh-plugin-guide official-docs freshness probe.
-# Purpose: detect drift between the KB mirror (references/official-docs) and the
-#   upstream deepseek-harness repository WITHOUT a local checkout. It compares the
-#   upstream branch tip SHA (git ls-remote) against the pinned "Source commit" SHA
-#   recorded in references/official-docs/SNAPSHOT.md — the SHA-locked authority the
-#   mirror was synced from. It never edits the mirror; drift is only reported.
-# Usage:  pwsh -File scripts/check-docs-drift.ps1 [-Repo <url>] [-Branch <name>] [-Snapshot <path>] [-FailOnDrift]
-#   Exit codes: 0 = FRESH, 1 = DRIFT (with -FailOnDrift), 2 = probe could not run (snapshot/parse/fetch failure).
-#   In CI it also writes `drift=yes|no|error` to $env:GITHUB_OUTPUT when that variable is set.
-param(
-  [string]$Repo = 'https://github.com/deepseek-ai/deepseek-harness.git',
-  [string]$Branch = 'master',
-  [string]$Snapshot = 'references/official-docs/SNAPSHOT.md',
-  [switch]$FailOnDrift
-)
-$ErrorActionPreference = 'Stop'
-$kit = Split-Path $PSScriptRoot -Parent
-$snapshotPath = Join-Path $kit $Snapshot
-
-# ---- 1) Read the pinned source commit SHA from SNAPSHOT.md ----
-$pinned = $null
-if (-not (Test-Path $snapshotPath)) { Write-Error "snapshot not found: $snapshotPath"; exit 2 }
-foreach ($line in Get-Content $snapshotPath -Encoding UTF8) {
-  if ($line -match '^\|\s*Source commit\s*\|\s*`([0-9a-f]{40})`\s*\|') {
-    $pinned = $Matches[1]
-    break
-  }
-}
-if (-not $pinned) { Write-Error "cannot parse the pinned 'Source commit' SHA from $Snapshot"; exit 2 }
-
-# ---- 2) Fetch the upstream branch tip SHA (no clone required) ----
-$remoteLine = (& git ls-remote $Repo "refs/heads/$Branch" 2>$null | Select-Object -First 1)
-if (-not $remoteLine -or $remoteLine -notmatch '^([0-9a-f]{40})\s') {
-  $message = "cannot reach upstream $Repo (branch $Branch)"
-  Write-Output "ERROR: $message"
-  if ($env:GITHUB_OUTPUT) { Add-Content -Path $env:GITHUB_OUTPUT -Value 'drift=error' }
-  exit 2
-}
-$upstream = $Matches[1]
-
-# ---- 3) Compare and report ----
-$fresh = ($upstream -eq $pinned)
-Write-Output "pinned (SNAPSHOT.md): $pinned"
-Write-Output "upstream ($Branch): $upstream"
-if ($fresh) {
-  Write-Output 'FRESH: references/official-docs matches the upstream branch tip'
-} else {
-  Write-Output "DRIFT: references/official-docs is pinned to $pinned but upstream is at $upstream"
-  Write-Output 'Action: run  pwsh -File scripts/sync-official-docs.ps1  to refresh the mirror (do not hand-edit the mirror).'
-}
-if ($env:GITHUB_OUTPUT) {
-  Add-Content -Path $env:GITHUB_OUTPUT -Value ($(if ($fresh) { 'drift=no' } else { 'drift=yes' }))
-}
-if (-not $fresh -and $FailOnDrift) { exit 1 }
-exit 0
+# dsh-plugin-guide official-docs freshness probe.
+# Purpose: detect drift between the KB mirror (references/official-docs) and the
+#   upstream deepseek-harness repository WITHOUT a local checkout. It compares the
+#   upstream branch tip SHA (git ls-remote) against the pinned "Source commit" SHA
+#   recorded in references/official-docs/SNAPSHOT.md — the SHA-locked authority the
+#   mirror was synced from. It never edits the mirror; drift is only reported.
+# Usage:  pwsh -File scripts/check-docs-drift.ps1 [-Repo <url>] [-Branch <name>] [-Snapshot <path>] [-FailOnDrift]
+#   Exit codes: 0 = FRESH, 1 = DRIFT (with -FailOnDrift), 2 = probe could not run (snapshot/parse/fetch failure).
+#   In CI it also writes `drift=yes|no|error` to $env:GITHUB_OUTPUT when that variable is set.
+param(
+  [string]$Repo = 'https://github.com/deepseek-ai/deepseek-harness.git',
+  [string]$Branch = 'master',
+  [string]$Snapshot = 'references/official-docs/SNAPSHOT.md',
+  [switch]$FailOnDrift
+)
+$ErrorActionPreference = 'Stop'
+$kit = Split-Path $PSScriptRoot -Parent
+$snapshotPath = Join-Path $kit $Snapshot
+
+# ---- 1) Read the pinned source commit SHA from SNAPSHOT.md ----
+$pinned = $null
+if (-not (Test-Path $snapshotPath)) { Write-Error "snapshot not found: $snapshotPath"; exit 2 }
+foreach ($line in Get-Content $snapshotPath -Encoding UTF8) {
+  if ($line -match '^\|\s*Source commit\s*\|\s*`([0-9a-f]{40})`\s*\|') {
+    $pinned = $Matches[1]
+    break
+  }
+}
+if (-not $pinned) { Write-Error "cannot parse the pinned 'Source commit' SHA from $Snapshot"; exit 2 }
+
+# ---- 2) Fetch the upstream branch tip SHA (no clone required) ----
+$remoteLine = (& git ls-remote $Repo "refs/heads/$Branch" 2>$null | Select-Object -First 1)
+if (-not $remoteLine -or $remoteLine -notmatch '^([0-9a-f]{40})\s') {
+  $message = "cannot reach upstream $Repo (branch $Branch)"
+  Write-Output "ERROR: $message"
+  if ($env:GITHUB_OUTPUT) { Add-Content -Path $env:GITHUB_OUTPUT -Value 'drift=error' }
+  exit 2
+}
+$upstream = $Matches[1]
+
+# ---- 3) Compare and report ----
+$fresh = ($upstream -eq $pinned)
+Write-Output "pinned (SNAPSHOT.md): $pinned"
+Write-Output "upstream ($Branch): $upstream"
+if ($fresh) {
+  Write-Output 'FRESH: references/official-docs matches the upstream branch tip'
+} else {
+  Write-Output "DRIFT: references/official-docs is pinned to $pinned but upstream is at $upstream"
+  Write-Output 'Action: run  pwsh -File scripts/sync-official-docs.ps1  to refresh the mirror (do not hand-edit the mirror).'
+}
+if ($env:GITHUB_OUTPUT) {
+  Add-Content -Path $env:GITHUB_OUTPUT -Value ($(if ($fresh) { 'drift=no' } else { 'drift=yes' }))
+}
+if (-not $fresh -and $FailOnDrift) { exit 1 }
+exit 0

package/scripts/check-ps1-bom.mjs

@@ -0,0 +1,68 @@
+// Assert every PowerShell script under scripts/ keeps its UTF-8 BOM.
+//
+// Why this exists: PowerShell 5.1 (Windows PowerShell - the only shell on a
+// machine without pwsh) decodes a BOM-less script as ANSI/CP936. `verify-kit.ps1`
+// carries ~1.6 KB of Chinese comments and messages, so the mis-decode corrupts
+// the source and the parser fails with "Missing ')' in method call". That is the
+// repository's own recorded convention (`references/sources.md`), and on
+// 2026-10-13 `verify-kit.ps1` was found to be the only one of nine scripts
+// missing its BOM - and therefore unusable on PowerShell 5.1, which was
+// invisible to CI because CI runs it under `pwsh`, where a missing BOM is
+// harmless.
+//
+// Deliberately implemented in Node, not PowerShell: it must run on the Linux CI
+// runner and on a machine whose only PowerShell is the 5.1 that cannot read the
+// file in the first place.
+
+import { readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const dir = join(process.cwd(), 'scripts')
+const BOM = [0xef, 0xbb, 0xbf]
+
+/** True when the buffer starts with a UTF-8 BOM. */
+function hasBom(buf) {
+  return buf.length >= 3 && buf[0] === BOM[0] && buf[1] === BOM[1] && buf[2] === BOM[2]
+}
+
+/** Count bytes above ASCII, i.e. how much a mis-decode could corrupt. */
+function nonAsciiBytes(buf) {
+  let n = 0
+  for (const b of buf) if (b > 127) n++
+  return n
+}
+
+const scripts = readdirSync(dir)
+  .filter((f) => f.toLowerCase().endsWith('.ps1'))
+  .sort()
+
+const problems = []
+const rows = []
+
+for (const file of scripts) {
+  const buf = readFileSync(join(dir, file))
+  const bom = hasBom(buf)
+  const nonAscii = nonAsciiBytes(buf)
+  rows.push({ file, bom, nonAscii, bytes: buf.length })
+  // A BOM matters most when the file contains non-ASCII text; for a pure-ASCII
+  // script a missing BOM is harmless, so report it without failing.
+  if (!bom && nonAscii > 0) {
+    problems.push(
+      `${file}: ${nonAscii} non-ASCII bytes but no UTF-8 BOM - PowerShell 5.1 will mis-decode this script`,
+    )
+  }
+}
+
+for (const r of rows) {
+  const flag = !r.bom && r.nonAscii > 0 ? 'FAIL' : r.bom ? 'ok  ' : 'warn'
+  console.log(`${flag}  ${r.file.padEnd(34)} bom=${String(r.bom).padEnd(5)} nonAscii=${String(r.nonAscii).padEnd(5)} bytes=${r.bytes}`)
+}
+
+if (problems.length > 0) {
+  console.error('\nps1-bom: FAIL')
+  for (const p of problems) console.error('  ' + p)
+  console.error('\nFix: prepend EF BB BF to the file (keep the content byte-identical otherwise).')
+  process.exit(1)
+}
+
+console.log(`\nps1-bom OK (${scripts.length} scripts; every non-ASCII one carries a BOM)`)

package/scripts/check-readme-parity.mjs

@@ -0,0 +1,149 @@
+// Content-parity gate for the five READMEs and the five quick references.
+//
+// `check-readme-sync.mjs` only compares `## ` headings, so four translation
+// families drifted past it unnoticed: an audit on 2026-10-13 found the es/pt/hi
+// READMEs missing whole entries of "What you get" (including the flagship
+// version-adaptivity document), the quick references still claiming "215 pages"
+// against an actual 429, and a "re-verified on 2026-10-06" date attached to a
+// commit dated 2026-10-09.
+//
+// This gate compares STRUCTURE at the block level — the number of list items and
+// table rows inside each H2 section — instead of only the H2 titles. It cannot
+// judge translation quality; it catches the case that actually happens, a
+// section that gained or lost items in one language only.
+//
+// Usage: node scripts/check-readme-parity.mjs [--json] [--max-drift N]
+
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+const root = process.cwd()
+const json = process.argv.includes('--json')
+const maxArg = process.argv.indexOf('--max-drift')
+const maxDrift = maxArg >= 0 ? Number(process.argv[maxArg + 1] ?? 0) : 0
+
+/** The English source and its translations, for each family. */
+const FAMILIES = [
+  {
+    name: 'README',
+    base: 'README.md',
+    variants: ['README-zh.md', 'README-es.md', 'README-pt.md', 'README-hi.md'],
+  },
+  {
+    name: 'quick-reference',
+    base: 'guide/quick-reference.md',
+    variants: [
+      'guide/quick-reference.zh-CN.md',
+      'guide/quick-reference.es.md',
+      'guide/quick-reference.pt.md',
+      'guide/quick-reference.hi.md',
+    ],
+  },
+]
+
+/**
+ * Split a markdown document into H2 sections and count countable blocks.
+ *
+ * Sections are keyed by ORDINAL, not by title: the quick references legitimately
+ * translate their headings, so matching on English titles produced 26 false
+ * "missing section" reports per language. What must stay identical across a
+ * translation family is the SEQUENCE and the SIZE of the sections, because the
+ * failure mode this gate exists for is a section that gained or lost content in
+ * one language only.
+ *
+ * @param text - raw markdown.
+ * @returns ordered sections with their countable blocks.
+ */
+function sectionProfile(text) {
+  const lines = text.split(/\r?\n/)
+  const out = []
+  let current = { index: 0, title: '(preamble)', bullets: 0, tableRows: 0, codeBlocks: 0 }
+  out.push(current)
+  let inFence = false
+
+  for (const line of lines) {
+    if (/^\s*```/.test(line)) {
+      inFence = !inFence
+      if (inFence) current.codeBlocks++
+      continue
+    }
+    if (inFence) continue
+    const h2 = /^##\s+(.*)$/.exec(line)
+    if (h2) {
+      current = { index: out.length, title: h2[1].trim(), bullets: 0, tableRows: 0, codeBlocks: 0 }
+      out.push(current)
+      continue
+    }
+    if (/^\s*[-*]\s+\S/.test(line)) current.bullets++
+    // A table row, excluding the separator row.
+    if (/^\s*\|/.test(line) && !/^\s*[\s:|-]+\|\s*$/.test(line)) current.tableRows++
+  }
+  return out
+}
+
+/** Compare one variant against the English source, by section ordinal. */
+function compare(basePath, variantPath) {
+  const base = sectionProfile(readFileSync(join(root, basePath), 'utf8'))
+  const variant = sectionProfile(readFileSync(join(root, variantPath), 'utf8'))
+  const drift = []
+
+  if (base.length !== variant.length) {
+    drift.push({
+      kind: 'section-count',
+      detail: `${base.length} sections in base vs ${variant.length} in variant`,
+      base: null,
+      variant: null,
+      section: null,
+    })
+  }
+
+  const n = Math.min(base.length, variant.length)
+  for (let i = 0; i < n; i++) {
+    for (const key of ['bullets', 'tableRows', 'codeBlocks']) {
+      if (base[i][key] !== variant[i][key]) {
+        drift.push({
+          section: `#${i} ${base[i].title}`,
+          kind: key,
+          base: base[i][key],
+          variant: variant[i][key],
+          detail: `base="${base[i].title}" variant="${variant[i].title}"`,
+        })
+      }
+    }
+  }
+  return drift
+}
+
+let total = 0
+const report = []
+for (const family of FAMILIES) {
+  if (!existsSync(join(root, family.base))) continue
+  for (const v of family.variants) {
+    if (!existsSync(join(root, v))) continue
+    const drift = compare(family.base, v)
+    total += drift.length
+    report.push({ family: family.name, variant: v, drift })
+  }
+}
+
+if (json) {
+  console.log(JSON.stringify({ total, report }, null, 2))
+} else {
+  for (const r of report) {
+    if (r.drift.length === 0) {
+      console.log(`ok   ${r.family.padEnd(16)} ${r.variant}`)
+      continue
+    }
+    console.log(`DRIFT ${r.family.padEnd(15)} ${r.variant}  (${r.drift.length} block(s))`)
+    for (const d of r.drift.slice(0, 12)) {
+      if (d.kind === 'section-count') console.log(`        ${d.detail}`)
+      else if (d.section === null) console.log(`        ${d.kind}: ${d.detail ?? ''}`)
+      else console.log(`        ${d.kind.padEnd(11)} ${d.base} vs ${d.variant}  in "${d.section}"`)
+    }
+    if (r.drift.length > 12) console.log(`        ... and ${r.drift.length - 12} more`)
+  }
+  console.log(`\nblock-level drift entries: ${total}`)
+}
+
+// The gate is opt-in strict: run with --max-drift N to allow a known budget.
+process.exit(total > maxDrift ? 1 : 0)