@educa-corp/sdd-framework 0.9.1 → 0.9.3

package/docs/plans/qc-sync-command.md

@@ -0,0 +1,359 @@
+# Plan — lệnh sync skill QC từ upstream vào framework
+
+> Tài liệu này là **phần 2** của [`qc-merge-plan.md`](qc-merge-plan.md).
+> Plan kia trả lời *"gộp cái gì, và ba quyết định nào đang chặn"*.
+> Plan này trả lời *"về sau QC sửa skill thì làm sao đưa vào framework mà không vỡ"*.
+
+| | |
+|---|---|
+| Snapshot | `upstream/qc-base/` — 82 file, 10.008 dòng, **không ship** (ngoài `package.json` `files`) |
+| Upstream | `D:\projects\ui-automation-testing` @ `596149f` (git repo thật → pin được) |
+| Đích | `skills/qc/qa-*` (35 file) + 6 lệnh `commands/qc-*.tmpl` |
+| Trạng thái | plan — chưa code |
+
+---
+
+## 1 · Vì sao đây không phải copy file
+
+Ba lý do, xếp theo độ khó tăng dần.
+
+### (a) Ánh xạ không phải 1:1
+
+```
+upstream                          framework
+qa-tc-analyst  (1 agent)   ─┬──►  /qc-analyze   (trạm 1)  +  skills/qc/qa-analyst/
+  23 skill                  └──►  /qc-plan      (trạm 2)  +  skills/qc/qa-planner/
+```
+
+Một đơn vị upstream nở ra hai đơn vị framework. `test-plan.md` của `qa-tc-analyst`
+đã nằm ở `qa-planner/`. Copy theo thư mục là sai ngay từ bước đầu.
+
+### (b) File được **adapt**, không phải copy
+
+Cả 4 file trùng tên đều khác nội dung, và khác có chủ ý:
+
+| | upstream | framework | framework thêm gì |
+|---|---|---|---|
+| `business-rules` | 90 dòng | 59 | `{paths.qc_dir}` · rào *"chỉ trả 2 file"* |
+| `acceptance-criteria` | 57 | 60 | như trên |
+| `data-flow` | 61 | 64 | như trên |
+| `spec-breakdown` | 58 | 61 | như trên |
+
+Copy đè = **xoá sạch phần adapt**. Và `business-rules` bản upstream **dài hơn 31 dòng** —
+nên chiều ngược lại cũng đúng: bản framework có thể đã cắt mất nội dung thật, không chỉ đổi path.
+
+### (c) Đây là bài toán **merge ba chiều**, và hiện đang thiếu một chiều
+
+Khi QC sửa `business-rules.md`, có ba bản:
+
+```
+        BASE                    THEIRS                  OURS
+   bản upstream mà          bản upstream mới         bản framework
+   framework đã port từ                              đã adapt
+        │                         │                       │
+        └────────── diff A ───────┘                       │
+                 "QC đã đổi gì"                           │
+        └──────────────────── diff B ──────────────────────┘
+                       "ta đã adapt gì"
+
+   Không có BASE  ⇒  không phân biệt được A với B
+                 ⇒  mọi merge đều là đoán
+```
+
+**`upstream/qc-base/` chính là BASE** — nhưng chỉ khi nó được **pin**: ghi lại nó ứng với
+commit upstream nào. Một thư mục snapshot không có pin thì chỉ là "một bản copy cũ nào đó",
+không dùng làm base merge được.
+
+> **Đây là lý do kiến trúc của toàn bộ plan này:** lệnh cần dựng không phải lệnh copy,
+> mà là một **vendor-branch merge tool có pin**.
+
+---
+
+## 2 · Ba tạo tác phải có trước khi viết lệnh
+
+### 2.1 · Pin — `upstream/qc-base/.pin.json`
+
+```json
+{
+  "upstream": {
+    "repo": "ui-automation-testing",
+    "url": "<git remote>",
+    "ref": "main",
+    "commit": "596149f",
+    "captured_at": "2026-08-24"
+  },
+  "files": {
+    "skills/qa-tc-analyst/business-rules.md": "sha1…",
+    "skills/qa-tc-analyst/gap-verifier.md":   "sha1…"
+  }
+}
+```
+
+Hash từng file, không chỉ commit. Lý do: snapshot có thể bị sửa tay (ai đó "sửa nhanh một
+dòng trong `upstream/`"), và lúc đó base không còn là base. Hash bắt được, commit thì không.
+
+### 2.2 · Bản đồ ánh xạ — `bin/qc-base-map.json`
+
+Đây là tạo tác quan trọng nhất. Mỗi entry trả lời: file upstream này đi đâu, adapt thế nào,
+ai chịu trách nhiệm.
+
+```json
+{
+  "map": [
+    {
+      "upstream": "skills/qa-tc-analyst/business-rules.md",
+      "targets": ["skills/qc/qa-analyst/business-rules.md"],
+      "adapt": ["path-placeholders", "two-file-guard"],
+      "state": "ported",
+      "base_sha": "sha1 của bản upstream đã port từ"
+    },
+    {
+      "upstream": "skills/qa-tc-analyst/gap-verifier.md",
+      "targets": ["steps/gap-verify.md"],
+      "adapt": ["path-placeholders", "generalize-doc-gap-to-findings"],
+      "state": "planned",
+      "note": "P0 — dùng chung cho refine-prd / review-context / qc-analyze"
+    },
+    {
+      "upstream": "skills/qa-tc-designer/manual-excel-testcase.md",
+      "targets": [],
+      "state": "skipped",
+      "why": "README upstream khai đã bỏ nhánh manual-Excel; file còn sót"
+    },
+    {
+      "upstream": "skills/qa-gate/styled-report-template.py",
+      "targets": [],
+      "state": "undecided",
+      "why": "script thật, không phải prompt — framework QC hiện 100% markdown-first"
+    }
+  ]
+}
+```
+
+**Bốn `state`, và cái thứ tư là cái quan trọng:**
+
+| state | Nghĩa |
+|---|---|
+| `ported` | đã đưa vào, có `base_sha` để merge lần sau |
+| `planned` | đã quyết sẽ đưa, chưa làm |
+| `skipped` | **cố ý** không đưa, có lý do ghi lại |
+| `undecided` | chưa ai quyết ← **đây là hàng đợi việc** |
+
+File upstream **không có entry nào** = bị bỏ quên trong im lặng. Đó là failure mode duy nhất
+mà bản đồ này tồn tại để chặn — và §5 để máy canh nó.
+
+### 2.3 · Luật adapt dạng **dữ liệu**, không phải người nhớ
+
+```json
+{
+  "adapt_rules": {
+    "path-placeholders": [
+      { "from": "inputs/free-trial-spec/specs/", "to": "{paths.specs_dir}/" },
+      { "from": "docs/<feature>/",              "to": "{paths.qc_dir}/{TICKET-ID}/{active_platform}/",
+        "note": "sau B11 phép map này gần như đồng nhất — upstream vốn đã là cấp feature (`docs/<feature>/`); chỉ thêm một cấp nền" },
+      { "from": "inputs/",                      "to": "{paths.specs_dir}/", "note": "khái niệm nguồn-evidence" }
+    ],
+    "two-file-guard": { "kind": "append-block", "block": "…rào 'chỉ trả 2 file'…" },
+    "orchestrator-to-agent-mode": {
+      "kind": "manual",
+      "why": "upstream nhận routing plan từ qa-orchestrator; framework dùng gate Bước 0 _agent_mode. Không map máy được."
+    }
+  }
+}
+```
+
+Ba loại luật: **thay chuỗi** (máy làm) · **chèn block** (máy làm) · **`manual`** (buộc người
+xem, lệnh dừng lại hỏi). Loại thứ ba là chỗ tránh được cái bẫy "tool tự tin adapt sai".
+
+> **37 file upstream hardcode `inputs/…`** — đây là khối lượng chính của `path-placeholders`.
+
+---
+
+## 3 · Chia việc: script làm phần cơ học, lệnh làm phần phán đoán
+
+Framework đã có tiền lệ cho cách chia này: `bin/lint-trace.js` (script, chạy được trong CI)
+vs `/validate-traces` (LLM, không chạy được trong CI thường). Áp đúng khuôn đó.
+
+```
+bin/qc-sync.js                          /sync-qc-base  (lệnh markdown)
+─────────────────────────────           ────────────────────────────────
+hash + so pin                           "thay đổi này thuộc trạm 1 hay trạm 2?"
+diff ba chiều                           "skill mới này có thuộc phạm vi framework?"
+áp adapt_rules loại string/block        áp adapt_rules loại `manual`
+bookkeeping pin + base_sha              đọc diff, quyết giữ/bỏ phần adapt của ta
+phát hiện entry thiếu / mồ côi          viết lại đoạn cần diễn đạt theo giọng framework
+in báo cáo máy-đọc-được                 CHECKPOINT trước khi ghi
+─────────────────────────────           ────────────────────────────────
+deterministic · CI-able · --dry-run     cần người · cần ngữ cảnh · có gate
+```
+
+Nguyên tắc: **script không bao giờ tự ghi vào `skills/qc/qa-*` hay `commands/`
+khi có `manual` rule hoặc conflict.** Nó dựng patch + báo; lệnh mới là chỗ quyết.
+
+---
+
+## 4 · Sáu lệnh con
+
+Framework không dùng sub-command thật — nó dùng cờ trên một lệnh (`--resume`, `--fix`,
+`--full`). Giữ đúng quy ước đó:
+
+```
+/sync-qc-base [--status] [--pull] [--diff] [--port] [--adopt] [--verify]
+```
+
+| Cờ | Trả lời câu | Đọc | Ghi | Chặn |
+|---|---|---|---|---|
+| `--status` *(mặc định)* | "upstream đi trước ta bao nhiêu?" | pin, snapshot, map, upstream | — | không |
+| `--pull` | "lấy bản upstream mới về snapshot" | upstream git | `upstream/qc-base/` + `.pin.json` | không¹ |
+| `--diff` | "QC đổi gì, ta adapt gì, có đè nhau không?" | 3 chiều | — | không |
+| `--port` | "đưa thay đổi upstream vào file framework" | 3 chiều + adapt_rules | `skills/qc/qa-*`, `commands/*.tmpl` | **CỨNG** |
+| `--adopt` | "nhận một skill upstream CHƯA có trong map" | snapshot + map | map entry + file đích mới | **CỨNG** |
+| `--verify` | "pin/map/frontmatter còn khớp nhau không?" | tất cả | — | không |
+
+¹ `--pull` không chặn vì nó chỉ đụng `upstream/` — nhưng nó **phải** cảnh báo nếu snapshot
+đang bị sửa tay (hash lệch pin), vì lúc đó base sắp bị ghi đè mất.
+
+### Chi tiết từng cờ
+
+**`--status`** — bức ảnh một màn hình:
+```
+Snapshot : 596149f (2026-08-24)   Upstream: a3f21c8 (2026-09-02)  → đi trước 7 commit
+Đổi      : 12 file
+           ├─ 4 ported     → cần --port
+           ├─ 2 planned    → chưa làm, không ảnh hưởng
+           ├─ 1 skipped    → bỏ qua đúng chủ ý
+           └─ 5 KHÔNG CÓ TRONG MAP  ← chạy --adopt hoặc khai skipped
+Framework: 1 file đã bị sửa tay sau lần port (base_sha lệch) → --diff xem trước
+```
+
+**`--pull`** — làm mới snapshot. Không đụng framework. Ba việc: fetch/checkout ref,
+ghi lại `.pin.json`, và **giữ bản pin cũ** thành `.pin.prev.json` — vì merge ba chiều lần
+`--port` sau cần BASE là bản *trước khi* pull.
+
+> Đây là chỗ dễ sai nhất của cả thiết kế: `--pull` mà không lưu base cũ thì `--port`
+> mất chiều thứ ba, và ta quay về đúng vấn đề §1(c).
+
+**`--diff`** — bề mặt review. Mỗi file đổi, in ba khối: QC đổi gì · ta adapt gì · hai cái
+có chạm nhau không. Chạm nhau = conflict thật, cần người.
+
+**`--port`** — merge + adapt + ghi. Chặn CỨNG (`--yes` không bỏ được) vì nó ghi đè file
+framework đã có. Với mỗi file: 3-way merge → áp `adapt_rules` string/block → gặp rule
+`manual` hoặc conflict thì **để lại** vào file findings, không tự quyết → cập nhật
+`base_sha` cho các file đã port sạch.
+
+**`--adopt`** — đường vào cho skill upstream mới (và cho **P1** của plan kia: 18 skill của
+`qa-tc-analyst` chưa có đều đi qua đây). Việc nó làm: hỏi đích (`skills/qc/…`? `steps/`?
+một `commands/*.tmpl`?), hỏi `adapt` nào áp, dựng bản adapt đầu tiên, tạo entry map với
+`state: ported` + `base_sha`.
+
+**`--verify`** — invariant check, chạy được trong CI:
+
+| Kiểm | Bắt lỗi gì |
+|---|---|
+| mọi file snapshot có entry trong map | **skill upstream bị bỏ quên im lặng** |
+| entry map trỏ tới file tồn tại (cả 2 phía) | map lỗi thời sau khi upstream đổi tên |
+| `base_sha` của entry `ported` khớp một file snapshot | base đã trôi, merge lần sau sẽ sai |
+| frontmatter `upstream_path` + `upstream_sha` của file đích khớp map | file đích bị sửa tay ngoài luồng |
+| `skills/qc/qa-*` không còn chuỗi `inputs/` sót | adapt làm nửa vời |
+| lệnh `qc-*` không trỏ vào skill đã mất | **đúng lỗi vừa xảy ra hôm nay** |
+
+---
+
+## 5 · Rule máy canh — `R16`
+
+`--verify` là lệnh người gọi. Nhưng framework này có một nguyên tắc lặp lại năm lần trong
+loạt GAP: *luật đúng, viết rõ, và không ai canh*. Nên phần **cốt lõi** của `--verify` phải
+thành rule trong `bin/self-check.js`, fail build:
+
+```
+R16 — snapshot upstream và framework không được trôi khỏi nhau trong im lặng
+
+  a) mọi file trong upstream/qc-base/ phải có entry trong bin/qc-base-map.json
+     → thiếu entry = bị bỏ quên. state `skipped` là câu trả lời hợp lệ; VẮNG MẶT thì không.
+  b) mọi entry `state: ported` phải có base_sha, và base_sha phải khớp file snapshot
+  c) mọi target của entry `ported` phải tồn tại
+  d) mọi lệnh qc-* trỏ vào {paths.qc_skills_dir}/X phải có X tồn tại trong skills/qc/
+```
+
+**(d) là rule đáng lẽ đã chặn sự cố hôm nay** — 35 file skill bị xoá, `self-check` xanh,
+`build` xanh, `.agent` vẫn chạy được nên dogfood không phát hiện, và installer thì sẽ
+*chủ động xoá* chúng ở project người dùng. Ba tầng che nhau, không tầng nào bắt.
+
+`R16(d)` **đáng làm ngay, độc lập với toàn bộ plan này.**
+
+---
+
+## 6 · Luồng điển hình
+
+```
+QC push skill mới
+     │
+     ▼
+/sync-qc-base --status      "đi trước 7 commit, 12 file đổi, 5 chưa có trong map"
+     │
+     ▼
+/sync-qc-base --pull        snapshot: 596149f → a3f21c8   (giữ .pin.prev.json)
+     │
+     ▼
+/sync-qc-base --diff        đọc: QC đổi gì · ta adapt gì · chỗ nào chạm nhau
+     │
+     ├──► 5 file chưa có trong map
+     │        │
+     │        ▼
+     │    /sync-qc-base --adopt    quyết đích + adapt cho từng cái
+     │
+     ▼
+/sync-qc-base --port        CHECKPOINT CỨNG → merge + adapt → conflict ra findings
+     │
+     ▼
+node bin/self-check.js      R16 xanh
+node bin/build.js           41/41
+     │
+     ▼
+/sync-qc-base --verify      invariant sạch
+```
+
+---
+
+## 7 · Phase triển khai
+
+| Phase | Việc | Phụ thuộc |
+|---|---|---|
+| **S0** | **`R16(d)`** — rule chặn "lệnh qc-* trỏ vào skill không tồn tại" | không · **làm ngay** |
+| **S1** | Dựng `.pin.json` cho snapshot hiện tại (`596149f`) + hash 82 file | không |
+| **S2** | Dựng `bin/qc-base-map.json` — 82 entry. Phần lớn là `undecided`, 5 là `ported` (4 analyst + test-plan), phần còn lại phân loại dần | S1 |
+| **S3** | `bin/qc-sync.js` — `--status` + `--verify` trước (read-only, rẻ, có giá trị ngay) | S1, S2 |
+| **S4** | `R16(a)(b)(c)` vào `self-check.js` | S2 |
+| **S5** | `--pull` + `--diff` (vẫn read-only với framework) | S3 |
+| **S6** | `--adopt` — rồi dùng chính nó chạy **P1** của plan kia (18 skill analyst) | S5 |
+| **S7** | `--port` — merge ba chiều. Phần khó nhất, làm cuối | S6 |
+
+> **Thứ tự này có chủ ý:** mọi thứ read-only xong trước, ghi-file để sau cùng.
+> `--status` + `--verify` đã trả giá trị (biết mình đang lệch bao nhiêu) trước khi
+> viết một dòng logic merge nào.
+
+Và `--adopt` (S6) đứng **trước** `--port` (S7) vì `--adopt` là việc phải làm ngay
+(18 skill đang chờ), còn `--port` chỉ cần khi QC push lần sửa đầu tiên.
+
+---
+
+## 8 · Câu chưa quyết
+
+| # | Câu | Ghi chú |
+|---|---|---|
+| 1 | `upstream/qc-base/` **track git hay không?** | Nên track — cần nó làm BASE và cần diff được qua lịch sử. Đổi lại: +10k dòng vào repo. |
+| 2 | Snapshot lấy bằng **copy tay** hay **git submodule**? | Submodule đúng bản chất hơn nhưng `--pull` phức tạp hơn, và submodule *là* moving target trong khi BASE cần đóng băng. Copy + pin đơn giản hơn, tôi nghiêng về nó. |
+| 3 | `bin/qc-base-map.json` hay gộp vào `bin/trace-schema.json`? | Tách riêng: đây không phải contract về trace. Nhưng `self-check.js` phải đọc cả hai. |
+| 4 | 2 file `.py` của `qa-gate` xử sao? | `state: undecided`. Framework QC hiện 100% markdown-first — nhận script là đổi một nguyên tắc. |
+| 5 | `ported_from: ai-automation-qc-base` đang **sai tên repo** (thật là `ui-automation-testing`) | Sửa luôn khi thêm `upstream_path` + `upstream_sha` vào frontmatter. |
+| 6 | `shared/` của upstream — framework có nhận khái niệm này? | `qa-tc-designer/shared/` 7 file dùng chung. Framework hiện "mỗi skill tự đủ". Nhận `shared/` là đổi kiến trúc skill. |
+| 7 | `read-doc-gap-inputs.md` tồn tại **2 bản khác nội dung** (designer + reviewer) | Trùng tên khác ruột — chọn sai là sai im lặng. Phải chốt 1 bản, hoặc map thành 2 entry riêng. |
+
+---
+
+## Liên quan
+
+- [`qc-implementation-log.md`](qc-implementation-log.md) — nhật ký triển khai, viết cho người không cần biết code
+
+- [`qc-merge-plan.md`](qc-merge-plan.md) — gộp cái gì, ba quyết định đang chặn (§5), plan P0–P4
+- `--adopt` (S6 ở đây) **chính là** P1 của plan kia — không phải hai việc, là một việc có công cụ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@educa-corp/sdd-framework",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Spec Driven Development workflow framework for Claude Code",
   "bin": {
     "sdd-framework": "./bin/index.js"

package/scripts/migrate-qc-docs.js

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+/**
+ * migrate-qc-docs — move per-UC QC working docs into the per-PRD layout.
+ *
+ *   docs/{TICKET-ID}-UC{N}/{platform}/…
+ *     → docs/{TICKET-ID}/{platform}/…
+ *
+ * The per-UC layout shattered one feature across N sibling folders (10 UCs = 10 root
+ * folders, 30 files). It was the framework's own imposition when the QC skills were
+ * ported: upstream has always been PRD-scoped — their real file is `DOC_GAP_FEAT-02-3.md`
+ * (no UC suffix), the gap-ID format `GAP-<UC>-001` only means anything when ONE file holds
+ * several UCs, and `qa-planner/test-plan.md` says "Test Plan cho một feature". See B11.
+ *
+ * WHY THIS SCRIPT DOES NOT MERGE. Collapsing N UC folders into one makes UC1's
+ * REQUIREMENT_ANALYSIS.md and UC2's collide on the same target path, and two prose
+ * documents cannot be merged mechanically. So:
+ *
+ *   test-cases/*   → MOVED   (filenames carry <FEATURE>, they do not collide)
+ *   the 3 top docs → ARCHIVED to {qc}/_archive-per-uc/{UC-ID}/{platform}/
+ *                    and listed as NEEDS REGENERATE
+ *
+ * Regenerating beats hand-merging: a PRD-level pass reads the PRD, design-spec and
+ * tech-doc ONCE instead of once per UC, and it sees cross-UC contradictions that N
+ * separate passes structurally cannot. Nothing is deleted — the archive is the way back,
+ * and the only way to check whether the PRD-level run caught anything the old ones missed.
+ *
+ * Also folds in the pending `DOC_GAPS.md` → `DOC_GAP.md` rename (B9), in the same pass,
+ * including for folders that are ALREADY in the new layout. Without it `/qc-plan` reports
+ * "DOC_GAP not found" while the analysis sits right there under the old name.
+ *
+ * Reports (does NOT guess) two conditions that need a human:
+ *   - NO PLATFORM : files sit directly under {qc}/{UC-ID}/ with no platform level. The
+ *                   platform cannot be inferred from a QC artifact, so they are left alone.
+ *   - OCCUPIED    : the target path already holds a file — moving would overwrite it.
+ *
+ * DRY-RUN by default (prints the plan, changes nothing). Pass --apply to execute.
+ * Tracked files move with `git mv` to preserve history; the rest with fs.rename.
+ *
+ * Usage (from the consumer project root):
+ *   node scripts/migrate-qc-docs.js                 # dry-run, prints plan
+ *   node scripts/migrate-qc-docs.js --apply         # execute
+ *   node scripts/migrate-qc-docs.js --qc docs --root .
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// ── args ──────────────────────────────────────────────────────────────────────
+const argv = process.argv.slice(2);
+const has = f => argv.includes(f);
+const flag = (f, d) => { const i = argv.indexOf(f); return i !== -1 ? argv[i + 1] : d; };
+
+const APPLY = has('--apply');
+const ROOT = path.resolve(flag('--root', '.'));
+const QC = flag('--qc', 'docs');
+
+const qcAbs = path.join(ROOT, QC);
+const ARCHIVE = '_archive-per-uc';
+
+// The three PRD-level documents. Anything else at that level is archived too (safe
+// default) but called out separately so nobody loses a file without seeing its name.
+const TOP_DOCS = ['REQUIREMENT_ANALYSIS.md', 'DOC_GAP.md', 'DOC_GAPS.md', 'TEST_PLAN.md'];
+
+// `{TICKET-ID}-UC{N}` — the framework's UC-ID contract (steps/gate.md Bước 1: TICKET-ID is
+// the part before `-UC`). Anchored at both ends so `FEAT-01-2-UC1` matches but a folder
+// that merely contains the letters "uc" does not.
+const UC_DIR = /^(.+)-UC(\d+)$/i;
+
+// ── git tracked set (for `git mv`) ────────────────────────────────────────────
+let tracked = null;
+try {
+  const out = execSync('git ls-files', { cwd: ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  tracked = new Set(out.split('\n').filter(Boolean).map(p => p.replace(/\\/g, '/')));
+} catch { tracked = null; }
+
+const rel = abs => path.relative(ROOT, abs).replace(/\\/g, '/');
+const isTracked = abs => !!(tracked && tracked.has(rel(abs)));
+const isDir = p => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+
+function walk(dir) {
+  let out = [];
+  if (!isDir(dir)) return out;
+  for (const n of fs.readdirSync(dir)) {
+    const p = path.join(dir, n);
+    out = out.concat(isDir(p) ? walk(p) : [p]);
+  }
+  return out;
+}
+
+// ── plan ──────────────────────────────────────────────────────────────────────
+const moves = [];       // { from, to, kind }
+const noPlatform = [];  // { ucDir, files }
+const occupied = [];    // { from, to }
+const regen = new Map();// "TICKET|platform" → { ticket, platform, ucs:Set }
+
+if (!isDir(qcAbs)) {
+  console.log(`\n${QC}/ does not exist under ${ROOT} — nothing to migrate.\n`);
+  process.exit(0);
+}
+
+const ucDirs = fs.readdirSync(qcAbs)
+  .filter(n => n !== ARCHIVE)
+  .map(n => ({ name: n, abs: path.join(qcAbs, n) }))
+  .filter(d => isDir(d.abs) && UC_DIR.test(d.name));
+
+function plan(from, to, kind) {
+  // Never overwrite, and never let two sources land on one target.
+  if (fs.existsSync(to) || moves.some(m => m.to === to)) { occupied.push({ from, to }); return; }
+  moves.push({ from, to, kind });
+}
+
+for (const d of ucDirs) {
+  const m = UC_DIR.exec(d.name);
+  const ticket = m[1];
+  const ucNum = m[2];
+  const ucId = d.name;
+
+  // Files sitting directly under {qc}/{UC-ID}/ mean the platform level is absent. A QC
+  // artifact carries no @trace.platform, so there is nothing to infer it from — leave them.
+  const loose = fs.readdirSync(d.abs).filter(x => !isDir(path.join(d.abs, x)));
+  if (loose.length) noPlatform.push({ ucDir: ucId, files: loose });
+
+  for (const platform of fs.readdirSync(d.abs).filter(x => isDir(path.join(d.abs, x)))) {
+    const src = path.join(d.abs, platform);
+
+    const key = `${ticket}|${platform}`;
+    if (!regen.has(key)) regen.set(key, { ticket, platform, ucs: new Set() });
+    regen.get(key).ucs.add(`UC${ucNum}`);
+
+    for (const abs of walk(src)) {
+      const within = path.relative(src, abs).replace(/\\/g, '/');
+      const base = path.basename(abs);
+
+      if (within.startsWith('test-cases/')) {
+        // Survives the merge — the filename carries <FEATURE>, and the Trace SC column
+        // is what says which UC a TC belongs to.
+        plan(abs, path.join(qcAbs, ticket, platform, within), 'test-case');
+      } else {
+        // Archive, renaming DOC_GAPS.md → DOC_GAP.md so the archive uses one name.
+        const outName = base === 'DOC_GAPS.md' ? 'DOC_GAP.md' : base;
+        const outRel = path.join(path.dirname(within), outName);
+        plan(abs, path.join(qcAbs, ARCHIVE, ucId, platform, outRel),
+          TOP_DOCS.includes(base) ? 'archive' : 'archive-other');
+      }
+    }
+  }
+}
+
+// ── second pass — DOC_GAPS.md → DOC_GAP.md for folders ALREADY in the new layout ──
+for (const abs of walk(qcAbs)) {
+  if (path.basename(abs) !== 'DOC_GAPS.md') continue;
+  if (rel(abs).includes(`/${ARCHIVE}/`)) continue;
+  if (moves.some(mv => mv.from === abs)) continue;   // already handled above
+  plan(abs, path.join(path.dirname(abs), 'DOC_GAP.md'), 'rename');
+}
+
+// ── report ────────────────────────────────────────────────────────────────────
+const pad = (s, n) => s + ' '.repeat(Math.max(0, n - s.length));
+console.log('');
+console.log('╔════════════════════════════════════════════════╗');
+console.log(`║  migrate-qc-docs  —  ${pad(APPLY ? 'APPLY' : 'DRY RUN', 25)}║`);
+console.log('╚════════════════════════════════════════════════╝');
+console.log(`Root  : ${ROOT}`);
+console.log(`QC    : ${QC}/   Git: ${tracked ? 'yes (git mv)' : 'no (fs move)'}`);
+console.log('');
+
+if (!moves.length && !noPlatform.length && !occupied.length) {
+  console.log('Nothing to migrate — no per-UC folder found, and no DOC_GAPS.md to rename.');
+  console.log(`(Scanned ${QC}/ for folders matching {TICKET-ID}-UC{N}.)`);
+  console.log('');
+  process.exit(0);
+}
+
+const byKind = k => moves.filter(m => m.kind === k);
+const show = (title, list) => {
+  if (!list.length) return;
+  console.log(`${title}  (${list.length})`);
+  for (const m of list) console.log(`  ${rel(m.from)}\n    -> ${rel(m.to)}`);
+  console.log('');
+};
+
+show('📦 MOVE — test cases (survive the merge)', byKind('test-case'));
+show('🗄  ARCHIVE — the 3 PRD-level docs (regenerate instead of merging)', byKind('archive'));
+show('🗄  ARCHIVE — other files found at that level', byKind('archive-other'));
+show('✏️  RENAME — DOC_GAPS.md -> DOC_GAP.md (B9, already-new layout)', byKind('rename'));
+
+if (noPlatform.length) {
+  console.log(`⚠️  NO PLATFORM — left in place (${noPlatform.length})`);
+  console.log('    Files sit directly under the UC folder with no web/app/system level.');
+  console.log('    A QC artifact carries no @trace.platform, so the platform cannot be');
+  console.log('    inferred — move these by hand into the right platform folder.');
+  for (const x of noPlatform) console.log(`  ${QC}/${x.ucDir}/  ->  ${x.files.join(', ')}`);
+  console.log('');
+}
+
+if (occupied.length) {
+  console.log(`❌ OCCUPIED — NOT moved, target already exists (${occupied.length})`);
+  console.log('    Moving would overwrite. Resolve by hand, then re-run.');
+  for (const x of occupied) console.log(`  ${rel(x.from)}\n    x ${rel(x.to)}`);
+  console.log('');
+}
+
+if (regen.size) {
+  console.log('🔄 NEEDS REGENERATE — run these after the move:');
+  for (const r of regen.values()) {
+    console.log(`  /qc-analyze ${r.ticket} ${r.platform}      <- was ${[...r.ucs].sort().join(' + ')}`);
+    console.log(`  /qc-plan    ${r.ticket} ${r.platform}`);
+  }
+  console.log('');
+  console.log('    The archived per-UC docs are the way back, and the only way to check');
+  console.log('    whether the PRD-level run caught cross-UC contradictions the old ones');
+  console.log('    could not see. Compare, then delete the archive when you are satisfied.');
+  console.log('');
+}
+
+if (!APPLY) {
+  console.log('DRY RUN — nothing changed. Re-run with --apply to execute.');
+  console.log('');
+  process.exit(0);
+}
+
+// ── execute ───────────────────────────────────────────────────────────────────
+function mv(from, to) {
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  if (isTracked(from)) execSync(`git mv -k "${rel(from)}" "${rel(to)}"`, { cwd: ROOT, stdio: ['ignore', 'ignore', 'pipe'] });
+  else fs.renameSync(from, to);
+}
+
+let moved = 0, failed = 0;
+for (const m of moves) {
+  try { mv(m.from, m.to); moved++; }
+  catch (err) {
+    console.log(`  ❌ ${rel(m.from)} — ${err.message.split('\n')[0]}`);
+    failed++;
+  }
+}
+
+// Prune folders the move emptied — deepest first, and only if genuinely empty.
+let pruned = 0;
+const dirsDeepFirst = [];
+(function collect(dir) {
+  if (!isDir(dir)) return;
+  for (const n of fs.readdirSync(dir)) collect(path.join(dir, n));
+  dirsDeepFirst.push(dir);
+})(qcAbs);
+for (const d of dirsDeepFirst) {
+  if (d === qcAbs) continue;
+  try { if (fs.readdirSync(d).length === 0) { fs.rmdirSync(d); pruned++; } } catch { /* keep */ }
+}
+
+console.log(`✅ Moved ${moved} file(s)${failed ? `, ${failed} FAILED` : ''}.`);
+console.log(`✅ Pruned ${pruned} empty folder(s).`);
+console.log('');
+console.log('Next:');
+console.log('  1. git status  — review the moves (nothing was deleted)');
+console.log('  2. Run the /qc-analyze + /qc-plan commands listed above');
+console.log(`  3. Compare against ${QC}/${ARCHIVE}/, then remove the archive when satisfied`);
+console.log('');