create-harness-vibe-coding 0.8.12 → 0.8.13

package/README-CN.md

@@ -191,8 +191,20 @@ node Harness/scripts/validate-harness.mjs
 
 # bootstrap 完成后或发布前
 node Harness/scripts/validate-harness.mjs --strict
+
+# 发布更新版本后
+npm run check:mirrors
 ```
 
+## 发布门禁
+
+铁律：每次 Harness 更新发版都必须同时保持两个更新通道可用：
+
+- Canonical：npm `create-harness-vibe-coding@latest` 和 `https://github.com/LiWeny16/create-harness-vibe-coding`
+- 低版本兼容镜像：`https://github.com/zingspark/create-harness-vibe-coding`
+
+低版本用户的 updater 可能已经硬编码到旧的 `zingspark` 仓库。发布不能只更新新仓库；必须等 legacy mirror 拥有同一份 commit、tag 和生成后的 template manifest，才算发版完成。新安装生成的 `Harness/.harness-version` 仍然记录 canonical `LiWeny16` source；`zingspark` 只作为旧用户兼容镜像保留。
+
 ## 适配范围与体积
 
 - 支持 Claude Code、Codex 和 OpenCode 的共享 Harness 工作流。

package/README.md

@@ -189,8 +189,20 @@ node Harness/scripts/validate-harness.mjs
 
 # Generated project after bootstrap or before release
 node Harness/scripts/validate-harness.mjs --strict
+
+# After publishing an update release
+npm run check:mirrors
 ```
 
+## Release gate
+
+Iron rule: every update release must keep both update channels live:
+
+- Canonical: npm `create-harness-vibe-coding@latest` and `https://github.com/LiWeny16/create-harness-vibe-coding`
+- Legacy compatibility mirror: `https://github.com/zingspark/create-harness-vibe-coding`
+
+Low-version installs can have updater scripts hardcoded to the legacy mirror. Do not mark a release complete until the legacy mirror exposes the same commit, tag, and generated template manifest as canonical. Generated installs still record the canonical `LiWeny16` source; the `zingspark` repo is kept for backward compatibility.
+
 ## Footprint
 
 | | |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-harness-vibe-coding",
-  "version": "0.8.12",
+  "version": "0.8.13",
   "description": "Scaffold a 0-1 product harness for AI-assisted research, PRD, planning, architecture, build, test, and feedback loops",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
   "scripts": {
     "start": "node src/index.js",
     "build:version": "node scripts/build-version.mjs",
+    "check:mirrors": "node scripts/check-update-mirrors.mjs",
     "prepush": "node scripts/pre-push-check.mjs",
     "test": "node --test tests/*.test.js",
     "test:e2e": "node tests/e2e-wf-scripts.test.mjs",

package/src/index.js

@@ -9,6 +9,7 @@ import { generate, getOptionalCatalog } from './generator.js';
 
 const UPDATE_SUCCESS_STATUSES = new Set(['up-to-date', 'update-available', 'partial-update']);
 const UPDATE_FAILURE_STATUSES = new Set(['error', 'offline', 'template-remote', 'downgrade-refused']);
+const CANONICAL_UPDATE_SOURCE_BASE = 'https://raw.githubusercontent.com/LiWeny16/create-harness-vibe-coding/main/templates/common/';
 
 // ── CLI flags ──────────────────────────────────────────────
 const raw = process.argv.slice(2);
@@ -515,6 +516,7 @@ function runUpdateSwitch(scan, { json }) {
   console.log(pc.yellow('Existing Harness detected. Switching to wf-update check.'));
   console.log(pc.dim(`Directory   ${scan.resolvedDir}`));
   console.log(pc.dim('Command     node Harness/scripts/wf-update-check.mjs'));
+  console.log(pc.dim(`Source      ${CANONICAL_UPDATE_SOURCE_BASE}`));
   console.log('');
 
   if (!updateResult.success && updateResult.error) {
@@ -555,12 +557,14 @@ function createUpdateSwitchResult(scan, { json }) {
       updateCommand: json
         ? 'node Harness/scripts/wf-update-check.mjs --json'
         : 'node Harness/scripts/wf-update-check.mjs',
+      updateSourceBase: CANONICAL_UPDATE_SOURCE_BASE,
       next: [
         {
           action: 'update',
           command: json
             ? 'node Harness/scripts/wf-update-check.mjs --json'
             : 'node Harness/scripts/wf-update-check.mjs',
+          env: { WF_SOURCE_BASE: CANONICAL_UPDATE_SOURCE_BASE },
           reason: 'Harness already exists, so updates must use the installed Harness update flow.',
         },
       ],
@@ -589,6 +593,10 @@ function createUpdateSwitchResult(scan, { json }) {
   const result = spawnSync(process.execPath, args, {
     cwd: scan.resolvedDir,
     encoding: 'utf8',
+    env: {
+      ...process.env,
+      WF_SOURCE_BASE: CANONICAL_UPDATE_SOURCE_BASE,
+    },
   });
   const stdout = result.stdout || '';
   const stderr = result.stderr || '';

package/templates/common/.claude/commands/wf-update.md

@@ -4,7 +4,7 @@ Run the Harness update checker script. Do not invoke a skill or start WF mode.
 
 ## Flow
 
-1. Run `node Harness/scripts/wf-update-check.mjs --json` and use the `agent` block as the action plan.
+1. Run `node Harness/scripts/wf-update-check.mjs --json` and use the `agent` block as the action plan. Current updaters try npm `create-harness-vibe-coding@latest` first, then the canonical GitHub source `LiWeny16/create-harness-vibe-coding`, then the legacy compatibility mirror `zingspark/create-harness-vibe-coding`.
 2. Preserve all PRESERVE files. Never overwrite user task, memory, research, README, package, or architecture files.
 3. If `agent.safeApplyCommand` is present, run it to apply SAFE/NEW files first.
 4. For conflicts, compare local with `templateHint` or `remoteUrl`, decide merge/keep-local/overwrite, and record via `--accept-local`, `--accept-merged`, or `--accept-template`.
@@ -22,3 +22,9 @@ npx create-harness-vibe-coding@latest <project-name> . -y --on-conflict skip
 ```
 
 This creates missing Harness files while preserving CLAUDE.md, README.md, tasks, memory, research, and all user data. After recovery, re-run the update check.
+
+If an old updater reports only `0.8.10`, run the latest installer command above or re-run the checker with:
+
+```
+node Harness/scripts/wf-update-check.mjs --json --source-base https://raw.githubusercontent.com/LiWeny16/create-harness-vibe-coding/main/templates/common/
+```

package/templates/common/.claude/skills/wf-update/SKILL.md

@@ -23,7 +23,10 @@ This skill is a Codex compatibility shim plus script-flow reference. Claude Code
 ## Flow
 
 1. Run `node Harness/scripts/wf-update-check.mjs --json` first and use the
-   `agent` block as the action plan.
+   `agent` block as the action plan. Current updaters try npm
+   `create-harness-vibe-coding@latest` first, then the canonical GitHub source
+   `LiWeny16/create-harness-vibe-coding`, then the legacy compatibility mirror
+   `zingspark/create-harness-vibe-coding`.
 2. Preserve all PRESERVE files. Never overwrite user task, memory, research,
    README, package, or architecture files.
 3. If `agent.safeApplyCommand` is present, run it to apply SAFE, NEW, and
@@ -50,6 +53,13 @@ npx create-harness-vibe-coding@latest <project-name> . -y --on-conflict skip
 
 The `--on-conflict skip` policy preserves all existing user files (CLAUDE.md, README.md, tasks, memory, research, architecture) and only creates missing Harness infrastructure files. After recovery, re-run the update check.
 
+If an old updater reports only `0.8.10`, run the latest installer command above
+or re-run the checker with:
+
+```
+node Harness/scripts/wf-update-check.mjs --json --source-base https://raw.githubusercontent.com/LiWeny16/create-harness-vibe-coding/main/templates/common/
+```
+
 ## Return
 
 Report version, SAFE/NEW updates, conflicts and decisions, preserved files,

package/templates/common/.harness-version

@@ -1,9 +1,9 @@
 {
-  "generator": "0.8.12",
-  "generated": "2026-07-22T08:15:49.785Z",
+  "generator": "0.8.13",
+  "generated": "2026-07-22T09:32:47.044Z",
   "options": [],
   "autoCheck": true,
-  "source": "https://raw.githubusercontent.com/zingspark/create-harness-vibe-coding/main/templates/common/",
+  "source": "https://raw.githubusercontent.com/LiWeny16/create-harness-vibe-coding/main/templates/common/",
   "checksums": {
     ".agents/skills/subagent-orchestrator/SKILL.md": "sha256-8d9e8c0db4647bcf168a5f99c8b2ea97d154bfca30e78ffd1cc5a98ce185bb1d",
     ".agents/skills/tdd/SKILL.md": "sha256-1e2ec0b54a5cf5b071800b0f2e5672a128a42471e16f70f00bb4c0a07a3617cb",
@@ -14,7 +14,7 @@
     ".agents/skills/wf-readme/SKILL.md": "sha256-4d34ee3b6b305fa2581f5d8cb31e9152759f3df8bf8fa08efbb43782f128bdcd",
     ".agents/skills/wf-remove/SKILL.md": "sha256-21ebef1a1fa8645d094c8ceeca78b33f036b6c42cda6db8be425d38d9e91af75",
     ".agents/skills/wf-review/SKILL.md": "sha256-ab1122cbc9612ba734f98736e5479d7777206293d011d5471aaa34d1da35dae6",
-    ".agents/skills/wf-update/SKILL.md": "sha256-6fa16fd5a526969837b9fd5fcae6aed55eec5ccd755e0a9cddcb7065878f61d8",
+    ".agents/skills/wf-update/SKILL.md": "sha256-a0942270455063911bfc603fe6e5fad3e0247e845fc8095e5b4a54fc883e1fba",
     ".agents/skills/wf/SKILL.md": "sha256-53225645b593f4cf060781590f9b3025cf17315baad4e2acce850cc4cd972f97",
     ".claude/agents/architect-manager.md": "sha256-d98c3a2d044d5216d9bcde217b4359b1c33f5be152416e242807652ddcd2868b",
     ".claude/agents/architect.md": "sha256-61cea40c8c3e01bd53f3ad642ef734850fdb931497e7ee20552ea7a8b4e7b70c",
@@ -36,7 +36,7 @@
     ".claude/agents/test-writer.md": "sha256-724866d627f193caaf060ec6af97b1d54c2df2d5c5f937e78fc3c53c7f798b16",
     ".claude/agents/verifier.md": "sha256-d501a505b97e679daa89ee1d910ee185edc42ba57d58203e962b1c5a844c0872",
     ".claude/commands/wf-help.md": "sha256-aaaa6834c6cb61d2ecbeb41ad8fcf77de10ac1638b2009a3822284c01cf41fac",
-    ".claude/commands/wf-update.md": "sha256-1988e82eb60311b8208367e3c8e22e6222ae05f4b0f645fa9a0e426790705c12",
+    ".claude/commands/wf-update.md": "sha256-5a92a2b32952b6dac6b9ef318c63bc049d68c9dbf2623370a116c4fe602392dd",
     ".claude/rules/ecc/common.md": "sha256-e5f046d02ec9f5d326088f608c63758632d9a5f6c67688b20e065b6380884992",
     ".claude/settings.json": "sha256-99e8552584b8e71e3e11b4b760c3bfbf8c1b18dadda7ec3f6e3c46f88d9ea513",
     ".claude/skills/subagent-orchestrator/SKILL.md": "sha256-8d9e8c0db4647bcf168a5f99c8b2ea97d154bfca30e78ffd1cc5a98ce185bb1d",
@@ -48,7 +48,7 @@
     ".claude/skills/wf-readme/SKILL.md": "sha256-4d34ee3b6b305fa2581f5d8cb31e9152759f3df8bf8fa08efbb43782f128bdcd",
     ".claude/skills/wf-remove/SKILL.md": "sha256-21ebef1a1fa8645d094c8ceeca78b33f036b6c42cda6db8be425d38d9e91af75",
     ".claude/skills/wf-review/SKILL.md": "sha256-ab1122cbc9612ba734f98736e5479d7777206293d011d5471aaa34d1da35dae6",
-    ".claude/skills/wf-update/SKILL.md": "sha256-6fa16fd5a526969837b9fd5fcae6aed55eec5ccd755e0a9cddcb7065878f61d8",
+    ".claude/skills/wf-update/SKILL.md": "sha256-a0942270455063911bfc603fe6e5fad3e0247e845fc8095e5b4a54fc883e1fba",
     ".claude/skills/wf/SKILL.md": "sha256-53225645b593f4cf060781590f9b3025cf17315baad4e2acce850cc4cd972f97",
     ".codex/config.toml": "sha256-e0af046982c6dbc535c52b19610d16ce9aba08a17dd29f11b74cc8dad8371145",
     ".codex/hooks.json": "sha256-3200c42c2da434c07cd6ab1ce86f8845ab46a1ed9a25b65117b2b2b42056c725",
@@ -79,7 +79,7 @@
     ".opencode/commands/wf-readme.md": "sha256-276e80255bd38f51e17b158650d182401304bf06388407d259f47850306556e8",
     ".opencode/commands/wf-remove.md": "sha256-fe9823152c4f74e66b151e352de7167436d1bc47376c2a688d190391931d300a",
     ".opencode/commands/wf-review.md": "sha256-4bd59f66bc96c2773868e63c37cbacf39dd521555e997c0b60d50538ef2d5dbd",
-    ".opencode/commands/wf-update.md": "sha256-1988e82eb60311b8208367e3c8e22e6222ae05f4b0f645fa9a0e426790705c12",
+    ".opencode/commands/wf-update.md": "sha256-5a92a2b32952b6dac6b9ef318c63bc049d68c9dbf2623370a116c4fe602392dd",
     ".opencode/commands/wf.md": "sha256-d86cf20a78c37757f76aed7e252475fb82e7597cd55c6a4c916441b3b75fe9af",
     ".opencode/plugins/harness-wf-status.mjs": "sha256-ee0987cec5530c34784c619a803562d7085ae26fe5d199fde7ce42c2bed4724e",
     "AGENTS.md": "sha256-fad176931742a5080e073d1ddba99a3eabb67e8c42bebb132df99a51ca6a184d",
@@ -109,11 +109,11 @@
     "Harness/lifecycle.md": "sha256-a2d025e52f3b4412d8439083aca0d2cf7a4458ad0e30de4fc6465f990379190f",
     "Harness/research/README.md": "sha256-956c154df01cb9376972eb8b88bb3be0fe4e2dda802a72457c0126e3476fa755",
     "Harness/scripts/archive-tasks.mjs": "sha256-07bba20c2f4b3baae737b8b9a951125a48e37dd482a1f1ca122b9cf88e90e956",
-    "Harness/scripts/scan-clean.mjs": "sha256-1278900563545d67d1d4057d66a03a95f5e9aede0d33ac5d6d0837a72a38d4b0",
+    "Harness/scripts/scan-clean.mjs": "sha256-2b414738317cfe41432926b72691edb55ce313ff2427fd1312c1947bf687da61",
     "Harness/scripts/validate-harness.mjs": "sha256-a6174f918453943387df8015664f81599ea74a179bec351d22187ec0a19a1e7c",
     "Harness/scripts/wf-auto-update-prompt.mjs": "sha256-14210304dbd8e648b8939fc4c5d3664f943052153e689264c16b05b7b81bd39e",
     "Harness/scripts/wf-remove.mjs": "sha256-576bc92325bf63d4142eb6028d095f12abf9d845a1a178dfe247b813794476a9",
-    "Harness/scripts/wf-update-check.mjs": "sha256-8d883930676126f4308ecdfedd3fccb7c62e170c8086723ed2c10d44e580a7e1",
+    "Harness/scripts/wf-update-check.mjs": "sha256-40044032d6b4a3307e6dc5ea978d18c010936342d41f3324b3a2b92abe6646c4",
     "Harness/subagents.md": "sha256-f2e81c21792b4d70c64c9bd22e9548d783d945dddb3504b4937e04ca1d04320d",
     "Harness/templates/ACCEPTANCE.template.md": "sha256-394a6c08b155b1d121f1d51da774f7988bdb891224c6d5f2ca2c131e8c95ffb3",
     "Harness/templates/API_CONTRACT.template.md": "sha256-e11ec9866576624982f35e77359e3f4ef3aea3e3f6b5895f6cc5419d29699fc5",

package/templates/common/.opencode/commands/wf-update.md

@@ -4,7 +4,7 @@ Run the Harness update checker script. Do not invoke a skill or start WF mode.
 
 ## Flow
 
-1. Run `node Harness/scripts/wf-update-check.mjs --json` and use the `agent` block as the action plan.
+1. Run `node Harness/scripts/wf-update-check.mjs --json` and use the `agent` block as the action plan. Current updaters try npm `create-harness-vibe-coding@latest` first, then the canonical GitHub source `LiWeny16/create-harness-vibe-coding`, then the legacy compatibility mirror `zingspark/create-harness-vibe-coding`.
 2. Preserve all PRESERVE files. Never overwrite user task, memory, research, README, package, or architecture files.
 3. If `agent.safeApplyCommand` is present, run it to apply SAFE/NEW files first.
 4. For conflicts, compare local with `templateHint` or `remoteUrl`, decide merge/keep-local/overwrite, and record via `--accept-local`, `--accept-merged`, or `--accept-template`.
@@ -22,3 +22,9 @@ npx create-harness-vibe-coding@latest <project-name> . -y --on-conflict skip
 ```
 
 This creates missing Harness files while preserving CLAUDE.md, README.md, tasks, memory, research, and all user data. After recovery, re-run the update check.
+
+If an old updater reports only `0.8.10`, run the latest installer command above or re-run the checker with:
+
+```
+node Harness/scripts/wf-update-check.mjs --json --source-base https://raw.githubusercontent.com/LiWeny16/create-harness-vibe-coding/main/templates/common/
+```

package/templates/common/Harness/scripts/scan-clean.mjs

@@ -19,11 +19,16 @@ import { readFileSync, writeFileSync, existsSync, lstatSync, readdirSync, unlink
 import { resolve, dirname, sep, join } from 'path';
 import { fileURLToPath } from 'url';
 import { createInterface } from 'readline';
+import { gunzipSync } from 'zlib';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = process.env.WF_ROOT ? resolve(process.env.WF_ROOT) : resolve(__dirname, '..', '..');
 const VERSION_FILE = resolve(ROOT, 'Harness', '.harness-version');
+const NPM_PACKAGE = 'create-harness-vibe-coding';
+const NPM_REGISTRY = (process.env.NPM_CONFIG_REGISTRY || 'https://registry.npmjs.org').replace(/\/+$/, '');
+const TEMPLATE_SUBPATH = 'templates/common/';
 const DEFAULT_SOURCE_BASE = 'https://raw.githubusercontent.com/LiWeny16/create-harness-vibe-coding/main/templates/common/';
+const LEGACY_SOURCE_BASE = 'https://raw.githubusercontent.com/zingspark/create-harness-vibe-coding/main/templates/common/';
 
 // ── Classification constants ────────────────────────────────────────
 
@@ -151,6 +156,73 @@ async function fetchRemote(url, timeoutMs = 30000) {
   }
 }
 
+async function fetchBytes(url, timeoutMs = 30000) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: controller.signal, headers: { 'User-Agent': 'harness-scan-clean' } });
+    if (!res.ok) throw new Error(`HTTP ${res.status}: ${url}`);
+    return Buffer.from(await res.arrayBuffer());
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function tarString(header, start, length) {
+  const slice = header.subarray(start, start + length);
+  const zero = slice.indexOf(0);
+  return Buffer.from(zero === -1 ? slice : slice.subarray(0, zero)).toString('utf8').trim();
+}
+
+function parseTarFiles(buffer) {
+  const files = new Map();
+  for (let offset = 0; offset + 512 <= buffer.length;) {
+    const header = buffer.subarray(offset, offset + 512);
+    if (header.every(byte => byte === 0)) break;
+
+    const name = tarString(header, 0, 100);
+    const prefix = tarString(header, 345, 155);
+    const size = Number.parseInt(tarString(header, 124, 12) || '0', 8) || 0;
+    const type = String.fromCharCode(header[156] || 0);
+    const fullName = prefix ? `${prefix}/${name}` : name;
+    const dataStart = offset + 512;
+
+    if ((type === '\0' || type === '0' || type === '') && fullName) {
+      files.set(fullName, buffer.subarray(dataStart, dataStart + size));
+    }
+
+    offset = dataStart + Math.ceil(size / 512) * 512;
+  }
+  return files;
+}
+
+async function fetchNpmLatestManifest() {
+  const meta = JSON.parse(await fetchRemote(`${NPM_REGISTRY}/${NPM_PACKAGE}/latest`, 15000));
+  const tarball = meta?.dist?.tarball;
+  if (!tarball) throw new Error(`npm metadata missing dist.tarball for ${NPM_PACKAGE}@latest`);
+  const files = parseTarFiles(gunzipSync(await fetchBytes(tarball, 30000)));
+  const manifest = files.get(`package/${TEMPLATE_SUBPATH}.harness-version`);
+  if (!manifest) throw new Error('npm package missing templates/common/.harness-version');
+  return Buffer.from(manifest).toString('utf8');
+}
+
+async function fetchRemoteManifest(explicitSource) {
+  if (explicitSource) return fetchRemote(normalizeSourceBase(explicitSource) + '.harness-version');
+  try {
+    return await fetchNpmLatestManifest();
+  } catch (npmError) {
+    try {
+      return await fetchRemote(DEFAULT_SOURCE_BASE + '.harness-version');
+    } catch (canonicalError) {
+      try {
+        return await fetchRemote(LEGACY_SOURCE_BASE + '.harness-version');
+      } catch (legacyError) {
+        throw new Error(`npm latest: ${npmError.message}; canonical GitHub: ${canonicalError.message}; legacy mirror: ${legacyError.message}`);
+      }
+    }
+  }
+}
+
 // ── Orphan detection ─────────────────────────────────────────────────
 
 /**
@@ -285,7 +357,7 @@ async function main() {
   const clean = args.includes('--clean');
   const yes = args.includes('--yes');
   const jsonOut = args.includes('--json');
-  const sourceBase = normalizeSourceBase(readFlagValue(args, '--source-base') || process.env.WF_SOURCE_BASE || DEFAULT_SOURCE_BASE);
+  const explicitSource = readFlagValue(args, '--source-base') || process.env.WF_SOURCE_BASE;
 
   // 1. Read local state
   if (!existsSync(VERSION_FILE)) {
@@ -314,7 +386,7 @@ async function main() {
   // 2. Fetch remote version file
   let remoteVersion;
   try {
-    const raw = await fetchRemote(sourceBase + '.harness-version');
+    const raw = await fetchRemoteManifest(explicitSource);
     if (isTemplate(raw)) {
       if (jsonOut) {
         console.log(JSON.stringify({ status: 'error', message: 'Remote .harness-version is a template (contains {{placeholders}}). Cannot determine dead files.' }));
@@ -328,9 +400,9 @@ async function main() {
     remoteVersion = JSON.parse(raw);
   } catch (e) {
     if (jsonOut) {
-      console.log(JSON.stringify({ status: 'error', message: 'Cannot reach GitHub or invalid remote JSON: ' + e.message }));
+      console.log(JSON.stringify({ status: 'error', message: 'Cannot reach npm, canonical GitHub, or legacy mirror update sources: ' + e.message }));
     } else {
-      console.error('ERROR: Cannot reach GitHub or invalid remote JSON. Offline?');
+      console.error('ERROR: Cannot reach npm, canonical GitHub, or legacy mirror update sources. Offline?');
       console.error(e.message);
     }
     process.exit(1);

package/templates/common/Harness/scripts/wf-update-check.mjs

@@ -19,15 +19,22 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, lstatSync } from 'f
 import { createHash } from 'crypto';
 import { resolve, dirname, sep } from 'path';
 import { fileURLToPath } from 'url';
+import { gunzipSync } from 'zlib';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = process.env.WF_ROOT ? resolve(process.env.WF_ROOT) : resolve(__dirname, '..', '..');
 const VERSION_FILE = resolve(ROOT, 'Harness', '.harness-version');
+const NPM_PACKAGE = 'create-harness-vibe-coding';
+const NPM_REGISTRY = (process.env.NPM_CONFIG_REGISTRY || 'https://registry.npmjs.org').replace(/\/+$/, '');
 const GITHUB_REPO = 'LiWeny16/create-harness-vibe-coding';
+const LEGACY_GITHUB_REPO = 'zingspark/create-harness-vibe-coding';
 const GITHUB_LATEST_STABLE = `https://api.github.com/repos/${GITHUB_REPO}/releases/latest`;
 const RAW_GITHUB = `https://raw.githubusercontent.com/${GITHUB_REPO}`;
+const LEGACY_RAW_GITHUB = `https://raw.githubusercontent.com/${LEGACY_GITHUB_REPO}`;
 const TEMPLATE_SUBPATH = 'templates/common/';
 const DEFAULT_SOURCE_BASE = `${RAW_GITHUB}/main/${TEMPLATE_SUBPATH}`;
+const LEGACY_SOURCE_BASE = `${LEGACY_RAW_GITHUB}/main/${TEMPLATE_SUBPATH}`;
+const npmPackageCache = new Map();
 
 // Tier classification
 
@@ -185,6 +192,47 @@ async function fetchRemote(url, timeoutMs = 30000) {
   }
 }
 
+async function fetchBytes(url, timeoutMs = 30000) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: controller.signal, headers: { 'User-Agent': 'harness-wf-update-check' } });
+    if (!res.ok) throw new Error(`HTTP ${res.status}: ${url}`);
+    return Buffer.from(await res.arrayBuffer());
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function tarString(header, start, length) {
+  const slice = header.subarray(start, start + length);
+  const zero = slice.indexOf(0);
+  return Buffer.from(zero === -1 ? slice : slice.subarray(0, zero)).toString('utf8').trim();
+}
+
+function parseTarFiles(buffer) {
+  const files = new Map();
+  for (let offset = 0; offset + 512 <= buffer.length;) {
+    const header = buffer.subarray(offset, offset + 512);
+    if (header.every(byte => byte === 0)) break;
+
+    const name = tarString(header, 0, 100);
+    const prefix = tarString(header, 345, 155);
+    const sizeText = tarString(header, 124, 12);
+    const size = Number.parseInt(sizeText || '0', 8) || 0;
+    const type = String.fromCharCode(header[156] || 0);
+    const fullName = prefix ? `${prefix}/${name}` : name;
+    const dataStart = offset + 512;
+
+    if ((type === '\0' || type === '0' || type === '') && fullName) {
+      files.set(fullName, buffer.subarray(dataStart, dataStart + size));
+    }
+
+    offset = dataStart + Math.ceil(size / 512) * 512;
+  }
+  return files;
+}
+
 // Main
 
 function isPrerelease(v) {
@@ -192,7 +240,74 @@ function isPrerelease(v) {
   return /-[0-9A-Za-z.-]+/.test(v.replace(/^[^0-9]*/, ''));
 }
 
-async function resolveStableSourceBase() {
+function parseSemver(v) {
+  if (!v || typeof v !== 'string') return [0, 0, 0];
+  return v.replace(/^[^0-9]*/, '').split('.').slice(0, 3).map(n => Number(n) || 0);
+}
+
+function cmpSemver(a, b) {
+  const va = parseSemver(a), vb = parseSemver(b);
+  for (let i = 0; i < 3; i++) {
+    if ((va[i] || 0) > (vb[i] || 0)) return 1;
+    if ((va[i] || 0) < (vb[i] || 0)) return -1;
+  }
+  return 0;
+}
+
+async function loadNpmPackage(version = 'latest') {
+  const cacheKey = `${NPM_REGISTRY}:${version}`;
+  if (npmPackageCache.has(cacheKey)) return npmPackageCache.get(cacheKey);
+
+  const metaUrl = `${NPM_REGISTRY}/${NPM_PACKAGE}/${version}`;
+  const meta = JSON.parse(await fetchRemote(metaUrl, 15000));
+  const packageVersion = meta.version;
+  const tarball = meta?.dist?.tarball;
+  if (!packageVersion || !tarball) throw new Error(`npm metadata missing dist.tarball for ${NPM_PACKAGE}@${version}`);
+
+  const archive = gunzipSync(await fetchBytes(tarball, 30000));
+  const files = parseTarFiles(archive);
+  const loaded = { version: packageVersion, tarball, files };
+  npmPackageCache.set(cacheKey, loaded);
+  npmPackageCache.set(`${NPM_REGISTRY}:${packageVersion}`, loaded);
+  return loaded;
+}
+
+function readNpmFile(pkg, templateRelPath) {
+  const key = `package/${TEMPLATE_SUBPATH}${templateRelPath}`;
+  const content = pkg.files.get(key);
+  if (!content) throw new Error(`npm package missing ${key}`);
+  return Buffer.from(content).toString('utf8');
+}
+
+async function createNpmSource(version = 'latest') {
+  const pkg = await loadNpmPackage(version);
+  const raw = readNpmFile(pkg, '.harness-version');
+  if (isTemplate(raw)) throw new Error('npm .harness-version has not been generated yet');
+  const manifest = JSON.parse(raw);
+  return {
+    kind: 'npm',
+    stable: true,
+    label: `npm:${NPM_PACKAGE}@${pkg.version}/${TEMPLATE_SUBPATH}`,
+    version: pkg.version,
+    manifest,
+    package: pkg,
+  };
+}
+
+async function createUrlSource(sourceBase, { stable = false } = {}) {
+  const base = normalizeSourceBase(sourceBase);
+  const raw = await fetchRemote(base + '.harness-version');
+  if (isTemplate(raw)) throw new Error('remote .harness-version has not been generated yet');
+  return {
+    kind: 'url',
+    stable,
+    label: base,
+    base,
+    manifest: JSON.parse(raw),
+  };
+}
+
+async function resolveGithubReleaseSource() {
   try {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), 15000);
@@ -209,26 +324,45 @@ async function resolveStableSourceBase() {
     const data = JSON.parse(await res.text());
     const tag = data && data.tag_name;
     if (!tag || data.prerelease) return null;
-    const source = `${RAW_GITHUB}/${tag}/${TEMPLATE_SUBPATH}`;
-    const versionController = new AbortController();
-    const versionTimer = setTimeout(() => versionController.abort(), 15000);
-    try {
-      const versionRes = await fetch(source + '.harness-version', {
-        signal: versionController.signal,
-        headers: { 'User-Agent': 'harness-wf-update-check' },
-      });
-      if (!versionRes.ok) return null;
-      const raw = await versionRes.text();
-      if (isTemplate(raw)) return null;
-    } finally {
-      clearTimeout(versionTimer);
-    }
-    return source;
+    return await createUrlSource(`${RAW_GITHUB}/${tag}/${TEMPLATE_SUBPATH}`, { stable: true });
   } catch {
     return null;
   }
 }
 
+async function resolveUpdateSource(explicitSource) {
+  if (explicitSource) {
+    return createUrlSource(explicitSource, { stable: false });
+  }
+
+  const errors = [];
+  try {
+    return await createNpmSource('latest');
+  } catch (e) {
+    errors.push(`npm latest: ${e.message}`);
+  }
+
+  const releaseSource = await resolveGithubReleaseSource();
+  if (releaseSource) return releaseSource;
+  errors.push('GitHub latest release: unavailable');
+
+  try {
+    return await createUrlSource(DEFAULT_SOURCE_BASE, { stable: false });
+  } catch (e) {
+    errors.push(`GitHub canonical main: ${e.message}`);
+  }
+
+  try {
+    return await createUrlSource(LEGACY_SOURCE_BASE, { stable: false });
+  } catch (e) {
+    errors.push(`GitHub legacy mirror: ${e.message}`);
+  }
+
+  const err = new Error('Cannot reach npm, canonical GitHub, or legacy mirror update sources.');
+  err.sourceErrors = errors;
+  throw err;
+}
+
 async function main() {
   const args = process.argv.slice(2);
   const apply = args.includes('--apply');
@@ -240,14 +374,16 @@ async function main() {
   const acceptTemplate = readRepeatedFlagValues(args, '--accept-template');
   const ignoreVersion = args.includes('--ignore-version') || args.includes('--force-check');
   const explicitSource = readFlagValue(args, '--source-base') || process.env.WF_SOURCE_BASE;
-  let sourceBase = normalizeSourceBase(explicitSource || DEFAULT_SOURCE_BASE);
-  let stableTagResolved = false;
-  if (!explicitSource) {
-    const resolved = await resolveStableSourceBase();
-    if (resolved) {
-      sourceBase = normalizeSourceBase(resolved);
-      stableTagResolved = true;
-    }
+  let source;
+  let sourceBase;
+  let sourceStable = false;
+  let sourceErrors = [];
+  try {
+    source = await resolveUpdateSource(explicitSource);
+    sourceBase = source.label;
+    sourceStable = Boolean(source.stable);
+  } catch (e) {
+    sourceErrors = e.sourceErrors || [e.message];
   }
 
   // 1. Read local state
@@ -302,44 +438,23 @@ async function main() {
 
   const localChecksums = localVersion.checksums || {};
 
-  // 2. Fetch remote version file
-  let remoteVersion;
-  try {
-    const raw = await fetchRemote(sourceBase + '.harness-version');
-    if (isTemplate(raw)) {
-      if (jsonOut) {
-        console.log(JSON.stringify({ status: 'template-remote', message: 'Remote .harness-version has not been generated yet.' }));
-      } else {
-        console.log('WARN: Remote .harness-version is a template (contains {{placeholders}}).');
-        console.log('  The generate step has not been run on the remote repo. No update possible.');
-        console.log('  This is expected during development; the update mechanism works once the remote is live.');
-      }
-      process.exitCode = 1;
-      return;
-    }
-    remoteVersion = JSON.parse(raw);
-  } catch (e) {
+  // 2. Read remote version metadata from the selected update source.
+  let remoteVersion = source?.manifest;
+  if (!remoteVersion) {
     if (jsonOut) {
-      console.log(JSON.stringify({ status: 'offline', message: 'Cannot reach GitHub.' }));
+      console.log(JSON.stringify({
+        status: 'offline',
+        message: 'Cannot reach npm, canonical GitHub, or legacy mirror update sources.',
+        sourceErrors,
+      }));
     } else {
-      console.error('ERROR: Cannot reach GitHub or invalid JSON. Offline?');
-      console.error(e.message);
+      console.error('ERROR: Cannot reach npm, canonical GitHub, or legacy mirror update sources. Offline?');
+      for (const err of sourceErrors) console.error(`  ${err}`);
     }
     process.exitCode = 1;
     return;
   }
 
-  // Compare versions and prevent downgrades from explicit custom sources.
-  function parseSemver(v) {
-    if (!v || typeof v !== 'string') return [0, 0, 0];
-    return v.replace(/^[^0-9]*/, '').split('.').slice(0, 3).map(n => Number(n) || 0);
-  }
-  function cmpSemver(a, b) {
-    const va = parseSemver(a), vb = parseSemver(b);
-    for (let i = 0; i < 3; i++) { if ((va[i]||0) > (vb[i]||0)) return 1; if ((va[i]||0) < (vb[i]||0)) return -1; }
-    return 0;
-  }
-
   const localGen = localVersion.generator || '0.0.0';
   const remoteGen = remoteVersion.generator || '0.0.0';
 
@@ -355,7 +470,7 @@ async function main() {
   const versionCmp = cmpSemver(remoteGen, localGen);
 
   if (!ignoreVersion && versionCmp <= 0) {
-    const reportDowngrade = !stableTagResolved;
+    const reportDowngrade = !sourceStable;
     if (jsonOut) {
       console.log(JSON.stringify({
         status: (versionCmp < 0 && reportDowngrade) ? 'downgrade-refused' : 'up-to-date',
@@ -385,13 +500,23 @@ async function main() {
     return remoteSources[file] || file;
   }
 
+  async function fetchSourceFile(templateRelPath) {
+    if (source.kind === 'npm') return readNpmFile(source.package, templateRelPath);
+    return fetchRemote(source.base + templateRelPath);
+  }
+
+  function sourceUrl(templateRelPath) {
+    if (source.kind === 'npm') return `${source.label}${templateRelPath}`;
+    return source.base + templateRelPath;
+  }
+
   function withRemoteMeta(entry) {
     if (!entry || !entry.file || !remoteChecksums[entry.file]) return entry;
     const templateHint = remotePath(entry.file);
     return {
       ...entry,
       templateHint,
-      remoteUrl: sourceBase + templateHint,
+      remoteUrl: sourceUrl(templateHint),
     };
   }
 
@@ -459,7 +584,7 @@ async function main() {
     const dest = safePath(file);
     if (!dest) throw new Error(`Traversal rejected: ${file}`);
     if (existsSync(dest) && lstatSync(dest).isSymbolicLink()) throw new Error(`Symlink rejected: ${file}`);
-    const content = await fetchRemote(sourceBase + remotePath(file));
+    const content = await fetchSourceFile(remotePath(file));
     const normalized = content.replace(/\r\n/g, '\n');
     const fetchedHash = sha256(normalized);
     if (fetchedHash !== remoteHash) throw new Error(`Hash mismatch: ${file}`);
@@ -678,56 +803,62 @@ async function main() {
       console.log(`Applying SAFE/NEW files only; ${plan.conflict.length} conflicts will remain for AI/user merge.`);
     }
 
-    const lexists = existsSync;
-    let applied = 0;
+    const preparedWrites = [];
     let failed = 0;
 
-    for (const u of plan.updated) {
+    async function prepareWrite(entry, { mustNotExist = false } = {}) {
       try {
-        const dest = safePath(u.file);
-        if (!dest) { console.error(`   x Traversal rejected: ${u.file}`); failed++; continue; }
+        const dest = safePath(entry.file);
+        if (!dest) { console.error(`   x Traversal rejected: ${entry.file}`); failed++; return; }
         // Symlink rejection: do not follow symlinks.
-        if (lexists(dest)) {
-          try { if (lstatSync(dest).isSymbolicLink()) { console.error(`   x Symlink rejected: ${u.file}`); failed++; continue; } } catch (_) {}
+        if (existsSync(dest)) {
+          try { if (lstatSync(dest).isSymbolicLink()) { console.error(`   x Symlink rejected: ${entry.file}`); failed++; return; } } catch (_) {}
+          if (mustNotExist) {
+            console.error(`   x File created since plan: ${entry.file} - treating as CONFLICT`);
+            failed++; return;
+          }
         }
-        const content = await fetchRemote(sourceBase + remotePath(u.file));
+        const content = await fetchSourceFile(remotePath(entry.file));
         const normalized = content.replace(/\r\n/g, '\n');
         const fetchedHash = sha256(normalized);
-        if (fetchedHash !== u.remoteHash) {
-          console.error(`   x Hash mismatch: ${u.file}`);
-          failed++; continue;
+        if (fetchedHash !== entry.remoteHash) {
+          console.error(`   x Hash mismatch: ${entry.file}`);
+          failed++; return;
         }
-        mkdirSync(dirname(dest), { recursive: true });
-        writeFileSync(dest, normalized, 'utf-8');
-        applied++;
+        preparedWrites.push({ file: entry.file, dest, content: normalized, mustNotExist });
       } catch (e) {
-        console.error(`   x Failed: ${u.file} - ${e.message}`);
+        console.error(`   x Failed: ${entry.file} - ${e.message}`);
         failed++;
       }
     }
 
+    for (const u of plan.updated) {
+      await prepareWrite(u);
+    }
+
     for (const c of plan.created) {
-      try {
-        const dest = safePath(c.file);
-        if (!dest) { console.error(`   x Traversal rejected: ${c.file}`); failed++; continue; }
-        // TOCTOU: recheck file didn't appear since planning
-        if (lexists(dest)) {
-          try { if (lstatSync(dest).isSymbolicLink()) { console.error(`   x Symlink rejected: ${c.file}`); failed++; continue; } } catch (_) {}
-          console.error(`   x File created since plan: ${c.file} - treating as CONFLICT`);
-          failed++; continue;
+      await prepareWrite(c, { mustNotExist: true });
+    }
+
+    if (failed === 0) {
+      for (const prepared of preparedWrites) {
+        if (prepared.mustNotExist && existsSync(prepared.dest)) {
+          console.error(`   x File created since plan: ${prepared.file} - treating as CONFLICT`);
+          failed++;
         }
-        const content = await fetchRemote(sourceBase + remotePath(c.file));
-        const normalized = content.replace(/\r\n/g, '\n');
-        const fetchedHash = sha256(normalized);
-        if (fetchedHash !== c.remoteHash) {
-          console.error(`   x Hash mismatch: ${c.file}`);
-          failed++; continue;
+      }
+    }
+
+    let applied = 0;
+    if (failed === 0) {
+      try {
+        for (const prepared of preparedWrites) {
+          mkdirSync(dirname(prepared.dest), { recursive: true });
+          writeFileSync(prepared.dest, prepared.content, 'utf-8');
+          applied++;
         }
-        mkdirSync(dirname(dest), { recursive: true });
-        writeFileSync(dest, normalized, 'utf-8');
-        applied++;
       } catch (e) {
-        console.error(`   x Failed: ${c.file} - ${e.message}`);
+        console.error(`   x Failed while writing prepared files - ${e.message}`);
         failed++;
       }
     }