dsh-plugin-guide 0.3.41 → 0.4.0

package/scripts/archive-discussions.ps1

@@ -1,162 +0,0 @@
-# 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/build-llms-full.mjs

@@ -1,73 +0,0 @@
-// build-llms-full.mjs — concatenate the knowledge base into llms-full.txt
-//
-// The KB ships a handful of long-form documents. LLM crawlers fetch a single
-// plain-text URL far more reliably than they walk a repository tree, so
-// `llms-full.txt` carries the whole corpus in reading order, and `llms.txt`
-// carries the index that points at it.
-//
-// Idempotent: re-running rewrites the file with identical bytes when the
-// sources are unchanged. Run it after editing any file in SOURCES.
-//
-//   node scripts/build-llms-full.mjs
-import { readFileSync, writeFileSync, existsSync } from 'node:fs'
-import path from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)))
-
-// Reading order: what a plugin author needs first, then the evidence base.
-const SOURCES = [
-  ['README.md', 'Overview'],
-  // SKILL.md first among the authored docs: it carries the contract red lines,
-  // and llms-full previously omitted it entirely.
-  ['SKILL.md', 'Agent skill: contract red lines and task-based development paths'],
-  ['guide/version-matrix.md', 'Version adaptivity matrix (latest values, seams, peer ranges, session format)'],
-  ['guide/plugin-dev-guide.md', 'Plugin development guide (10 chapters)'],
-  ['guide/standards.md', 'Adoption levels: DSH-ENTRY / DSH-FLOW / DSH-BOOST (non-official)'],
-  ['guide/quick-reference.md', 'Quick reference'],
-  ['guide/migration-0.2.md', 'Migration to the 0.2 generation (breaking changes)'],
-  ['guide/family-toolchain.md', 'Family toolchain router (check catalogs and crosswalk)'],
-  ['guide/when-to-retire-a-plugin.md', 'When to retire or freeze a plugin'],
-  ['guide/choosing-a-plugin.md', 'Choosing a plugin: who leads each capability surface'],
-  ['guide/release-engineering.md', 'Release engineering'],
-  ['guide/unfixed-issues.md', 'Unfixed upstream issues (source-verified)'],
-  ['guide/links.md', 'Curated links'],
-  ['references/official-plugin-dev-skill.md', 'Distilled official in-repo plugin-development skill'],
-  ['references/dev-resource-landscape.md', 'Competing and adjacent plugin-development resources'],
-  ['references/harness-repo.md', 'Harness repository reference'],
-  ['references/upstream-cordis.md', 'Upstream Cordis reference'],
-  ['references/cordis-paper-and-community.md', 'Cordis paper and community'],
-  ['references/community-ecosystem.md', 'Community ecosystem'],
-  ['references/community-repo-deep-dive.md', 'Community repository deep dive'],
-  ['references/website-pages.md', 'Official website pages'],
-  ['references/sources.md', 'Sources'],
-]
-
-const missing = SOURCES.filter(([rel]) => !existsSync(path.join(root, rel)))
-if (missing.length > 0) {
-  console.error('build-llms-full: missing sources:')
-  for (const [rel] of missing) console.error('  - ' + rel)
-  process.exit(1)
-}
-
-const header = [
-  '# dsh-plugin-guide — full knowledge base',
-  '',
-  '> DeepSeek Harness (dsh) plugin development knowledge base, in reading order.',
-  '> One document per section, each preceded by its source path so a citation can',
-  '> name the file it came from. Index: llms.txt. Repository:',
-  '> https://github.com/PerryLink/dsh-plugin-guide',
-  '',
-  `> Generated by scripts/build-llms-full.mjs from ${SOURCES.length} sources. Do not hand-edit.`,
-  '',
-].join('\n')
-
-const parts = [header]
-for (const [rel, title] of SOURCES) {
-  const body = readFileSync(path.join(root, rel), 'utf8').replace(/\r\n/gu, '\n').trimEnd()
-  parts.push(`\n\n<!-- source: ${rel} -->\n\n# [${title}] ${rel}\n\n${body}\n`)
-}
-
-const out = parts.join('')
-writeFileSync(path.join(root, 'llms-full.txt'), out, 'utf8')
-console.log(`llms-full.txt written: ${Buffer.byteLength(out)} bytes from ${SOURCES.length} sources`)

package/scripts/check-docs-drift-detail.mjs

@@ -1,145 +0,0 @@
-// Answer "WHAT changed upstream?", not just "is the mirror stale?".
-//
-// `check-docs-drift.ps1` compares the upstream branch-tip SHA against the SHA
-// recorded in `references/official-docs/SNAPSHOT.md`. When they differ it says so
-// and stops — a maintainer still has to work out which of ~700 mirrored files
-// moved. A drift report that names no file is why the weekly job can sit red for
-// eleven weeks without anyone acting on it.
-//
-// This script names the files: it compares the pinned commit's tree against the
-// upstream head's tree and lists added, removed, and modified paths inside the
-// mirror's declared scope.
-//
-// Usage:
-//   node scripts/check-docs-drift-detail.mjs [--commit <sha>] [--json]
-//   node scripts/check-docs-drift-detail.mjs --checkout D:\deepseek-harness
-//
-// Exit codes: 0 = fresh or report produced, 2 = could not probe, 1 = drift (with --fail-on-drift).
-
-import { execFileSync } from 'node:child_process'
-import { readFileSync, existsSync } from 'node:fs'
-import { join } from 'node:path'
-
-const root = process.cwd()
-const argv = process.argv.slice(2)
-const flag = (name, fallback) => {
-  const i = argv.indexOf(name)
-  return i >= 0 ? (argv[i + 1] ?? true) : fallback
-}
-const asJson = argv.includes('--json')
-const failOnDrift = argv.includes('--fail-on-drift')
-const checkout = flag('--checkout', null)
-
-const SNAPSHOT = join(root, 'references', 'official-docs', 'SNAPSHOT.md')
-const MIRROR = join(root, 'references', 'official-docs')
-
-// The mirror's declared scope, matching sync-official-docs.ps1 `$paths` exactly.
-// `packages/` contributes only AGENTS.md and README.md, and `vendor/` only
-// README.md — a bare directory prefix would report every package file as
-// "missing from the mirror", which is 2,000 paths of noise.
-const SCOPE_EXACT = new Set([
-  'AGENTS.md',
-  'BENCHMARK.md',
-  'CONTRIBUTING.md',
-  'CONTRIBUTING.zh.md',
-  'CONTRIBUTING.i18n.yaml',
-  'README.zh.md',
-  'README.i18n.yaml',
-  'THIRD_PARTY_NOTICES.md',
-  'LICENSE',
-  'packages/AGENTS.md',
-  'packages/README.md',
-  'vendor/README.md',
-  'website/docs.ts',
-])
-const inScope = (p) => p.startsWith('docs/') || SCOPE_EXACT.has(p)
-
-/** The scope, for the report header. */
-const SCOPE = ['docs/', ...SCOPE_EXACT]
-
-/** Read the pinned SHA and scope out of SNAPSHOT.md. */
-function readSnapshot() {
-  const text = readFileSync(SNAPSHOT, 'utf8')
-  const sha = /^\|\s*Source commit\s*\|\s*`([0-9a-f]{40})`\s*\|/m.exec(text)?.[1]
-  if (!sha) throw new Error(`cannot parse the pinned Source commit from ${SNAPSHOT}`)
-  return { sha, text }
-}
-
-/** git against the local checkout. */
-function git(args) {
-  return execFileSync('git', ['-C', checkout, ...args], { encoding: 'utf8', maxBuffer: 1 << 28 })
-}
-
-/** path -> blob sha for a commit's tree, via the local checkout. */
-function treeOf(rev) {
-  const out = git(['ls-tree', '-r', '--format=%(objectname) %(path)', rev])
-  const map = new Map()
-  for (const line of out.split('\n')) {
-    const sp = line.indexOf(' ')
-    if (sp < 0) continue
-    map.set(line.slice(sp + 1), line.slice(0, sp))
-  }
-  return map
-}
-
-const report = { scope: SCOPE, added: [], removed: [], modified: [] }
-
-if (checkout) {
-  if (!existsSync(checkout)) {
-    console.error(`ERROR: checkout not found: ${checkout}`)
-    process.exit(2)
-  }
-  const { sha: pinned } = readSnapshot()
-  const head = git(['rev-parse', 'HEAD']).trim()
-  const upstreamRev = git(['rev-parse', 'origin/master']).trim()
-  const target = flag('--commit', upstreamRev)
-  let a
-  let b
-  try {
-    a = treeOf(pinned)
-    b = treeOf(target)
-  } catch (err) {
-    console.error(`ERROR: cannot read a tree (${err.message.split('\n')[0]}). Is ${pinned.slice(0, 7)} present in the checkout?`)
-    process.exit(2)
-  }
-  for (const [p, s] of b) {
-    if (!inScope(p)) continue
-    if (!a.has(p)) report.added.push(p)
-    else if (a.get(p) !== s) report.modified.push(p)
-  }
-  for (const p of a.keys()) if (inScope(p) && !b.has(p)) report.removed.push(p)
-  report.pinned = pinned
-  report.target = target
-  report.head = head
-  report.mode = 'checkout'
-} else {
-  console.error('ERROR: pass --checkout <deepseek-harness>; the API mode is not implemented (the mirror is pinned to a commit, and a tree comparison needs both trees).')
-  process.exit(2)
-}
-
-const total = report.added.length + report.removed.length + report.modified.length
-if (asJson) {
-  console.log(JSON.stringify({ ...report, total }, null, 2))
-} else {
-  console.log(`pinned : ${report.pinned}`)
-  console.log(`target : ${report.target}${report.target === report.head ? ' (checkout HEAD)' : ''}`)
-  console.log('')
-  if (total === 0) {
-    console.log('FRESH: no in-scope file differs between the pinned commit and the target.')
-  } else {
-    console.log(`DRIFT: ${total} in-scope file(s) differ`)
-    const show = (label, list) => {
-      if (!list.length) return
-      console.log(`\n  ${label} (${list.length}):`)
-      for (const p of list.slice(0, 25)) console.log(`    ${p}`)
-      if (list.length > 25) console.log(`    ... and ${list.length - 25} more`)
-    }
-    show('ADDED upstream (the mirror is missing these)', report.added)
-    show('REMOVED upstream (the mirror still carries these)', report.removed)
-    show('MODIFIED upstream (the mirror has stale content)', report.modified)
-    console.log('\nAction: run  pwsh -File scripts/sync-official-docs.ps1  to refresh the mirror (never hand-edit it).')
-  }
-}
-
-if (total > 0 && failOnDrift) process.exit(1)
-process.exit(0)

package/scripts/check-docs-drift.ps1

@@ -1,55 +0,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-facts.mjs

@@ -1,162 +0,0 @@
-// Assert that the numbers this project states about itself match reality.
-//
-// Why this exists: the audits found the same class of defect repeatedly, always
-// a number stated in prose that no longer matched the thing it described.
-//   * the family roster was written four different ways in four files;
-//   * the pitfall list was "30+" in English and "20+" in three translations;
-//   * the mirror was described as "215 pages" long after it reached 429;
-//   * `unfixed-issues.md` carried four separate arithmetic slips ("4 items ...
-//     5 items").
-// None of those are content errors — they are drift between a claim and its
-// source. `data/facts.json` is the single home for the numbers; this script
-// checks the claims a machine can verify.
-//
-// Usage: node scripts/check-facts.mjs [--json]
-
-import { readFileSync, readdirSync, statSync } from 'node:fs'
-import { join, relative } from 'node:path'
-
-const root = process.cwd()
-const asJson = process.argv.includes('--json')
-const facts = JSON.parse(readFileSync(join(root, 'data', 'facts.json'), 'utf8'))
-
-const failures = []
-const checked = []
-const ok = (name, detail) => checked.push(`${name}: ${detail}`)
-const bad = (name, detail) => failures.push(`${name}: ${detail}`)
-
-const read = (p) => readFileSync(join(root, p), 'utf8')
-
-/** Count `## ` sections in a document. */
-const sections = (text) => text.split(/\r?\n/).filter((l) => /^##\s/.test(l)).length
-
-/** Count top-level bullets inside the section starting at `heading`. */
-function bulletsIn(text, heading) {
-  const lines = text.split(/\r?\n/)
-  const start = lines.findIndex((l) => l.trim() === `## ${heading}`)
-  if (start < 0) return -1
-  let end = lines.length
-  for (let i = start + 1; i < lines.length; i++) {
-    if (/^##\s/.test(lines[i])) { end = i; break }
-  }
-  return lines.slice(start + 1, end).filter((l) => /^- \S/.test(l)).length
-}
-
-// ---- 1. README structure claims -------------------------------------------------
-{
-  const text = read('README.md')
-  const got = sections(text)
-  if (got !== facts.readme.sections) bad('README sections', `${got} in README.md vs ${facts.readme.sections} in facts.json`)
-  else ok('README sections', String(got))
-
-  const wyg = bulletsIn(text, 'What you get')
-  if (wyg !== facts.readme.whatYouGetEntries) bad('What you get entries', `${wyg} vs ${facts.readme.whatYouGetEntries}`)
-  else ok('What you get entries', String(wyg))
-
-  // Every translation must match too; the parity gate covers structure, but this
-  // catches the case where a translation lost entries AND facts.json was not updated.
-  for (const f of ['README-zh.md', 'README-es.md', 'README-pt.md', 'README-hi.md']) {
-    let t
-    try { t = read(f) } catch { continue }
-    const n = bulletsIn(t, 'What you get')
-    if (n !== facts.readme.whatYouGetEntries) bad(`${f} "What you get"`, `${n} vs ${facts.readme.whatYouGetEntries}`)
-  }
-}
-
-// ---- 2. Knowledge-base inventory -------------------------------------------------
-{
-  const guide = readdirSync(join(root, 'guide')).filter((f) => f.endsWith('.md')).length
-  if (guide !== facts.knowledgeBase.guideDocuments) bad('guide/ documents', `${guide} vs ${facts.knowledgeBase.guideDocuments}`)
-  else ok('guide/ documents', String(guide))
-
-  const refs = readdirSync(join(root, 'references'))
-    .filter((f) => f.endsWith('.md') && statSync(join(root, 'references', f)).isFile()).length
-  if (refs !== facts.knowledgeBase.referenceDocuments) bad('references/ documents', `${refs} vs ${facts.knowledgeBase.referenceDocuments}`)
-  else ok('references/ documents', String(refs))
-}
-
-// ---- 3. Mirror claims ------------------------------------------------------------
-{
-  const snap = read('references/official-docs/SNAPSHOT.md')
-  const commit = /^\|\s*Source commit\s*\|\s*`([0-9a-f]{40})`\s*\|/m.exec(snap)?.[1]
-  if (commit !== facts.mirror.pinnedCommit) bad('mirror pinned commit', `${commit} in SNAPSHOT.md vs ${facts.mirror.pinnedCommit} in facts.json`)
-  else ok('mirror pinned commit', commit.slice(0, 7))
-
-  // Count the mirrored markdown pages and the zh pairs independently.
-  let md = 0
-  let zh = 0
-  const walk = (dir) => {
-    for (const e of readdirSync(dir, { withFileTypes: true })) {
-      const p = join(dir, e.name)
-      if (e.isDirectory()) walk(p)
-      else if (e.name.endsWith('.md')) {
-        md++
-        if (e.name.endsWith('.zh.md')) zh++
-      }
-    }
-  }
-  walk(join(root, 'references', 'official-docs', 'docs'))
-  if (md !== facts.mirror.mdPages) bad('mirror md pages', `${md} counted vs ${facts.mirror.mdPages} in facts.json`)
-  else ok('mirror md pages', String(md))
-  if (zh !== facts.mirror.zhPairs) bad('mirror zh pairs', `${zh} counted vs ${facts.mirror.zhPairs} in facts.json`)
-  else ok('mirror zh pairs', String(zh))
-
-  // Any document quoting a page count must quote the current one.
-  for (const f of ['guide/quick-reference.md', 'guide/quick-reference.zh-CN.md', 'references/sources.md']) {
-    let t
-    try { t = read(f) } catch { continue }
-    const stale = /\b(215|369|182)\s*(?:md|pages|篇)/i.exec(t)
-    if (stale) bad(`${f} stale page count`, `states "${stale[0]}" but the mirror has ${facts.mirror.mdPages} pages`)
-  }
-}
-
-// ---- 4. CLI check counts ---------------------------------------------------------
-{
-  const src = read('src/cli/skill-sections.ts')
-  const n = [...src.matchAll(/^\s*'[a-z0-9-]+':\s*\{/gm)].length
-  if (n !== facts.cli.staticChecks) bad('CLI static checks', `${n} citations vs ${facts.cli.staticChecks} in facts.json`)
-  else ok('CLI static checks', String(n))
-}
-
-// ---- 5. Seam index consistency ---------------------------------------------------
-{
-  const idx = JSON.parse(read('data/seams/index.json'))
-  const corridor = idx.seams.filter((s) => /^L\d+$/.test(s.id)).length
-  if (corridor !== facts.seams.corridorL) bad('corridor L seams', `${corridor} vs ${facts.seams.corridorL}`)
-  else ok('corridor L seams', String(corridor))
-
-  const areas = idx.capabilities.filter((c) => /^A\d+$/.test(c.id)).length
-  if (areas !== facts.seams.capabilityAreas) bad('capability areas', `${areas} vs ${facts.seams.capabilityAreas}`)
-  else ok('capability areas', String(areas))
-
-  const corridorSeams = idx.seams.filter((s) => /^L\d+$/.test(s.id))
-  const detectable = corridorSeams.filter((s) => s.detectable).length
-  const advisory = corridorSeams.length - detectable
-  if (detectable !== facts.seams.staticallyDetectable) bad('statically detectable seams', `${detectable} vs ${facts.seams.staticallyDetectable}`)
-  else ok('statically detectable seams', String(detectable))
-  if (advisory !== facts.seams.advisoryOnly) bad('advisory-only seams', `${advisory} vs ${facts.seams.advisoryOnly}`)
-  else ok('advisory-only seams', String(advisory))
-}
-
-// ---- 6. Release consistency ------------------------------------------------------
-{
-  const pkg = JSON.parse(read('package.json'))
-  const changelog = read('CHANGELOG.md')
-  if (!changelog.includes(`## [${pkg.version}]`)) {
-    bad('CHANGELOG section', `no "## [${pkg.version}]" section for the current package.json version`)
-  } else ok('CHANGELOG section', pkg.version)
-}
-
-if (asJson) {
-  console.log(JSON.stringify({ facts: facts.schema, checked, failures }, null, 2))
-} else {
-  for (const c of checked) console.log(`  ok    ${c}`)
-  if (failures.length) {
-    console.error('\ncheck-facts: FAIL')
-    for (const f of failures) console.error(`  - ${f}`)
-    console.error('\nEvery number above has one home: data/facts.json. Update it, then update the prose.')
-  } else {
-    console.log(`\ncheck-facts OK (${checked.length} assertions against data/facts.json)`)
-  }
-}
-process.exit(failures.length ? 1 : 0)

package/scripts/check-ps1-bom.mjs

@@ -1,68 +0,0 @@
-// 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)`)