dsh-plugin-guide 0.3.29 → 0.3.31

package/scripts/install-skill.ps1

@@ -1,63 +1,63 @@
-# dsh-plugin-guide skill installer.
-# Purpose: copy the KB (excluding generated/local-only parts) into an agent skill directory and verify byte parity.
-# Usage:   pwsh -File scripts/install-skill.ps1 -Target <skill-dir> [-Source <kb-root>]
-# Scope:   SKILL.md, guide/, references/ (incl. official-docs), scripts/, README*.md, LICENSE, NOTICE.md, CONTRIBUTING.md, SECURITY.md.
-# Excluded: downloads/ (generated by scripts), .github/ (CI), .gitignore.
-# Target must be the skill directory itself (e.g. ~/.deepseek/skills/dsh-plugin-guide or <project>/.agents/skills/dsh-plugin-guide).
-param(
-  [Parameter(Mandatory=$true)][string]$Target,
-  [string]$Source = ''
-)
-$ErrorActionPreference = 'Stop'
-if (-not $Source) { $Source = Split-Path $PSScriptRoot -Parent }
-$src = (Resolve-Path $Source).Path
-$top = @('SKILL.md','LICENSE','NOTICE.md','CONTRIBUTING.md','SECURITY.md') + @(Get-ChildItem $src -Filter 'README*.md' -File | ForEach-Object { $_.Name })
-$dirs = @('guide','references','scripts')
-
-New-Item -ItemType Directory -Force -Path $Target | Out-Null
-
-foreach ($f in $top) { Copy-Item (Join-Path $src $f) (Join-Path $Target $f) -Force }
-foreach ($d in $dirs) {
-  # Copy-Item -Recurse into an existing directory would nest the source inside it; replace the owned dir instead.
-  $td = Join-Path $Target $d
-  if (Test-Path $td) { Remove-Item $td -Recurse -Force }
-  Copy-Item (Join-Path $src $d) $td -Recurse -Force
-}
-
-# Prune target files under the owned scope that no longer exist in the source (keeps reinstalls clean).
-foreach ($d in $dirs) {
-  $td = Join-Path $Target $d
-  if (Test-Path $td) {
-    $sd = Join-Path $src $d
-    $sRoot = (Resolve-Path $sd).Path
-    $tRoot = (Resolve-Path $td).Path
-    Get-ChildItem -Recurse -File $td | ForEach-Object {
-      $rel = $_.FullName.Substring($tRoot.Length + 1)
-      if (-not (Test-Path (Join-Path $sRoot $rel))) { Remove-Item $_.FullName -Force }
-    }
-  }
-}
-Get-ChildItem $Target -File -ErrorAction SilentlyContinue | ForEach-Object {
-  if (($_.Name -like 'README*.md' -or $top -contains $_.Name) -and -not (Test-Path (Join-Path $src $_.Name))) { Remove-Item $_.FullName -Force }
-}
-
-# Parity report: every scoped source file must exist in the target byte-for-byte.
-$checked = 0; $mismatch = 0
-foreach ($f in $top) {
-  $s = Join-Path $src $f; $t = Join-Path $Target $f
-  if (Test-Path $t) { $checked++; if ((Get-FileHash $s -Algorithm MD5).Hash -ne (Get-FileHash $t -Algorithm MD5).Hash) { $mismatch++; Write-Output "MISMATCH: $f" } }
-  else { $mismatch++; Write-Output "MISSING-TARGET: $f" }
-}
-foreach ($d in $dirs) {
-  $sd = Join-Path $src $d
-  $sRoot = (Resolve-Path $sd).Path
-  Get-ChildItem -Recurse -File $sd | ForEach-Object {
-    $rel = $_.FullName.Substring($sRoot.Length + 1)
-    $t = Join-Path (Join-Path $Target $d) $rel
-    if (Test-Path $t) { $checked++; if ((Get-FileHash $_.FullName -Algorithm MD5).Hash -ne (Get-FileHash $t -Algorithm MD5).Hash) { $mismatch++; Write-Output "MISMATCH: $d\$rel" } }
-    else { $mismatch++; Write-Output "MISSING-TARGET: $d\$rel" }
-  }
-}
-Write-Output "DONE: $checked scoped files verified, $mismatch mismatches -> $Target"
-if ($mismatch -gt 0) { exit 1 }
-exit 0
+# dsh-plugin-guide skill installer.
+# Purpose: copy the KB (excluding generated/local-only parts) into an agent skill directory and verify byte parity.
+# Usage:   pwsh -File scripts/install-skill.ps1 -Target <skill-dir> [-Source <kb-root>]
+# Scope:   SKILL.md, guide/, references/ (incl. official-docs), scripts/, README*.md, LICENSE, NOTICE.md, CONTRIBUTING.md, SECURITY.md.
+# Excluded: downloads/ (generated by scripts), .github/ (CI), .gitignore.
+# Target must be the skill directory itself (e.g. ~/.deepseek/skills/dsh-plugin-guide or <project>/.agents/skills/dsh-plugin-guide).
+param(
+  [Parameter(Mandatory=$true)][string]$Target,
+  [string]$Source = ''
+)
+$ErrorActionPreference = 'Stop'
+if (-not $Source) { $Source = Split-Path $PSScriptRoot -Parent }
+$src = (Resolve-Path $Source).Path
+$top = @('SKILL.md','LICENSE','NOTICE.md','CONTRIBUTING.md','SECURITY.md') + @(Get-ChildItem $src -Filter 'README*.md' -File | ForEach-Object { $_.Name })
+$dirs = @('guide','references','scripts')
+
+New-Item -ItemType Directory -Force -Path $Target | Out-Null
+
+foreach ($f in $top) { Copy-Item (Join-Path $src $f) (Join-Path $Target $f) -Force }
+foreach ($d in $dirs) {
+  # Copy-Item -Recurse into an existing directory would nest the source inside it; replace the owned dir instead.
+  $td = Join-Path $Target $d
+  if (Test-Path $td) { Remove-Item $td -Recurse -Force }
+  Copy-Item (Join-Path $src $d) $td -Recurse -Force
+}
+
+# Prune target files under the owned scope that no longer exist in the source (keeps reinstalls clean).
+foreach ($d in $dirs) {
+  $td = Join-Path $Target $d
+  if (Test-Path $td) {
+    $sd = Join-Path $src $d
+    $sRoot = (Resolve-Path $sd).Path
+    $tRoot = (Resolve-Path $td).Path
+    Get-ChildItem -Recurse -File $td | ForEach-Object {
+      $rel = $_.FullName.Substring($tRoot.Length + 1)
+      if (-not (Test-Path (Join-Path $sRoot $rel))) { Remove-Item $_.FullName -Force }
+    }
+  }
+}
+Get-ChildItem $Target -File -ErrorAction SilentlyContinue | ForEach-Object {
+  if (($_.Name -like 'README*.md' -or $top -contains $_.Name) -and -not (Test-Path (Join-Path $src $_.Name))) { Remove-Item $_.FullName -Force }
+}
+
+# Parity report: every scoped source file must exist in the target byte-for-byte.
+$checked = 0; $mismatch = 0
+foreach ($f in $top) {
+  $s = Join-Path $src $f; $t = Join-Path $Target $f
+  if (Test-Path $t) { $checked++; if ((Get-FileHash $s -Algorithm MD5).Hash -ne (Get-FileHash $t -Algorithm MD5).Hash) { $mismatch++; Write-Output "MISMATCH: $f" } }
+  else { $mismatch++; Write-Output "MISSING-TARGET: $f" }
+}
+foreach ($d in $dirs) {
+  $sd = Join-Path $src $d
+  $sRoot = (Resolve-Path $sd).Path
+  Get-ChildItem -Recurse -File $sd | ForEach-Object {
+    $rel = $_.FullName.Substring($sRoot.Length + 1)
+    $t = Join-Path (Join-Path $Target $d) $rel
+    if (Test-Path $t) { $checked++; if ((Get-FileHash $_.FullName -Algorithm MD5).Hash -ne (Get-FileHash $t -Algorithm MD5).Hash) { $mismatch++; Write-Output "MISMATCH: $d\$rel" } }
+    else { $mismatch++; Write-Output "MISSING-TARGET: $d\$rel" }
+  }
+}
+Write-Output "DONE: $checked scoped files verified, $mismatch mismatches -> $Target"
+if ($mismatch -gt 0) { exit 1 }
+exit 0

package/scripts/sync-official-docs.ps1

@@ -1,138 +1,138 @@
-# dsh-plugin-guide official-docs sync script.
-# Purpose: sync the deepseek-harness checkout's official docs into references/official-docs/ (verbatim copy).
-# Source is pinned to origin/master (HEAD fallback): untracked drafts and unpushed commits in the checkout never enter the KB.
-# Output: references/official-docs/SNAPSHOT.md (source ref/SHA, sync time, file counts - the freshness authority for READMEs).
-# Usage:  pwsh -File scripts/sync-official-docs.ps1 [-Checkout <path>] [-SkipGit]
-# Verify: pwsh -File scripts/verify-kit.ps1 -Checkout <path>   # drift report KB vs checkout (tracked files only)
-param(
-  [string]$Checkout = 'D:\deepseek-harness',
-  [switch]$SkipGit
-)
-$ErrorActionPreference = 'Stop'
-$kit  = Split-Path $PSScriptRoot -Parent
-$dest = Join-Path $kit 'references\official-docs'
-
-if (-not (Test-Path $Checkout)) { Write-Error "checkout not found: $Checkout"; exit 1 }
-
-$gitOk = $false
-if (-not $SkipGit) {
-  $gitOk = (& git -C $Checkout rev-parse --is-inside-work-tree 2>$null) -eq 'true'
-}
-
-$ref = 'filesystem'
-$sha = ''
-$pruned = 0
-$mdCount = 0
-$zhCount = 0
-
-# Sync scope: docs/, root AGENTS.md/BENCHMARK.md/CLAUDE.md/CONTRIBUTING.*/README.zh.md/README.i18n.yaml/THIRD_PARTY_NOTICES.md/LICENSE, packages/AGENTS.md, packages/README.md, vendor/README.md, website/docs.ts
-# Upstream root README.md is out of scope: official-docs/README.md is the KB-owned index (the upstream English README snapshot lives in downloads/github/harness/README.md).
-# Every pathspec uses the :(top) anchor so git's basename-wide matching cannot sweep in same-named symlinks (e.g. the various CLAUDE.md files).
-$paths = @(':(top)docs', ':(top)AGENTS.md', ':(top)BENCHMARK.md', ':(top)CONTRIBUTING.md', ':(top)CONTRIBUTING.zh.md', ':(top)CONTRIBUTING.i18n.yaml', ':(top)README.zh.md', ':(top)README.i18n.yaml', ':(top)THIRD_PARTY_NOTICES.md', ':(top)LICENSE', ':(top)packages/AGENTS.md', ':(top)packages/README.md', ':(top)vendor/README.md', ':(top)website/docs.ts')
-
-if ($gitOk) {
-  # Prefer origin/master, fall back to HEAD - never the working tree (may contain untracked/unpushed content).
-  if ((& git -C $Checkout rev-parse --verify -q origin/master 2>$null)) { $ref = 'origin/master' } else { $ref = 'HEAD' }
-  $sha = (& git -C $Checkout rev-parse $ref).Trim()
-
-  $tmp = Join-Path ([System.IO.Path]::GetTempPath()) ("dsh-official-docs-$sha.tar")
-  Remove-Item $tmp -Force -ErrorAction SilentlyContinue
-  & git -C $Checkout archive -o $tmp $ref -- $paths
-  if ($LASTEXITCODE -ne 0) { Write-Error "git archive failed (ref=$ref)"; exit 1 }
-
-  New-Item -ItemType Directory -Force -Path $dest | Out-Null
-  # Verbatim copy: clear the destination before extracting (keep only the KB-owned index README.md,
-  # which is unrelated to upstream), so structural residue from older snapshots (e.g. a top-level
-  # .agents/ directory from a previous tree) cannot interfere with the extraction.
-  Get-ChildItem -Force $dest | Where-Object { $_.Name -ne 'README.md' } | ForEach-Object {
-    Remove-Item $_.FullName -Recurse -Force; $pruned++
-  }
-  & tar -xf $tmp -C $dest
-  if ($LASTEXITCODE -ne 0) { Write-Error 'tar extraction failed'; exit 1 }
-  Remove-Item $tmp -Force
-
-  # CLAUDE.md is a symlink upstream (target AGENTS.md, mode 120000); Windows tar cannot extract
-  # symlinks, and the 'CLAUDE.md' pathspec would basename-match same-named symlinks deeper in the
-  # repo, so it stays out of $paths - after extraction its target text lands as a plain file
-  # (content = the upstream blob text).
-  $claudeTarget = (& git -C $Checkout cat-file -p "${ref}:CLAUDE.md" 2>$null | Select-Object -First 1)
-  if (-not $claudeTarget) { $claudeTarget = 'AGENTS.md' }
-  Set-Content -Path (Join-Path $dest 'CLAUDE.md') -Value $claudeTarget -Encoding UTF8
-
-  # website/docs.ts keeps its in-repo filename in the archive; move it to the KB's flat name.
-  if (Test-Path (Join-Path $dest 'website\docs.ts')) {
-    Copy-Item (Join-Path $dest 'website\docs.ts') (Join-Path $dest 'website-docs.ts') -Force
-    Remove-Item (Join-Path $dest 'website\docs.ts') -Force
-    Remove-Item (Join-Path $dest 'website') -Force -Recurse -ErrorAction SilentlyContinue
-  }
-
-  # Keep only in-scope entries at the destination root (drops stale extraction residue and
-  # upstream-deleted root files so the copy stays verbatim).
-  $rootKeep = @('docs','examples','packages','vendor','AGENTS.md','BENCHMARK.md','CLAUDE.md','CONTRIBUTING.md','CONTRIBUTING.zh.md','CONTRIBUTING.i18n.yaml','LICENSE','README.zh.md','README.i18n.yaml','THIRD_PARTY_NOTICES.md','SNAPSHOT.md','README.md','website-docs.ts')
-  Get-ChildItem -Force $dest | Where-Object { $rootKeep -notcontains $_.Name } | ForEach-Object {
-    Remove-Item $_.FullName -Recurse -Force; $pruned++
-  }
-  foreach ($sub in @('examples','packages','vendor')) {
-    $subDir = Join-Path $dest $sub
-    if (Test-Path $subDir) {
-      $subKeep = @()
-      if ($sub -eq 'examples') { $subKeep = @('AGENTS.md') }
-      if ($sub -eq 'packages') { $subKeep = @('AGENTS.md','README.md') }
-      if ($sub -eq 'vendor')   { $subKeep = @('README.md') }
-      Get-ChildItem -Force -Directory $subDir -ErrorAction SilentlyContinue | ForEach-Object {
-        Remove-Item $_.FullName -Recurse -Force; $pruned++
-      }
-      Get-ChildItem -Force -File $subDir -ErrorAction SilentlyContinue | Where-Object { $subKeep -notcontains $_.Name } | ForEach-Object {
-        Remove-Item $_.FullName -Force; $pruned++
-      }
-    }
-  }
-
-  # Prune docs/ files that no longer exist in the source ref (a verbatim copy does not keep upstream-deleted content).
-  $tracked = New-Object System.Collections.Generic.HashSet[string]
-  foreach ($t in (& git -C $Checkout ls-tree -r --name-only $ref -- docs)) { [void]$tracked.Add($t.Replace('\','/')) }
-  $docsDir = Join-Path $dest 'docs'
-  if (Test-Path $docsDir) {
-    $docsRoot = (Resolve-Path $docsDir).Path
-    Get-ChildItem -Recurse -File $docsDir | ForEach-Object {
-      $rel = 'docs/' + $_.FullName.Substring($docsRoot.Length + 1).Replace('\','/')
-      if (-not $tracked.Contains($rel)) { Remove-Item $_.FullName -Force; $pruned++ }
-    }
-  }
-} else {
-  Write-Output 'WARN: checkout is not a git repo (or -SkipGit) - copying the filesystem as-is; untracked files are not filtered and no pruning runs.'
-  foreach ($p in $paths) {
-    $rel = $p -replace '^:\(top\)',''   # strip the pathspec anchor to get the in-repo relative path
-    $srcFull = Join-Path $Checkout ($rel -replace '/','\')
-    if (-not (Test-Path $srcFull)) { Write-Output "SKIP(source missing): $rel"; continue }
-    $target = Join-Path $dest ($rel -replace '/','\')
-    $tdir = Split-Path $target -Parent
-    if ($tdir -and -not (Test-Path $tdir)) { New-Item -ItemType Directory -Force -Path $tdir | Out-Null }
-    Copy-Item $srcFull $target -Recurse -Force
-  }
-}
-
-$mdCount = (Get-ChildItem -Recurse -File (Join-Path $dest 'docs') -Filter *.md).Count
-$zhCount = (Get-ChildItem -Recurse -File (Join-Path $dest 'docs') -Filter *.zh.md).Count
-$utc = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')
-$L = @(
-  '# official-docs snapshot (SNAPSHOT.md)',
-  '',
-  '> Generated by `scripts/sync-official-docs.ps1`. This file is the single authority for how `references/official-docs/` lines up with upstream deepseek-harness.',
-  '> The "last verified" dates and commit SHAs in README/guide must cite this file; do not hand-edit them.',
-  '',
-  '| Item | Value |',
-  '|---|---|',
-  "| Source checkout | ``$Checkout`` |",
-  "| Source ref | ``$ref`` |",
-  "| Source commit | ``$sha`` |",
-  "| Synced at (UTC) | $utc |",
-  '| Scope | tracked files at the ref: `docs/`, root `AGENTS.md`, `BENCHMARK.md`, `CLAUDE.md` (symlink target text), `CONTRIBUTING.md`/`.zh.md`/`.i18n.yaml`, `README.zh.md`/`.i18n.yaml` (the upstream English `README.md` is not in this dir; its snapshot lives in `downloads/github/harness/README.md`), `THIRD_PARTY_NOTICES.md`, `LICENSE`, `packages/AGENTS.md`, `packages/README.md`, `vendor/README.md`, `website/docs.ts` |',
-  "| File counts | docs/: $mdCount md files ($zhCount .zh.md pairs) |",
-  "| Pruned this run | $pruned out-of-scope/upstream-deleted entries |",
-  '',
-  'Drift check: `pwsh -File scripts/verify-kit.ps1 -Checkout <checkout>` (tracked files only).'
-)
-Set-Content -Path (Join-Path $dest 'SNAPSHOT.md') -Value ($L -join "`r`n") -Encoding UTF8
-
-Write-Output "DONE: ref=$ref sha=$sha pruned=$pruned -> $dest"
+# dsh-plugin-guide official-docs sync script.
+# Purpose: sync the deepseek-harness checkout's official docs into references/official-docs/ (verbatim copy).
+# Source is pinned to origin/master (HEAD fallback): untracked drafts and unpushed commits in the checkout never enter the KB.
+# Output: references/official-docs/SNAPSHOT.md (source ref/SHA, sync time, file counts - the freshness authority for READMEs).
+# Usage:  pwsh -File scripts/sync-official-docs.ps1 [-Checkout <path>] [-SkipGit]
+# Verify: pwsh -File scripts/verify-kit.ps1 -Checkout <path>   # drift report KB vs checkout (tracked files only)
+param(
+  [string]$Checkout = 'D:\deepseek-harness',
+  [switch]$SkipGit
+)
+$ErrorActionPreference = 'Stop'
+$kit  = Split-Path $PSScriptRoot -Parent
+$dest = Join-Path $kit 'references\official-docs'
+
+if (-not (Test-Path $Checkout)) { Write-Error "checkout not found: $Checkout"; exit 1 }
+
+$gitOk = $false
+if (-not $SkipGit) {
+  $gitOk = (& git -C $Checkout rev-parse --is-inside-work-tree 2>$null) -eq 'true'
+}
+
+$ref = 'filesystem'
+$sha = ''
+$pruned = 0
+$mdCount = 0
+$zhCount = 0
+
+# Sync scope: docs/, root AGENTS.md/BENCHMARK.md/CLAUDE.md/CONTRIBUTING.*/README.zh.md/README.i18n.yaml/THIRD_PARTY_NOTICES.md/LICENSE, packages/AGENTS.md, packages/README.md, vendor/README.md, website/docs.ts
+# Upstream root README.md is out of scope: official-docs/README.md is the KB-owned index (the upstream English README snapshot lives in downloads/github/harness/README.md).
+# Every pathspec uses the :(top) anchor so git's basename-wide matching cannot sweep in same-named symlinks (e.g. the various CLAUDE.md files).
+$paths = @(':(top)docs', ':(top)AGENTS.md', ':(top)BENCHMARK.md', ':(top)CONTRIBUTING.md', ':(top)CONTRIBUTING.zh.md', ':(top)CONTRIBUTING.i18n.yaml', ':(top)README.zh.md', ':(top)README.i18n.yaml', ':(top)THIRD_PARTY_NOTICES.md', ':(top)LICENSE', ':(top)packages/AGENTS.md', ':(top)packages/README.md', ':(top)vendor/README.md', ':(top)website/docs.ts')
+
+if ($gitOk) {
+  # Prefer origin/master, fall back to HEAD - never the working tree (may contain untracked/unpushed content).
+  if ((& git -C $Checkout rev-parse --verify -q origin/master 2>$null)) { $ref = 'origin/master' } else { $ref = 'HEAD' }
+  $sha = (& git -C $Checkout rev-parse $ref).Trim()
+
+  $tmp = Join-Path ([System.IO.Path]::GetTempPath()) ("dsh-official-docs-$sha.tar")
+  Remove-Item $tmp -Force -ErrorAction SilentlyContinue
+  & git -C $Checkout archive -o $tmp $ref -- $paths
+  if ($LASTEXITCODE -ne 0) { Write-Error "git archive failed (ref=$ref)"; exit 1 }
+
+  New-Item -ItemType Directory -Force -Path $dest | Out-Null
+  # Verbatim copy: clear the destination before extracting (keep only the KB-owned index README.md,
+  # which is unrelated to upstream), so structural residue from older snapshots (e.g. a top-level
+  # .agents/ directory from a previous tree) cannot interfere with the extraction.
+  Get-ChildItem -Force $dest | Where-Object { $_.Name -ne 'README.md' } | ForEach-Object {
+    Remove-Item $_.FullName -Recurse -Force; $pruned++
+  }
+  & tar -xf $tmp -C $dest
+  if ($LASTEXITCODE -ne 0) { Write-Error 'tar extraction failed'; exit 1 }
+  Remove-Item $tmp -Force
+
+  # CLAUDE.md is a symlink upstream (target AGENTS.md, mode 120000); Windows tar cannot extract
+  # symlinks, and the 'CLAUDE.md' pathspec would basename-match same-named symlinks deeper in the
+  # repo, so it stays out of $paths - after extraction its target text lands as a plain file
+  # (content = the upstream blob text).
+  $claudeTarget = (& git -C $Checkout cat-file -p "${ref}:CLAUDE.md" 2>$null | Select-Object -First 1)
+  if (-not $claudeTarget) { $claudeTarget = 'AGENTS.md' }
+  Set-Content -Path (Join-Path $dest 'CLAUDE.md') -Value $claudeTarget -Encoding UTF8
+
+  # website/docs.ts keeps its in-repo filename in the archive; move it to the KB's flat name.
+  if (Test-Path (Join-Path $dest 'website\docs.ts')) {
+    Copy-Item (Join-Path $dest 'website\docs.ts') (Join-Path $dest 'website-docs.ts') -Force
+    Remove-Item (Join-Path $dest 'website\docs.ts') -Force
+    Remove-Item (Join-Path $dest 'website') -Force -Recurse -ErrorAction SilentlyContinue
+  }
+
+  # Keep only in-scope entries at the destination root (drops stale extraction residue and
+  # upstream-deleted root files so the copy stays verbatim).
+  $rootKeep = @('docs','examples','packages','vendor','AGENTS.md','BENCHMARK.md','CLAUDE.md','CONTRIBUTING.md','CONTRIBUTING.zh.md','CONTRIBUTING.i18n.yaml','LICENSE','README.zh.md','README.i18n.yaml','THIRD_PARTY_NOTICES.md','SNAPSHOT.md','README.md','website-docs.ts')
+  Get-ChildItem -Force $dest | Where-Object { $rootKeep -notcontains $_.Name } | ForEach-Object {
+    Remove-Item $_.FullName -Recurse -Force; $pruned++
+  }
+  foreach ($sub in @('examples','packages','vendor')) {
+    $subDir = Join-Path $dest $sub
+    if (Test-Path $subDir) {
+      $subKeep = @()
+      if ($sub -eq 'examples') { $subKeep = @('AGENTS.md') }
+      if ($sub -eq 'packages') { $subKeep = @('AGENTS.md','README.md') }
+      if ($sub -eq 'vendor')   { $subKeep = @('README.md') }
+      Get-ChildItem -Force -Directory $subDir -ErrorAction SilentlyContinue | ForEach-Object {
+        Remove-Item $_.FullName -Recurse -Force; $pruned++
+      }
+      Get-ChildItem -Force -File $subDir -ErrorAction SilentlyContinue | Where-Object { $subKeep -notcontains $_.Name } | ForEach-Object {
+        Remove-Item $_.FullName -Force; $pruned++
+      }
+    }
+  }
+
+  # Prune docs/ files that no longer exist in the source ref (a verbatim copy does not keep upstream-deleted content).
+  $tracked = New-Object System.Collections.Generic.HashSet[string]
+  foreach ($t in (& git -C $Checkout ls-tree -r --name-only $ref -- docs)) { [void]$tracked.Add($t.Replace('\','/')) }
+  $docsDir = Join-Path $dest 'docs'
+  if (Test-Path $docsDir) {
+    $docsRoot = (Resolve-Path $docsDir).Path
+    Get-ChildItem -Recurse -File $docsDir | ForEach-Object {
+      $rel = 'docs/' + $_.FullName.Substring($docsRoot.Length + 1).Replace('\','/')
+      if (-not $tracked.Contains($rel)) { Remove-Item $_.FullName -Force; $pruned++ }
+    }
+  }
+} else {
+  Write-Output 'WARN: checkout is not a git repo (or -SkipGit) - copying the filesystem as-is; untracked files are not filtered and no pruning runs.'
+  foreach ($p in $paths) {
+    $rel = $p -replace '^:\(top\)',''   # strip the pathspec anchor to get the in-repo relative path
+    $srcFull = Join-Path $Checkout ($rel -replace '/','\')
+    if (-not (Test-Path $srcFull)) { Write-Output "SKIP(source missing): $rel"; continue }
+    $target = Join-Path $dest ($rel -replace '/','\')
+    $tdir = Split-Path $target -Parent
+    if ($tdir -and -not (Test-Path $tdir)) { New-Item -ItemType Directory -Force -Path $tdir | Out-Null }
+    Copy-Item $srcFull $target -Recurse -Force
+  }
+}
+
+$mdCount = (Get-ChildItem -Recurse -File (Join-Path $dest 'docs') -Filter *.md).Count
+$zhCount = (Get-ChildItem -Recurse -File (Join-Path $dest 'docs') -Filter *.zh.md).Count
+$utc = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')
+$L = @(
+  '# official-docs snapshot (SNAPSHOT.md)',
+  '',
+  '> Generated by `scripts/sync-official-docs.ps1`. This file is the single authority for how `references/official-docs/` lines up with upstream deepseek-harness.',
+  '> The "last verified" dates and commit SHAs in README/guide must cite this file; do not hand-edit them.',
+  '',
+  '| Item | Value |',
+  '|---|---|',
+  "| Source checkout | ``$Checkout`` |",
+  "| Source ref | ``$ref`` |",
+  "| Source commit | ``$sha`` |",
+  "| Synced at (UTC) | $utc |",
+  '| Scope | tracked files at the ref: `docs/`, root `AGENTS.md`, `BENCHMARK.md`, `CLAUDE.md` (symlink target text), `CONTRIBUTING.md`/`.zh.md`/`.i18n.yaml`, `README.zh.md`/`.i18n.yaml` (the upstream English `README.md` is not in this dir; its snapshot lives in `downloads/github/harness/README.md`), `THIRD_PARTY_NOTICES.md`, `LICENSE`, `packages/AGENTS.md`, `packages/README.md`, `vendor/README.md`, `website/docs.ts` |',
+  "| File counts | docs/: $mdCount md files ($zhCount .zh.md pairs) |",
+  "| Pruned this run | $pruned out-of-scope/upstream-deleted entries |",
+  '',
+  'Drift check: `pwsh -File scripts/verify-kit.ps1 -Checkout <checkout>` (tracked files only).'
+)
+Set-Content -Path (Join-Path $dest 'SNAPSHOT.md') -Value ($L -join "`r`n") -Encoding UTF8
+
+Write-Output "DONE: ref=$ref sha=$sha pruned=$pruned -> $dest"

package/scripts/verify-artifacts.mjs

@@ -58,6 +58,32 @@ try {
     const readmeCount = readdirSync(target).filter((f) => /^README(-\w{2})?\.md$/.test(f)).length
     check(result.status === 0 && hasEntry && hasPatch, `${lang} scaffold produces entry + cordis.patch.yml (exit ${result.status})`)
     check(readmeCount === 5, `${lang} scaffold produces 5 README languages (${readmeCount})`)
+
+    // Round-trip the scaffolder through the checker. This is the assertion whose
+    // absence let `new --lang js` fail `check` for as long as it did: the
+    // scaffolder and the checker disagreed about whether a build-artifact
+    // directory is mandatory, and nothing ever ran one against the other. The
+    // golden path a user follows is exactly this pair, so it is the pair the
+    // artifact gate must exercise.
+    const scaffoldCheck = runNode(['dist/dsh-plugin-dev.js', 'check', '--cwd', target, '--json'], { stdio: ['ignore', 'pipe', 'pipe'] })
+    let scaffoldOk = false
+    let scaffoldDetail = ''
+    try {
+      const parsed = JSON.parse(scaffoldCheck.stdout)
+      scaffoldOk = parsed.ok === true
+      if (!scaffoldOk) {
+        scaffoldDetail = (parsed.checks ?? [])
+          .filter((c) => c.status === 'fail')
+          .map((c) => c.id)
+          .join(', ')
+      }
+    } catch {
+      scaffoldDetail = 'unparseable --json output'
+    }
+    check(
+      scaffoldCheck.status === 0 && scaffoldOk,
+      `${lang} scaffold passes the checker (exit ${scaffoldCheck.status}${scaffoldDetail ? `; failing: ${scaffoldDetail}` : ''})`,
+    )
   }
 
   // 3b. Extension contract for the TS scaffold. `platform: node` makes tsdown