@educa-corp/sdd-framework 0.4.0 → 0.5.0

package/modules/nuxt/stack-profile.yaml

@@ -53,6 +53,6 @@ testing:
 
 trace_tags:
   implements: "// @trace.implements={UC-ID}-SC{N}"
-  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
   verifies: "// @trace.verifies={UC-ID}"
   test_type: "// @trace.test_type=unit|integration"

package/modules/phaser-game/stack-profile.yaml

@@ -85,6 +85,6 @@ testing:
 
 trace_tags:
   implements: "// @trace.implements={UC-ID}-SC{N}"
-  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
   verifies: "// @trace.verifies={UC-ID}"
   test_type: "// @trace.test_type=unit|integration"

package/modules/php-laravel/stack-profile.yaml

@@ -51,6 +51,6 @@ testing:
 
 trace_tags:
   implements: "// @trace.implements={UC-ID}-SC{N}"
-  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
   verifies: "// @trace.verifies={UC-ID}"
   test_type: "// @trace.test_type=unit|feature"

package/modules/qc-playwright/stack-profile.yaml

@@ -59,7 +59,7 @@ testing:
 trace_tags:
   # QC tests map back to the framework's scenarios — drives qc_status in the trace TSV.
   verifies: "# @trace.verifies={UC-ID}-SC{N}"
-  source: "# @trace.source=<official .feature path>"
+  source: "# @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
   test_type: "# @trace.test_type=functional|integration|e2e|non-functional"
 
 # qc_status: /qc-run-test writes pass|fail|skip|not_run + qc_run_at into {trace_dir}/{UC-ID}.tsv

package/modules/react/stack-profile.yaml

@@ -58,6 +58,6 @@ testing:
 
 trace_tags:
   implements: "// @trace.implements={UC-ID}-SC{N}"
-  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
   verifies: "// @trace.verifies={UC-ID}"
   test_type: "// @trace.test_type=unit|integration"

package/modules/react-native/stack-profile.yaml

@@ -53,4 +53,4 @@ testing:
 
 trace_tags:
   implements: "// @trace.implements={UC-ID}-SC{N}"
-  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"

package/modules/vue/stack-profile.yaml

@@ -60,6 +60,6 @@ testing:
 
 trace_tags:
   implements: "// @trace.implements={UC-ID}-SC{N}"
-  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
   verifies: "// @trace.verifies={UC-ID}"
   test_type: "// @trace.test_type=unit|integration"

package/package.json

@@ -1,17 +1,18 @@
 {
   "name": "@educa-corp/sdd-framework",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Spec Driven Development workflow framework for Claude Code",
   "bin": {
     "sdd-framework": "./bin/index.js"
   },
   "scripts": {
-    "build": "node bin/build.js",
-    "prepublishOnly": "node bin/build.js",
+    "build": "node bin/build.js && node bin/self-check.js",
+    "prepublishOnly": "node bin/build.js && node bin/self-check.js",
     "pub": "npm publish --access=public",
     "dev": "node bin/build.js && node bin/index.js --init",
     "prepack": "node -e \"const fs=require('fs'); ['README.md','PUBLISHING.md','SETUP_GUIDE.md'].forEach(f=>{ if(fs.existsSync(f)) fs.renameSync(f,'__'+f); });\"",
-    "postpack": "node -e \"const fs=require('fs'); ['README.md','PUBLISHING.md','SETUP_GUIDE.md'].forEach(f=>{ if(fs.existsSync('__'+f)) fs.renameSync('__'+f,f); });\""
+    "postpack": "node -e \"const fs=require('fs'); ['README.md','PUBLISHING.md','SETUP_GUIDE.md'].forEach(f=>{ if(fs.existsSync('__'+f)) fs.renameSync('__'+f,f); });\"",
+    "self-check": "node bin/self-check.js"
   },
   "files": [
     "bin/",

package/rules/workflow.md

@@ -18,6 +18,35 @@
 - Do NOT create files outside the directories specified in `project-context.yaml → paths`.
 - If new scope is discovered mid-command, STOP and ask: "I found additional scope [{description}]. Should I include it? (Y/N)"
 
+## Trace Contract
+
+- Contract trace (field `@trace.*`, cột `.tsv`, path pattern, giá trị enum) có **một
+  nguồn-sự-thật máy đọc**: `bin/trace-schema.json`. Bản cho người đọc:
+  `docs/04-reference/trace-schema.md` — giữ hai file đồng bộ.
+- Đổi contract (thêm/bỏ/đổi nghĩa một field, path, hay giá trị enum) → **sửa
+  `bin/trace-schema.json` TRƯỚC**, rồi mới sửa lệnh. `npm run build` chạy
+  `bin/self-check.js` và **fail** nếu lệnh lệch schema.
+- Field có consumer mà **không có producer** là lỗi chặn build — đó chính là hình dạng
+  của G1 (`@trace.sc_version`: 3 consumer, 0 producer, DRIFT chết mà không ai báo).
+- **Làm mất hiệu lực ≠ ghi đè.** Cột trace có chủ sở hữu rõ ràng — `dev_selftest`/`dev_selftest_at`
+  thuộc `/dev-run-test` · `qc_status`/`qc_run_at` thuộc `/qc-run-test` · `test_count`/`test_classes`
+  thuộc `/dev-gen-test` — và **chỉ chủ được ghi giá trị KHẲNG ĐỊNH** (`pass`/`fail`/số lượng).
+  Nhưng lệnh nào làm giá trị đó **HẾT ĐÚNG** (spec đổi, code đổi) thì **BẮT BUỘC** hạ nó về giá
+  trị "chưa biết" (`not_run` / `—`). Giữ một `pass` đã hết hiệu lực là **báo cáo sai**, không phải
+  tôn trọng quyền sở hữu.
+  *Tiền lệ đúng có sẵn: `/fix-bug` hạ `dev_selftest → not_run` với lý do "code vừa đổi nên tín
+  hiệu self-test cũ hết hiệu lực". Cùng lý do đó áp cho MỌI lệnh làm đổi spec hoặc code.*
+  **Ngoại lệ có chủ ý:** `qc_owner`/`qc_blocked_by` (con trỏ tới bug — spec đổi không làm bug biến
+  mất) và `test_count`/`test_classes` (test vẫn tồn tại trên đĩa; số lượng không sai, chỉ nội dung
+  cũ → **cảnh báo**, không hạ số, để tỷ lệ coverage không nhảy loạn).
+- **Mỗi audit flag phải quan sát được ở CẢ BA tầng.** Mọi giá trị trong
+  `vocabularies.audit_flags` bắt buộc có đủ: **(1)** một counter `{flag_lowercase}_count`
+  trong Step 7 + `summary` của `trace-report.json` · **(2)** một mảng trong `issues` ·
+  **(3)** một khối trong report terminal. Thiếu tầng nào = cờ vô hình ở tầng đó.
+  `bin/self-check.js` R7 ép tầng (1) — **không có ngoại lệ**. Đây là hình dạng của G33:
+  7/10 cờ có counter, 3 cái không, nên dashboard (chỉ đọc `summary`) không tổng hợp
+  được — và bất đối xứng 7/10 là bẫy cho người viết dashboard: đọc `summary` rồi tưởng đủ.
+
 ## Code Generation
 
 - Never generate code for files not backed by a `.feature` spec (unless `/fix-bug` or `/debug`).

package/scripts/migrate-bdd-platform.js

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+/**
+ * migrate-bdd-platform — move flat BDD files into the per-platform layout.
+ *
+ *   specs/{domain}/{prd-slug}/bdd/{FILE}.feature
+ *     → specs/{domain}/{prd-slug}/bdd/{platform}/{FILE}.feature
+ *
+ * The flat layout was produced by the umbrella-mode branch of /generate-bdd before
+ * v0.4.1 (see GAPS.md G3). It breaks five consumers — most importantly `web` and
+ * `system` features of the same UC collide on one filename and overwrite each other.
+ *
+ * The {platform} for each file is resolved in this order:
+ *   1. `# @trace.platform:` in the file header               (authoritative)
+ *   2. `# @trace.module:`  mapped through MODULE_PLATFORM    (umbrella files carry it)
+ *   3. Gherkin step vocabulary  ("clicks"→web, "taps"→app, "calls the API"→system)
+ * Files that cannot be resolved are LEFT IN PLACE and listed — never moved to a guess.
+ *
+ * After moving, `@trace.platform` is INSERTED into the header if it was missing
+ * (it is mandatory in every mode), and internal path references to the moved files
+ * are rewritten across specs/ and .trace/.
+ *
+ * Also reports (does NOT fix) two conditions that need a human:
+ *   - OCCUPIED  : the target path already holds a file (mixed/partial layout) — moving
+ *                 would overwrite it, so the flat file is left in place instead
+ *   - LOST SPEC : a UC has N trace books ({UC}-{platform}.tsv) but fewer flat files
+ *                 than N → a previous run likely overwrote a platform's .feature
+ *
+ * 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-bdd-platform.js                 # dry-run, prints plan
+ *   node scripts/migrate-bdd-platform.js --apply         # execute
+ *   node scripts/migrate-bdd-platform.js --specs specs --trace .trace --root .
+ */
+
+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 SPECS = flag('--specs', 'specs');
+const TRACE = flag('--trace', '.trace');
+
+const specsAbs = path.join(ROOT, SPECS);
+const traceAbs = path.join(ROOT, TRACE);
+
+const PLATFORMS = ['web', 'app', 'system'];
+
+// module → platform (same table as /generate-bdd §Service Detection)
+const MODULE_PLATFORM = {
+  react: 'web', nextjs: 'web', vue: 'web', nuxt: 'web', angular: 'web',
+  flutter: 'app', 'react-native': 'app', 'ios-swiftui': 'app', 'android-compose': 'app',
+  'java-spring': 'system', golang: 'system', dotnet: 'system', 'php-laravel': 'system',
+  'context-engineering': 'system', 'phaser-game': 'web',
+};
+
+// ── 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)));
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+function walk(dir) {
+  const out = [];
+  if (!fs.existsSync(dir)) return out;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...walk(p));
+    else out.push(p);
+  }
+  return out;
+}
+const read = file => { try { return fs.readFileSync(file, 'utf8'); } catch { return ''; } };
+
+const rePlatform = /^#\s*@trace\.platform\s*:\s*([A-Za-z-]+)\s*$/m;
+const reModule   = /^#\s*@trace\.module\s*:\s*([A-Za-z0-9-]+)\s*$/m;
+const reUcId     = /^#\s*@trace\.id\s*:\s*([A-Za-z0-9_-]+)\s*$/m;
+
+/** Resolve platform for one flat .feature file. Returns {platform, via} or null. */
+function resolvePlatform(body) {
+  const tagged = (body.match(rePlatform) || [])[1];
+  if (tagged && PLATFORMS.includes(tagged)) return { platform: tagged, via: '@trace.platform' };
+
+  const mod = (body.match(reModule) || [])[1];
+  if (mod && MODULE_PLATFORM[mod]) return { platform: MODULE_PLATFORM[mod], via: `@trace.module=${mod}` };
+
+  // last resort: step vocabulary (see the per-platform table in /generate-bdd)
+  const steps = body.toLowerCase();
+  const web = /\b(clicks|types into|the page shows)\b/.test(steps);
+  const app = /\b(taps|the screen shows)\b/.test(steps);
+  const sys = /\b(calls the api|submits a request|the system returns|receives response)\b/.test(steps);
+  const hits = [web && 'web', app && 'app', sys && 'system'].filter(Boolean);
+  if (hits.length === 1) return { platform: hits[0], via: 'step vocabulary' };
+
+  return null;
+}
+
+/** Trace books present for a UC, e.g. {UC}-web.tsv → ['web'] */
+function tracePlatformsFor(ucId) {
+  const found = new Set();
+  for (const f of walk(traceAbs).filter(f => f.endsWith('.tsv'))) {
+    const m = path.basename(f).match(/^(.+)-(web|app|system)\.tsv$/);
+    if (m && m[1] === ucId) found.add(m[2]);
+  }
+  return [...found];
+}
+
+// ── plan ──────────────────────────────────────────────────────────────────────
+const moves      = [];  // { from, to, platform, via, needsTag }
+const unresolved = [];  // { file, reason }
+const occupied   = [];  // { from, to }  — target already exists (mixed layout)
+const lostSpecs  = [];  // { ucId, flat, traceBooks[] }
+
+const bddDirs = new Set();
+for (const f of walk(specsAbs).filter(f => f.endsWith('.feature'))) {
+  const parts = rel(f).split('/');
+  const i = parts.lastIndexOf('bdd');
+  if (i === -1) continue;
+  // flat == the file sits DIRECTLY under bdd/ (no platform subfolder)
+  if (parts.length !== i + 2) continue;
+  bddDirs.add(parts.slice(0, i + 1).join('/'));
+
+  const body = read(f);
+  const res  = resolvePlatform(body);
+  if (!res) {
+    unresolved.push({
+      file: rel(f),
+      reason: 'no @trace.platform, no recognizable @trace.module, and step vocabulary is ambiguous ' +
+              '→ add `# @trace.platform: web|app|system` to the header, then re-run',
+    });
+    continue;
+  }
+  const dir    = path.dirname(f);
+  const target = path.join(dir, res.platform, path.basename(f));
+
+  // Mixed layout: some platforms already migrated, this one left flat. Moving onto an
+  // existing file would silently overwrite a real spec — leave it and let a human look.
+  if (fs.existsSync(target)) { occupied.push({ from: f, to: target }); continue; }
+
+  moves.push({
+    from: f,
+    to: target,
+    platform: res.platform,
+    via: res.via,
+    needsTag: res.via !== '@trace.platform',
+  });
+}
+
+// lost-spec detection: UC has more trace books than flat files
+const flatByUc = new Map();
+for (const m of moves) {
+  const uc = (read(m.from).match(reUcId) || [])[1] || path.basename(m.from).replace(/\.feature$/, '');
+  flatByUc.set(uc, [...(flatByUc.get(uc) || []), m]);
+}
+for (const [ucId, list] of flatByUc) {
+  const books = tracePlatformsFor(ucId);
+  if (books.length > list.length) {
+    lostSpecs.push({ ucId, flat: list.map(m => m.platform), traceBooks: books });
+  }
+}
+
+const refMap = new Map();
+for (const m of moves) refMap.set(rel(m.from), rel(m.to));
+
+// ── report ────────────────────────────────────────────────────────────────────
+console.log('');
+console.log('╔════════════════════════════════════════════════╗');
+console.log(`║  migrate-bdd-platform  —  ${APPLY ? 'APPLY' : 'DRY RUN'}${' '.repeat(APPLY ? 16 : 14)}║`);
+console.log('╚════════════════════════════════════════════════╝');
+console.log(`Root  : ${ROOT}`);
+console.log(`Specs : ${SPECS}/   Trace: ${TRACE}/   Git: ${tracked ? 'yes (git mv)' : 'no (fs move)'}`);
+console.log('');
+
+if (!moves.length && !unresolved.length && !occupied.length) {
+  console.log(`Nothing to migrate — no .feature file sits directly under a bdd/ folder.`);
+  console.log(`(Scanned ${bddDirs.size} bdd/ folder(s) under ${SPECS}/.)`);
+  process.exit(0);
+}
+
+const byPlatform = moves.reduce((a, m) => ((a[m.platform] = (a[m.platform] || 0) + 1), a), {});
+console.log(`Planned moves: ${moves.length}  (${Object.entries(byPlatform).map(([k, v]) => `${k}:${v}`).join('  ')})`);
+console.log('');
+for (const m of moves) {
+  console.log(`  ${rel(m.from)}`);
+  console.log(`    → ${rel(m.to)}   [platform via ${m.via}${m.needsTag ? ' · will INSERT @trace.platform' : ''}]`);
+}
+
+if (occupied.length) {
+  console.log('');
+  console.log(`🔴 OCCUPIED — ${occupied.length} target path already holds a file (mixed/partial layout).`);
+  console.log(`   NOT moved — that would overwrite a real spec.`);
+  for (const o of occupied) console.log(`  ${rel(o.from)}\n      target exists: ${rel(o.to)}`);
+  console.log(`  → Diff the two files. Keep the right one, delete the other, then re-run.`);
+}
+
+if (lostSpecs.length) {
+  console.log('');
+  console.log(`🔴 LOST SPEC — a UC has more trace books than flat .feature files.`);
+  console.log(`   A previous flat-layout run very likely OVERWROTE one platform's .feature.`);
+  console.log(`   Migration cannot recover it — restore from git history, or re-run /generate-bdd`);
+  console.log(`   for the missing platform AFTER this migration.`);
+  for (const l of lostSpecs) {
+    console.log(`  ${l.ucId}: flat file(s) resolve to [${l.flat.join(', ')}] but trace books exist for [${l.traceBooks.join(', ')}]`);
+  }
+}
+
+if (unresolved.length) {
+  console.log('');
+  console.log(`⚠️  Unresolved (LEFT IN PLACE):`);
+  for (const u of unresolved) console.log(`  ${u.file}\n      ${u.reason}`);
+}
+
+console.log('');
+if (!APPLY) {
+  console.log('DRY RUN — nothing changed. Re-run with --apply to execute.');
+  process.exit(0);
+}
+
+// ── apply ─────────────────────────────────────────────────────────────────────
+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);
+}
+
+/** Insert `# @trace.platform:` right after `# @trace.domain:` (or after @trace.id). */
+function insertPlatformTag(absFile, platform) {
+  const txt = read(absFile);
+  if (rePlatform.test(txt)) return false;
+  const lines = txt.split('\n');
+  let at = lines.findIndex(l => /^#\s*@trace\.domain\s*:/.test(l));
+  if (at === -1) at = lines.findIndex(l => /^#\s*@trace\.id\s*:/.test(l));
+  if (at === -1) return false;
+  lines.splice(at + 1, 0, `# @trace.platform: ${platform}`);
+  fs.writeFileSync(absFile, lines.join('\n'), 'utf8');
+  return true;
+}
+
+function rewriteRefs(absFile) {
+  if (!/\.(md|feature|tsv|ya?ml|json)$/.test(absFile)) return 0;
+  let txt = read(absFile);
+  if (!txt) return 0;
+  let n = 0, out = txt;
+  for (const [oldRef, newRef] of refMap) {
+    if (out.includes(oldRef)) { out = out.split(oldRef).join(newRef); n++; }
+  }
+  if (n) fs.writeFileSync(absFile, out, 'utf8');
+  return n;
+}
+
+let moved = 0, tagged = 0, skipped = 0;
+for (const m of moves) {
+  try {
+    mv(m.from, m.to);
+    moved++;
+    if (m.needsTag && insertPlatformTag(m.to, m.platform)) tagged++;
+  } catch (err) {
+    console.log(`  ❌ ${rel(m.from)} — ${err.message.split('\n')[0]}`);
+    skipped++;
+  }
+}
+
+let rewritten = 0;
+for (const f of [...walk(specsAbs), ...walk(traceAbs)]) rewritten += rewriteRefs(f) ? 1 : 0;
+
+console.log(`✅ Moved ${moved} file(s)${skipped ? `, skipped ${skipped}` : ''}.`);
+console.log(`✅ Inserted @trace.platform into ${tagged} header(s).`);
+console.log(`✅ Rewrote path references in ${rewritten} file(s).`);
+console.log('');
+console.log('Next:');
+console.log('  1. git diff  — review the moves + inserted headers');
+console.log('  2. /validate-traces   — reconcile trace books against the new layout');
+console.log('  3. Commit (spec repo, if specs live in a submodule)');
+console.log('');

package/steps/gate.md

@@ -29,23 +29,23 @@ Hiển thị và chờ phản hồi:
 ```
 ⚙️  MODEL CHECK
 ──────────────────────────────────────────────────────────────────
-  Recommended  : claude-opus-4 (hoặc model Opus mới nhất)
+  Recommended  : model Opus mới nhất
   Why needed   : Phân tích spec, review kiến trúc, sinh code đòi hỏi
-                 suy luận sâu. Model nhỏ hơn dễ bỏ sót edge case.
+                 suy luận sâu. Model nhỏ hơn (Haiku/Sonnet) dễ bỏ sót edge case.
 
   Cách đổi trong Claude Code:
-    • Settings → Model → chọn "claude-opus"
-    • hoặc: /model → chọn claude-opus
+    • /model → chọn model Opus
+    • hoặc: Settings → Model
 
-  Đang chạy claude-opus?
-    Y — đúng, đang dùng claude-opus → tiếp tục
+  Đang chạy một model Opus?
+    Y — đúng → tiếp tục
     S — bỏ qua kiểm tra (tôi chấp nhận rủi ro chất lượng thấp hơn với model hiện tại)
 ──────────────────────────────────────────────────────────────────
 ```
 
 - "Y" → tiếp tục sang Bước 1.
 - "S" → tiếp tục sang Bước 1 (người dùng chấp nhận rủi ro, thêm ⚠️ vào report cuối).
-- "N" hoặc bất kỳ giá trị nào khác → **DỪNG.** Xuất: "Vui lòng chuyển sang claude-opus rồi chạy lại lệnh này."
+- "N" hoặc bất kỳ giá trị nào khác → **DỪNG.** Xuất: "Vui lòng chuyển sang một model Opus (`/model`) rồi chạy lại lệnh này."
 
 ## Bước 1 — Xác định Target File
 
@@ -54,7 +54,12 @@ Hiển thị và chờ phản hồi:
 2. Nếu `$ARGUMENTS` là một **UC-ID / ticket ID / tên rút gọn** (không có path) → phân giải thành file bằng cách glob theo bố cục feature-package. `{prd-slug}` lúc này **chưa biết**, nên dùng wildcard `*` cho segment đó, và `**` đệ quy dưới `bdd/` để phủ hết các thư mục con theo platform (`bdd/web/`, `bdd/app/`, `bdd/system/`):
    - **Lệnh BDD** (target là `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — hoặc `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` nếu domain cũng chưa biết. Nếu lệnh ngụ ý một platform/scope cụ thể (vd: system tech-doc cần BDD `system/`), ưu tiên kết quả trong thư mục con platform đó.
    - **Lệnh PRD** (target là file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder, cạnh `bdd/`): `{specs_dir}/{domain}/*/{TICKET-ID}*.md` nếu biết TICKET-ID; nếu không, `{specs_dir}/{domain}/*/*.md` (khớp feature folder có id tương ứng), hoặc `{specs_dir}/*/*/*.md` nếu domain cũng chưa biết. *(Glob `*/*.md` ở cấp gốc folder chỉ khớp PRD — tech-docs/design-spec `.md` nằm sâu hơn trong thư mục con.)*
-   - **Lệnh tech-docs**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
+   - **Lệnh tech-docs** — target là tech-doc **gộp cấp PRD** `{TICKET-ID}-tech-design.md` (MỘT doc phủ nhiều UC; danh sách UC nằm ở `@trace.ucs`). Vì tên file mang `{TICKET-ID}` chứ **không** mang `{UC-ID}`, phải tách trước khi glob:
+     - `$ARGUMENTS` là **UC-ID** (`{TICKET-ID}-UC{N}`) → lấy `{TICKET-ID}` = phần **trước** `-UC`, rồi glob `{specs_dir}/{domain}/*/tech-docs/{TICKET-ID}-tech-design.md`.
+     - `$ARGUMENTS` là **TICKET-ID** → glob trực tiếp như trên.
+     - Chưa biết domain → `{specs_dir}/*/*/tech-docs/{TICKET-ID}-tech-design.md`.
+     - Vẫn không khớp → glob rộng `{specs_dir}/*/*/tech-docs/*tech-design*.md` rồi liệt kê để người dùng chọn.
+     *(Đừng glob `{UC-ID}*-tech-design*.md` — nó nở thành `FT-001-UC1*-tech-design*.md` và **không bao giờ** khớp `FT-001-tech-design.md`.)*
    - **Lệnh design-spec**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
 
    Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi.

package/steps/report-footer.md

@@ -34,7 +34,7 @@ Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **pha
 | Phase | Commands |
 |-------|----------|
 | Discovery | `/define-product` |
-| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| PRD | `/generate-prd` · `/extend-prd` · `/refine-prd` · `/review-context` (PRD) |
 | Design Spec | `/generate-design-spec` |
 | BDD | `/generate-bdd` · `/review-context` (BDD) |
 | Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
@@ -59,6 +59,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /setup-ai-first         | `/define-product` để bắt đầu feature đầu tiên |
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
+| /extend-prd             | `/refine-prd {prd-file}` (soi phần vừa thêm) rồi `/review-context {prd-file}` → PO duyệt → `/generate-bdd` **chỉ cho UC MỚI**; UC cũ dùng `/validate-traces --realign-prd-version {UC-ID}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
 | /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
@@ -71,6 +72,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /qc-run-test            | `/qc-report {UC-ID}` rồi `/qc-review {UC-ID}` (review script) |
 | /qc-review (script)     | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED |
 | /qc-report              | `/validate-traces {UC-ID}` để làm mới Living Docs (qc_status) |
+| /map-testids            | `/qc-design-test {UC-ID}` (QC dựng Page Object từ contract §4.5.6 vừa ghi) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` nếu APPROVED; sửa doc nếu NEEDS_FIX |
 | /generate-code          | Lần gen đầu → `/review-code {UC-ID}`; gen lại → `/dev-gen-test {UC-ID}` |
@@ -79,11 +81,11 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /dev-run-test (failing)    | `/fix-bug {ticket-id}` hoặc `/debug {error}`    |
 | /review-code            | `/dev-smoke-test {UC-ID}` hoặc tạo PR            |
 | /dev-smoke-test             | Tạo PR và link tới ticket                  |
-| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; tất cả OK → tạo PR |
-| /fix-bug                | Tạo PR và link tới ticket                  |
+| /validate-traces        | **Cờ 🔴 trước (chặn PR):** SEAM_UNWIRED → nối binding sang class thật, xoá/thay stub · STUB_UNRESOLVED → `/generate-code {owner_uc}` (lấp logic tại chỗ + xoá hàm song song) · ORPHANED/TRACE_ORPHAN → quyết định thủ công (xoá code+test, đưa scenario trở lại `.feature`, hoặc sửa `sc_id` của tag). **Rồi:** DRIFT/UNTRACKED → `/generate-code {UC-ID}` · BDD_DRIFT → `/generate-code {feature-file}` · tech-doc lỗi thời vs BDD → `/generate-tech-docs` → `/review-tech-docs` · PRD drift → `/generate-bdd {prd-file}` · GAP → `/dev-gen-test {UC-ID}`. **Chỉ tạo PR khi mọi cờ 🔴 = 0** |
+| /fix-bug                | `/dev-run-test {UC-ID}` (dev_selftest vừa reset về not_run) → tạo PR; nếu fix một `{BUG-ID}` → QC chạy `/qc-run-test {UC-ID}` để verify + đóng bug |
 | /debug                  | `/fix-bug {ticket-id}` nếu cần sửa          |
 | /report-bug             | Gửi cho dev (`/fix-bug {BUG-ID}`); nếu thiếu coverage → `/propose-scenario {UC-ID}` |
-| /propose-scenario       | Báo PO/Dev review proposal trong `feedback/bdd-proposals/` |
+| /propose-scenario       | **Case A** (thiếu scenario cho AC có sẵn) → báo PO/Dev review trong `feedback/bdd-proposals/`; `/generate-bdd` tự chèn khi `Status: accepted`. **Case B** (requirement mới) → `feedback/prd-change-requests/` — PO phải đưa vào PRD trước, KHÔNG tự vào BDD được; `/validate-traces` nhắc lại kèm số ngày chờ chừng nào `Status: Open` |
 | /learn                  | Tiếp tục làm việc — lesson áp dụng ở lệnh kế tiếp |
 | /sync                   | `/validate-traces` để xem độ phủ đầy đủ; xử lý mọi `📥 tester feedback` được nêu |
 | /update-framework       | Review `git diff .agent/`, commit; `/sync` để đồng bộ nội dung dự án |

package/steps/trace-mirror.md

@@ -1,7 +1,31 @@
-# Làm mới panel mirror của Living Docs *(local, chế độ umbrella)*
+# Làm mới panel mirror của Living Docs *(local)*
 
-*Bỏ qua hoàn toàn ở chế độ single-service (không có `services` và không có `setup.spec_source`) — ở đó
-`.trace/` của chính repo CHÍNH LÀ vị trí panel, nên không có gì để mirror.*
+> **Hai vị trí, HAI TÊN KHÁC NHAU — đọc trước khi sửa gì ở đây.**
+>
+> | Đường dẫn | Vai trò | Git |
+> |---|---|---|
+> | `{paths.trace_dir}` (`.trace/` hoặc `{spec_source}/.trace/`) | **AUTHORITATIVE** — TSV + `trace-history.jsonl`. Không regenerate được. | **PHẢI commit** |
+> | `./.trace-mirror/` ở gốc workspace hiện tại | **MIRROR** — bản sao tiện cho panel VS Code. Sinh lại được bất cứ lúc nào. | **Luôn gitignore** |
+>
+> Trước v0.4.3 cả hai đều tên `.trace`, nên một luật gitignore theo tên có thể **xoá sạch sổ gốc**
+> khi dev mở thẳng spec repo làm workspace (lúc đó hai path bằng nhau). Hai tên khác nhau làm
+> luật git đọc được bằng mắt và **không còn ca nhập nhằng nào**: `.trace-mirror/` không bao giờ
+> commit, `.trace/` không bao giờ gitignore.
+
+## Khi nào CÓ mirror
+
+Mirror chỉ tồn tại khi **`{paths.trace_dir}` nằm NGOÀI workspace hiện tại** — panel đọc từ workspace đang mở nên cần một bản sao ở đây.
+
+| Tình huống | `{paths.trace_dir}` | Có mirror? |
+|---|---|---|
+| Single-service | `./.trace` — **trong** workspace | ❌ Không. Panel đọc thẳng `.trace/trace-report.json`. Bỏ qua cả file này. |
+| Dev mở thẳng **spec repo** | `./.trace` — **trong** workspace | ❌ Không. Như trên. |
+| Umbrella + `spec_source`, dev đứng ở umbrella hoặc service submodule | `{spec_source}/.trace` — **ngoài** workspace | ✅ Có |
+| Umbrella legacy (không `spec_source`) | `.trace` theo từng service | ✅ Có |
+
+Quy tắc một dòng: **phân giải `panel_mirror = ./.trace-mirror` ở gốc workspace hiện tại; nếu `{paths.trace_dir}` đã nằm trong workspace này thì bỏ qua toàn bộ bước mirror.**
+
+---
 
 Sau khi cập nhật TSV authoritative tại `{paths.trace_dir}`:
 
@@ -9,11 +33,14 @@ Sau khi cập nhật TSV authoritative tại `{paths.trace_dir}`:
 `{paths.trace_dir}` phân giải về `{spec_source}/.trace` — vị trí authoritative duy nhất.
 Lệnh này chạy từ `service_root`, nên thao tác ghi là **liên-repo vào spec submodule**;
 commit/push spec submodule cho lần cập nhật trace (giống như `feedback/`).
-1. Phân giải `panel_mirror = ./.trace` tại **gốc workspace hiện tại**.
-2. Nếu `panel_mirror` phân giải ra path khác với `{paths.trace_dir}`, copy mỗi
+
+1. Phân giải `panel_mirror = ./.trace-mirror` tại **gốc workspace hiện tại**.
+2. Nếu `{paths.trace_dir}` **không** nằm trong workspace hiện tại, copy mỗi
    `{UC-ID}-{platform}.tsv` vừa cập nhật → `{panel_mirror}/{UC-ID}-{platform}.tsv` (tạo thư mục; ghi đè).
-   Không namespace theo service — chỉ có một bộ trace; service sở hữu được mang trong
-   `@trace.service` của từng row.
+   Không namespace theo service — chỉ có một bộ trace; service sở hữu được mang ở
+   **cột `service` (cột 23)** của chính từng row, do `/generate-bdd` ghi từ `@trace.service`.
+3. **KHÔNG copy `trace-history.jsonl`.** Nó là dữ liệu tích luỹ, không phải thứ sinh lại được —
+   nhân bản nó ra một thư mục gitignore là tạo hai lịch sử lệch nhau rồi mất bản thật.
 
 **Legacy (không có `spec_source` — trace theo service):**
 Copy mỗi `{UC-ID}-{platform}.tsv` vừa cập nhật → `{panel_mirror}/{service-name}/{UC-ID}-{platform}.tsv`

package/templates/README.md

@@ -0,0 +1,47 @@
+# templates/ — build-time skeletons
+
+> **Nếu bạn đang mở thư mục này ở `.agent/templates/` trong một project: sửa file ở đây KHÔNG có tác dụng.**
+
+## Vì sao
+
+Các skeleton trong thư mục này được `{{include}}` **nướng cứng vào file lệnh lúc `npm run build`**:
+
+```
+templates/feature.template
+      ↓ {{include:templates/feature.template}}  ← bin/build.js, thay thế văn bản lúc build
+commands/generate-bdd.md
+      ↓ copy vào core/ → mirror sang .agent/
+.agent/commands/generate-bdd.md        ← LỆNH THẬT SỰ CHẠY (đã chứa sẵn skeleton)
+.agent/templates/feature.template      ← bản tham khảo, KHÔNG lệnh nào đọc
+```
+
+Không lệnh nào đọc một path template lúc chạy. `paths.feature_template` / `paths.prd_template` từng tồn tại trong `project-context.yaml` nhưng chưa bao giờ có tác dụng — đã được gỡ bỏ (xem `GAPS.md` G9).
+
+**Thêm nữa:** `.agent/` là vùng bị ghi đè. `/update-framework` chạy `npx … --init`, và `--init` copy `core/` → `.agent/` **vô điều kiện** (`bin/index.js` → `copyDirRecursive`, không có existence check, không backup). File duy nhất được giữ lại là `.agent/project-context.yaml`. Nên mọi chỉnh sửa ở `.agent/templates/` sẽ **biến mất im lặng** ở lần nâng cấp kế tiếp.
+
+## Muốn đổi cấu trúc artifact sinh ra thì làm gì
+
+Sửa file trong **repo framework** rồi build lại:
+
+```bash
+# trong repo sdd-framework
+vim templates/feature.template          # hoặc prd.template.md, tech-design.template.md, …
+npm run build                           # inline lại vào commands/*.md + core/ + .agent/
+```
+
+Rồi phát hành version mới; project chạy `/update-framework` để nhận.
+
+## File nào ở đây đi vào đâu
+
+| Template | Được include vào | Trở thành |
+|---|---|---|
+| `feature.template` | `commands/generate-bdd.tmpl` | mỗi file `.feature` |
+| `prd.template.md` | `commands/generate-prd.tmpl` | mỗi PRD |
+| `tech-design.template.md` | `commands/generate-tech-docs.tmpl` | tech-doc gộp / PRD |
+| `design-spec.template.md` | `commands/generate-design-spec.tmpl` | design-spec / platform |
+| `architecture.template.md` | `commands/generate-architecture.tmpl` | tài liệu kiến trúc |
+| `product-definition.template.md` | `commands/define-product.tmpl` | product definition |
+| `platform-guide.template.md` | (tham khảo) | — |
+| `project-context.yaml` | **không** include — được copy thẳng làm file config khởi tạo | `.agent/project-context.yaml` |
+
+> Lưu ý `project-context.yaml` là ngoại lệ duy nhất: nó **được** copy ra làm file thật của project, và **được bảo vệ** khỏi ghi đè khi nâng cấp (chỉ tạo nếu chưa tồn tại).