@educa-corp/sdd-framework 0.1.0

package/scripts/migrate-specs.js

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+
+/**
+ * migrate-specs.js — migrate a consumer project's specs from the LEGACY
+ * artifact-type-first layout to the FEATURE-PACKAGE layout.
+ *
+ *   OLD                                   NEW
+ *   specs/prd/{domain}/{slug}.md          specs/{domain}/{slug}/{TICKET-ID}-{slug}.md
+ *   specs/bdd/{domain}/{rest}             specs/{domain}/{prd-slug}/bdd/{rest}
+ *   specs/tech-docs/{domain}/{file}       specs/{domain}/{prd-slug}/tech-docs/{file}
+ *   specs/design-spec/{domain}/{file}     specs/{domain}/{prd-slug}/design-spec/{file}
+ *   .trace/{UC-ID}.tsv                    .trace/{domain}/{prd-slug}/{UC-ID}.tsv
+ *
+ * The {prd-slug} for a BDD / tech-doc / design-spec / trace file is resolved by
+ * reading its `@trace.source` header (the PRD it derives from) or its `@trace.uc`
+ * tag (mapped to a PRD via the .feature index). Files that cannot be resolved are
+ * LEFT IN PLACE and listed in the report — never moved to a guessed location.
+ *
+ * DRY-RUN by default (prints the plan, changes nothing). Pass --apply to execute.
+ * Tracked files are moved with `git mv` to preserve history; the rest with fs.rename.
+ * After moving, internal `@trace.source` / path references inside the moved files
+ * are rewritten to the new locations.
+ *
+ * Usage (from the consumer project root):
+ *   node scripts/migrate-specs.js                 # dry-run, prints plan
+ *   node scripts/migrate-specs.js --apply         # execute the migration
+ *   node scripts/migrate-specs.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);
+
+// ── 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 head = (file, n = 4096) => { try { return fs.readFileSync(file, 'utf8').slice(0, n); } catch { return ''; } };
+
+const reSource = /@trace\.source\s*[=:]\s*([^\s)'"]+)/;
+const reUc     = /@trace\.(?:uc|id)\s*[=:]\s*([A-Za-z0-9_-]+)/;
+const reUcName = /\b([A-Za-z][A-Za-z0-9]*-UC\d+)\b/;       // e.g. PAY-UC1, FT-UC3
+// extract {domain}/{slug} from a legacy PRD ref like specs/prd/payment/create-invoice.md
+const slugFromPrdRef = ref => { const m = ref && ref.match(/prd\/([^/]+)\/([^/]+)\.md/); return m ? { domain: m[1], slug: m[2] } : null; };
+
+// ── plan state ─────────────────────────────────────────────────────────────────
+const moves      = [];   // { from(abs), to(abs), type }
+const unresolved = [];   // { file(rel), type, reason }
+const prdByDomain = {};  // domain -> Set(slug)
+const ucToSlug    = {};  // `${domain}/${UC}` -> slug
+const ticketToSlug = {}; // `${domain}/${TICKET}` -> slug (from PRD metadata)
+
+const addSlug = (domain, slug) => { (prdByDomain[domain] = prdByDomain[domain] || new Set()).add(slug); };
+const onlySlug = domain => { const s = prdByDomain[domain]; return s && s.size === 1 ? [...s][0] : null; };
+
+// ── Phase 1 — PRDs: specs/prd/{domain}/{slug}.md → specs/{domain}/{slug}/{TICKET-ID}-{slug}.md ──
+const prdRoot = path.join(specsAbs, 'prd');
+for (const file of walk(prdRoot).filter(f => f.endsWith('.md'))) {
+  const parts = rel(file).split('/');                  // [SPECS, 'prd', domain, ...rest, name.md]
+  const after = parts.slice(parts.indexOf('prd') + 1); // [domain, ...rest, name.md]
+  if (after.length !== 2) { unresolved.push({ file: rel(file), type: 'prd', reason: `expected specs/prd/{domain}/{slug}.md (got depth ${after.length})` }); continue; }
+  const [domain, name] = after;
+  const slug = name.replace(/\.md$/, '');
+  addSlug(domain, slug);
+  // map this PRD's Ticket + UC ids → slug (fallback resolution for other artifacts)
+  const body = head(file, 16384);
+  const ticket = (body.match(/\|\s*\*\*(?:PRD ID|Ticket)\*\*\s*\|\s*([A-Za-z0-9_-]+)/) || [])[1];
+  if (ticket) ticketToSlug[`${domain}/${ticket}`] = slug;
+  let m; const reUcG = new RegExp(reUcName.source, 'g');
+  while ((m = reUcG.exec(body))) ucToSlug[`${domain}/${m[1]}`] = ucToSlug[`${domain}/${m[1]}`] || slug;
+  // PRD file name follows the {TICKET-ID}-{slug}.md convention (falls back to {slug}.md if no ticket found)
+  const prdFile = ticket ? `${ticket}-${slug}.md` : `${slug}.md`;
+  moves.push({ from: file, to: path.join(specsAbs, domain, slug, prdFile), type: 'prd' });
+}
+
+// ── Phase 2 — BDD: specs/bdd/{domain}/{rest} → specs/{domain}/{prd-slug}/bdd/{rest}
+const bddRoot = path.join(specsAbs, 'bdd');
+for (const file of walk(bddRoot).filter(f => f.endsWith('.feature'))) {
+  const after  = rel(file).split('/').slice(rel(file).split('/').indexOf('bdd') + 1); // [domain, ...rest]
+  const domain = after[0];
+  const rest   = after.slice(1).join('/');             // e.g. system/PAY-UC1.feature OR PAY-UC1.feature
+  const h = head(file);
+  let resolved = slugFromPrdRef((h.match(reSource) || [])[1]);
+  const uc = (h.match(reUc) || [])[1] || (path.basename(file).match(reUcName) || [])[1];
+  let slug = resolved && resolved.domain === domain ? resolved.slug : null;
+  if (!slug && uc) slug = ucToSlug[`${domain}/${uc}`];
+  if (!slug) slug = onlySlug(domain);
+  if (!slug) { unresolved.push({ file: rel(file), type: 'bdd', reason: 'cannot resolve prd-slug (no @trace.source / @trace.uc match, and domain has multiple PRDs)' }); continue; }
+  if (uc) ucToSlug[`${domain}/${uc}`] = ucToSlug[`${domain}/${uc}`] || slug;
+  moves.push({ from: file, to: path.join(specsAbs, domain, slug, 'bdd', ...rest.split('/')), type: 'bdd' });
+}
+
+// ── Phase 3 — tech-docs → specs/{domain}/{prd-slug}/tech-docs/{file} ────────────
+const techRoot = path.join(specsAbs, 'tech-docs');
+for (const file of walk(techRoot).filter(f => f.endsWith('.md'))) {
+  const after  = rel(file).split('/').slice(rel(file).split('/').indexOf('tech-docs') + 1);
+  const domain = after[0];
+  const rest   = after.slice(1).join('/');
+  const h = head(file);
+  const src = (h.match(reSource) || [])[1];
+  let slug = (slugFromPrdRef(src) || {}).slug;          // when @trace.source points at the PRD
+  const uc = (h.match(reUc) || [])[1] || (path.basename(file).match(reUcName) || [])[1];
+  if (!slug && uc)  slug = ucToSlug[`${domain}/${uc}`];
+  if (!slug && src) { const m = src.match(/bdd\/(?:.*\/)?([A-Za-z][A-Za-z0-9]*-UC\d+)/); if (m) slug = ucToSlug[`${domain}/${m[1]}`]; }
+  if (!slug) slug = onlySlug(domain);
+  if (!slug) { unresolved.push({ file: rel(file), type: 'tech-docs', reason: 'cannot resolve prd-slug from @trace.source / UC-ID' }); continue; }
+  moves.push({ from: file, to: path.join(specsAbs, domain, slug, 'tech-docs', ...rest.split('/')), type: 'tech-docs' });
+}
+
+// ── Phase 4 — design-spec → specs/{domain}/{prd-slug}/design-spec/{file} ────────
+const dsRoot = path.join(specsAbs, 'design-spec');
+for (const file of walk(dsRoot).filter(f => f.endsWith('.md'))) {
+  const after  = rel(file).split('/').slice(rel(file).split('/').indexOf('design-spec') + 1);
+  const domain = after[0];
+  const rest   = after.slice(1).join('/');
+  const h = head(file);
+  let slug = (slugFromPrdRef((h.match(reSource) || [])[1]) || {}).slug;
+  const ticket = (path.basename(file).match(/^([A-Za-z][A-Za-z0-9]*-\d+|[A-Za-z]+-UC\d+)/) || [])[1];
+  if (!slug && ticket) slug = ticketToSlug[`${domain}/${ticket}`] || ucToSlug[`${domain}/${ticket}`];
+  if (!slug) slug = onlySlug(domain);
+  if (!slug) { unresolved.push({ file: rel(file), type: 'design-spec', reason: 'cannot resolve prd-slug (no @trace.source / ticket match)' }); continue; }
+  moves.push({ from: file, to: path.join(specsAbs, domain, slug, 'design-spec', ...rest.split('/')), type: 'design-spec' });
+}
+
+// ── Phase 5 — trace: flat .trace/{UC-ID}.tsv → .trace/{domain}/{prd-slug}/{UC}.tsv
+if (fs.existsSync(traceAbs)) {
+  for (const file of fs.readdirSync(traceAbs).filter(f => f.endsWith('.tsv'))) {
+    const uc = file.replace(/\.tsv$/, '');
+    const keys = Object.keys(ucToSlug).filter(k => k.endsWith(`/${uc}`));
+    if (keys.length === 0) { unresolved.push({ file: `${TRACE}/${file}`, type: 'trace', reason: `no PRD/feature maps UC ${uc}` }); continue; }
+    if (keys.length > 1)   { unresolved.push({ file: `${TRACE}/${file}`, type: 'trace', reason: `UC ${uc} is ambiguous across domains: ${keys.join(', ')}` }); continue; }
+    const [domain] = keys[0].split('/');
+    const slug = ucToSlug[keys[0]];
+    moves.push({ from: path.join(traceAbs, file), to: path.join(traceAbs, domain, slug, file), type: 'trace' });
+  }
+}
+
+// ── build old→new ref map (repo-root-relative, forward slashes) ────────────────
+const refMap = new Map();
+for (const m of moves) refMap.set(rel(m.from), rel(m.to));
+
+// ── report ──────────────────────────────────────────────────────────────────────
+const byType = moves.reduce((a, m) => ((a[m.type] = (a[m.type] || 0) + 1), a), {});
+console.log('');
+console.log('╔════════════════════════════════════════════╗');
+console.log(`║  migrate-specs  —  ${APPLY ? 'APPLY' : 'DRY RUN'}${' '.repeat(APPLY ? 20 : 18)}║`);
+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 === 0 && unresolved.length === 0) {
+  console.log('Nothing to migrate — no legacy specs/prd, specs/bdd, specs/tech-docs, specs/design-spec, or flat .trace/*.tsv found.');
+  process.exit(0);
+}
+console.log(`Planned moves: ${moves.length}  (${Object.entries(byType).map(([k, v]) => `${k}:${v}`).join('  ')})`);
+console.log('');
+for (const m of moves) console.log(`  ${rel(m.from)}\n    → ${rel(m.to)}`);
+if (unresolved.length) {
+  console.log('');
+  console.log(`⚠️  Unresolved (LEFT IN PLACE — fix the file's @trace.source/@trace.uc or move manually):`);
+  for (const u of unresolved) console.log(`  [${u.type}] ${u.file}\n      ${u.reason}`);
+}
+console.log('');
+
+// ── apply ────────────────────────────────────────────────────────────────────────
+function gitMv(from, to) {
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  execSync(`git mv -k "${rel(from)}" "${rel(to)}"`, { cwd: ROOT, stdio: ['ignore', 'ignore', 'pipe'] });
+}
+function fsMv(from, to) {
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  fs.renameSync(from, to);
+}
+function rewriteRefs(absFile) {
+  if (!/\.(md|feature|tsv|ya?ml)$/.test(absFile)) return 0;
+  let txt; try { txt = fs.readFileSync(absFile, 'utf8'); } catch { 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;
+}
+function pruneEmptyDirs(root) {
+  if (!fs.existsSync(root)) return;
+  for (const e of fs.readdirSync(root, { withFileTypes: true })) {
+    if (e.isDirectory()) pruneEmptyDirs(path.join(root, e.name));
+  }
+  try { if (fs.readdirSync(root).length === 0) fs.rmdirSync(root); } catch {}
+}
+
+if (!APPLY) {
+  console.log('DRY RUN — nothing changed. Re-run with --apply to execute.');
+  console.log('After applying, grep your CODE for stale spec refs the move did not touch:');
+  console.log('  @trace.source=specs/bdd/...   and   specs/{prd,bdd,tech-docs,design-spec}/');
+  process.exit(0);
+}
+
+let moved = 0, failed = 0;
+for (const m of moves) {
+  try {
+    if (fs.existsSync(m.to)) throw new Error('target already exists');
+    (isTracked(m.from) ? gitMv : fsMv)(m.from, m.to);
+    moved++;
+  } catch (e) {
+    failed++;
+    console.log(`  ❌ ${rel(m.from)} — ${e.message}`);
+  }
+}
+// rewrite internal references in every moved file (now at its new path)
+let rewritten = 0;
+for (const m of moves) if (fs.existsSync(m.to)) rewritten += rewriteRefs(m.to) > 0 ? 1 : 0;
+
+// remove now-empty legacy roots
+[prdRoot, bddRoot, techRoot, dsRoot].forEach(pruneEmptyDirs);
+
+console.log('');
+console.log(`✅ Moved ${moved}/${moves.length} files${failed ? ` (${failed} failed)` : ''}.`);
+console.log(`✅ Rewrote internal references in ${rewritten} file(s).`);
+if (unresolved.length) console.log(`⚠️  ${unresolved.length} file(s) left in place (see list above).`);
+console.log('');
+console.log('Next:');
+console.log('  1. Review the moves (git status / git diff).');
+console.log('  2. Grep CODE for stale refs the move did not touch:');
+console.log('       @trace.source=specs/bdd/...   and   specs/{prd,bdd,tech-docs,design-spec}/');
+console.log('  3. Run /validate-traces to confirm coverage still resolves.');
+console.log('  4. Commit.');
+console.log('');

package/scripts/rename-prd-files.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+/**
+ * rename-prd-files.js — rename feature-package PRD files from the old fixed
+ * name `prd.md` to the `{TICKET-ID}-{slug}.md` convention.
+ *
+ *   OLD                                      NEW
+ *   specs/{domain}/{slug}/prd.md             specs/{domain}/{slug}/{TICKET-ID}-{slug}.md
+ *
+ * For each `specs/{domain}/{slug}/prd.md`:
+ *   - slug    = the feature-package folder name (parent dir)
+ *   - TICKET-ID is read from the PRD body — the Metadata table row
+ *     (| **PRD ID** | … | / | **Ticket** | … |) or, failing that, the leading
+ *     token of the H1 title (`# SEG01-…`). PRDs where no ticket can be resolved
+ *     are LEFT IN PLACE and listed in the report — never renamed to a guess.
+ *
+ * After moving, any reference to the old `…/{slug}/prd.md` path inside other
+ * spec / trace files (.md, .feature, .tsv, .yaml) is rewritten to the new path.
+ *
+ * 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/rename-prd-files.js                 # dry-run, prints plan
+ *   node scripts/rename-prd-files.js --apply         # execute the rename
+ *   node scripts/rename-prd-files.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);
+
+// ── 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 head = (file, n = 16384) => { try { return fs.readFileSync(file, 'utf8').slice(0, n); } catch { return ''; } };
+
+// Extract the TICKET-ID from a PRD body. Tries the Metadata table first, then the H1 title.
+function extractTicket(body) {
+  // | **PRD ID** | SEG01 |   /   | **Ticket** | [SEG01](...) |   /   | **TICKET-ID** | SEG01 |
+  let m = body.match(/\|\s*\*\*\s*(?:PRD ID|Ticket(?:\s*ID)?|TICKET-ID|Mã(?:\s*ticket)?)\s*\*\*\s*\|\s*\[?\s*([A-Za-z][A-Za-z0-9_.-]*?)\s*\]?\s*(?:\]\([^)]*\))?\s*\|/i);
+  if (m) return m[1];
+  // H1 title: "# SEG01-segment-scoring-service ..." or "# SEG01 Feature Name"
+  m = body.match(/^#\s+([A-Za-z][A-Za-z0-9_.]*(?:-?\d+)?)\b/m);
+  if (m) return m[1];
+  return null;
+}
+
+// ── plan ───────────────────────────────────────────────────────────────────────
+const moves      = [];   // { from(abs), to(abs) }
+const unresolved = [];   // { file(rel), reason }
+
+// Scan specs/{domain}/{slug}/prd.md  (PRD lives directly in the feature-package folder)
+for (const file of walk(specsAbs).filter(f => path.basename(f) === 'prd.md')) {
+  const parts = rel(file).split('/');                 // [SPECS, domain, slug, 'prd.md']
+  if (parts.length < 4) { unresolved.push({ file: rel(file), reason: `not a feature-package PRD (expected ${SPECS}/{domain}/{slug}/prd.md)` }); continue; }
+  const slug = parts[parts.length - 2];
+  const ticket = extractTicket(head(file));
+  if (!ticket) { unresolved.push({ file: rel(file), reason: 'no TICKET-ID found (add a Metadata "PRD ID"/"Ticket" row or an H1 title, then re-run)' }); continue; }
+  const to = path.join(path.dirname(file), `${ticket}-${slug}.md`);
+  if (rel(to) === rel(file)) continue; // already correctly named (shouldn't happen for prd.md)
+  moves.push({ from: file, to });
+}
+
+// ── old→new ref map (repo-root-relative, forward slashes) ──────────────────────
+const refMap = new Map();
+for (const m of moves) refMap.set(rel(m.from), rel(m.to));
+
+// ── report ──────────────────────────────────────────────────────────────────────
+console.log('');
+console.log('╔════════════════════════════════════════════╗');
+console.log(`║  rename-prd-files  —  ${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 === 0 && unresolved.length === 0) {
+  console.log(`Nothing to rename — no ${SPECS}/{domain}/{slug}/prd.md files found (already on the {TICKET-ID}-{slug}.md convention?).`);
+  process.exit(0);
+}
+console.log(`Planned renames: ${moves.length}`);
+console.log('');
+for (const m of moves) console.log(`  ${rel(m.from)}\n    → ${rel(m.to)}`);
+if (unresolved.length) {
+  console.log('');
+  console.log('⚠️  Left in place (fix the PRD, then re-run):');
+  for (const u of unresolved) console.log(`  ${u.file}\n      ${u.reason}`);
+}
+console.log('');
+
+// ── apply ────────────────────────────────────────────────────────────────────────
+function gitMv(from, to) {
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  execSync(`git mv -k "${rel(from)}" "${rel(to)}"`, { cwd: ROOT, stdio: ['ignore', 'ignore', 'pipe'] });
+}
+function fsMv(from, to) {
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  fs.renameSync(from, to);
+}
+function rewriteRefs(absFile) {
+  if (!/\.(md|feature|tsv|ya?ml)$/.test(absFile)) return 0;
+  let txt; try { txt = fs.readFileSync(absFile, 'utf8'); } catch { 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;
+}
+
+if (!APPLY) {
+  console.log('DRY RUN — nothing changed. Re-run with --apply to execute.');
+  process.exit(0);
+}
+
+let moved = 0, failed = 0;
+for (const m of moves) {
+  try {
+    if (fs.existsSync(m.to)) throw new Error('target already exists');
+    (isTracked(m.from) ? gitMv : fsMv)(m.from, m.to);
+    moved++;
+  } catch (e) {
+    failed++;
+    console.log(`  ❌ ${rel(m.from)} — ${e.message}`);
+  }
+}
+
+// rewrite references to the old prd.md paths across specs/ and .trace/
+let rewritten = 0;
+const scanForRefs = [...walk(specsAbs), ...walk(traceAbs)];
+for (const f of scanForRefs) rewritten += rewriteRefs(f) > 0 ? 1 : 0;
+
+console.log('');
+console.log(`✅ Renamed ${moved}/${moves.length} PRD file(s)${failed ? ` (${failed} failed)` : ''}.`);
+console.log(`✅ Rewrote internal references in ${rewritten} file(s).`);
+if (unresolved.length) console.log(`⚠️  ${unresolved.length} file(s) left in place (see list above).`);
+console.log('');
+console.log('Next:');
+console.log('  1. Review the renames (git status / git diff).');
+console.log('  2. Grep your CODE for stale `…/prd.md` refs the move did not touch.');
+console.log('  3. Run /validate-traces to confirm coverage still resolves.');
+console.log('  4. Commit.');
+console.log('');

package/scripts/upgrade.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# upgrade.sh — Upgrade SDD Framework framework in an existing project.
+#
+# Usage:
+#   bash scripts/upgrade.sh
+#   bash scripts/upgrade.sh --module java-spring   # also upgrade a stack module
+#
+# What it does:
+#   1. Reads current installed version from .agent/FRAMEWORK_VERSION
+#   2. Checks npm registry for the latest published version
+#   3. If newer: runs npx @educa-corp/sdd-framework@latest --init to update .agent/
+#   4. Reports what changed so you can review before committing
+#
+# Requirements:
+#   - Project was set up with init.sh (or npx ... --init)
+#   - .agent/FRAMEWORK_VERSION exists
+
+set -euo pipefail
+
+AGENT_DIR=".agent"
+VERSION_FILE="${AGENT_DIR}/FRAMEWORK_VERSION"
+
+echo ""
+echo "╔══════════════════════════════════════════╗"
+echo "║   SDD Framework — Upgrade                 ║"
+echo "╚══════════════════════════════════════════╝"
+echo ""
+
+# ── Prerequisite checks ───────────────────────────────────────────────────────
+
+if ! command -v node &> /dev/null; then
+  echo "❌ Node.js is required. Install from https://nodejs.org"
+  exit 1
+fi
+
+if ! command -v npm &> /dev/null; then
+  echo "❌ npm is required. Install Node.js from https://nodejs.org"
+  exit 1
+fi
+
+if [ ! -f "$VERSION_FILE" ]; then
+  echo "❌ .agent/FRAMEWORK_VERSION not found."
+  echo ""
+  echo "   This project was not set up with --init."
+  echo "   To set up the new structure:"
+  echo ""
+  echo "     bash scripts/init.sh"
+  echo "   or:"
+  echo "     npx @educa-corp/sdd-framework --init"
+  echo ""
+  exit 1
+fi
+
+# ── Version comparison ────────────────────────────────────────────────────────
+
+CURRENT=$(cat "$VERSION_FILE" | tr -d '[:space:]')
+echo "Checking npm registry ..."
+
+LATEST=$(npm view @educa-corp/sdd-framework version 2>/dev/null || echo "unknown")
+
+echo ""
+echo "  Installed : v${CURRENT}"
+echo "  Latest    : v${LATEST}"
+echo ""
+
+if [ "$LATEST" = "unknown" ]; then
+  echo "⚠️  Could not reach npm registry. Check your internet connection."
+  exit 1
+fi
+
+if [ "$CURRENT" = "$LATEST" ]; then
+  echo "✅ Already up to date (v${CURRENT}). Nothing to do."
+  echo ""
+  exit 0
+fi
+
+# ── Upgrade ───────────────────────────────────────────────────────────────────
+
+echo "Upgrading v${CURRENT} → v${LATEST} ..."
+echo ""
+
+npx -y @educa-corp/sdd-framework@latest --init "$@"
+
+# ── Post-upgrade guidance ─────────────────────────────────────────────────────
+
+echo ""
+echo "✅ Upgraded to v${LATEST}!"
+echo ""
+echo "Review what changed in .agent/ before committing:"
+echo ""
+echo "  git diff .agent/"
+echo "  git add .agent/"
+echo "  git commit -m 'chore: upgrade spec-driven-docs v${CURRENT} → v${LATEST}'"
+echo ""

package/skills/code/SKILL.md

@@ -0,0 +1,19 @@
+---
+description: Sinh implementation code từ BDD spec đã duyệt kèm tag traceability, hoặc review code read-only đối chiếu spec compliance và quy tắc kiến trúc. Trigger when: "/generate-code", "/review-code", "sinh code", "generate code", "viết code", "implement feature", "review code", "kiểm tra code", "code review", "check implementation".
+---
+
+# Code Skills — Generate & Review
+
+Skill này xử lý `/generate-code` và `/review-code`. Để **không lệch schema/gate**, skill KHÔNG nhân bản — mỗi lệnh thực thi **y hệt** command tương ứng.
+
+## /generate-code — Sinh Implementation Code
+
+→ **Đọc và tuân theo `commands/generate-code.md`** với cùng `$ARGUMENTS`.
+
+Command lo: guard mềm BDD `@trace.status` approved + Design Spec (approved/độ-tươi/sanity) cho FE/App · `--phase=ui`/`--phase=integration` · branch + build verify · trace TSV (22 cột) `@trace.implements`.
+
+## /review-code — Code Review chỉ-đọc (READ-ONLY)
+
+→ **Đọc và tuân theo `commands/review-code.md`** với cùng `$ARGUMENTS`.
+
+Command lo: Pre-Review Scan · 4 lăng kính (Traceability · Layer Architecture · Coding Standards · Spec Compliance) · đề xuất ghi Lesson cho lỗi AI lặp.

package/skills/code/SKILL.tmpl

@@ -0,0 +1,19 @@
+---
+description: Sinh implementation code từ BDD spec đã duyệt kèm tag traceability, hoặc review code read-only đối chiếu spec compliance và quy tắc kiến trúc. Trigger when: "/generate-code", "/review-code", "sinh code", "generate code", "viết code", "implement feature", "review code", "kiểm tra code", "code review", "check implementation".
+---
+
+# Code Skills — Generate & Review
+
+Skill này xử lý `/generate-code` và `/review-code`. Để **không lệch schema/gate**, skill KHÔNG nhân bản — mỗi lệnh thực thi **y hệt** command tương ứng.
+
+## /generate-code — Sinh Implementation Code
+
+→ **Đọc và tuân theo `commands/generate-code.md`** với cùng `$ARGUMENTS`.
+
+Command lo: guard mềm BDD `@trace.status` approved + Design Spec (approved/độ-tươi/sanity) cho FE/App · `--phase=ui`/`--phase=integration` · branch + build verify · trace TSV (22 cột) `@trace.implements`.
+
+## /review-code — Code Review chỉ-đọc (READ-ONLY)
+
+→ **Đọc và tuân theo `commands/review-code.md`** với cùng `$ARGUMENTS`.
+
+Command lo: Pre-Review Scan · 4 lăng kính (Traceability · Layer Architecture · Coding Standards · Spec Compliance) · đề xuất ghi Lesson cho lỗi AI lặp.

package/skills/debug/SKILL.md

@@ -0,0 +1,19 @@
+---
+description: Fix bug với full workflow (branch, test, commit), phân tích debug nhanh các lỗi hoặc hành vi bất ngờ, hoặc kiểm chứng độ phủ traceability giữa spec và code. Trigger when: "/fix-bug", "/debug", "/validate-traces", "fix bug", "sửa bug", "debug lỗi", "phân tích lỗi", "tại sao lỗi này", "validate traces", "kiểm tra traceability", "coverage matrix", "trace drift".
+---
+
+# Debug & Quality Skills — Fix Bug, Debug, Validate Traces
+
+Skill này xử lý `/fix-bug`, `/debug`, `/validate-traces`. Để **không lệch schema/flow**, skill KHÔNG nhân bản — mỗi lệnh thực thi **y hệt** command.
+
+## /fix-bug — Full Bug Fix Workflow
+→ **Đọc và tuân theo `commands/fix-bug.md`** với cùng `$ARGUMENTS`.
+(Command lo: bug-type table theo platform · đọc `{BUG-ID}` report · regression test · build + push 2 tầng (umbrella) · BUG State `Open→Fixed`→`Closed` · đề xuất Lesson.)
+
+## /debug — Phân tích nhanh
+→ **Đọc và tuân theo `commands/debug.md`** với cùng `$ARGUMENTS`.
+(Command lo: 4 path (stack trace / reproduce / test fail / câu hỏi code) · bảng lỗi theo từng platform/module · stack-trace đọc dưới-lên.)
+
+## /validate-traces — Traceability Coverage
+→ **Đọc và tuân theo `commands/validate-traces.md`** với cùng `$ARGUMENTS`.
+(Command lo: đọc trace TSV 22 cột authoritative · tính OK/DRIFT/GAP/UNTRACKED + PRD/TECHDOC drift · sync `uc_status` ← `@trace.status` · aggregate dashboard.)

package/skills/debug/SKILL.tmpl

@@ -0,0 +1,19 @@
+---
+description: Fix bug với full workflow (branch, test, commit), phân tích debug nhanh các lỗi hoặc hành vi bất ngờ, hoặc kiểm chứng độ phủ traceability giữa spec và code. Trigger when: "/fix-bug", "/debug", "/validate-traces", "fix bug", "sửa bug", "debug lỗi", "phân tích lỗi", "tại sao lỗi này", "validate traces", "kiểm tra traceability", "coverage matrix", "trace drift".
+---
+
+# Debug & Quality Skills — Fix Bug, Debug, Validate Traces
+
+Skill này xử lý `/fix-bug`, `/debug`, `/validate-traces`. Để **không lệch schema/flow**, skill KHÔNG nhân bản — mỗi lệnh thực thi **y hệt** command.
+
+## /fix-bug — Full Bug Fix Workflow
+→ **Đọc và tuân theo `commands/fix-bug.md`** với cùng `$ARGUMENTS`.
+(Command lo: bug-type table theo platform · đọc `{BUG-ID}` report · regression test · build + push 2 tầng (umbrella) · BUG State `Open→Fixed`→`Closed` · đề xuất Lesson.)
+
+## /debug — Phân tích nhanh
+→ **Đọc và tuân theo `commands/debug.md`** với cùng `$ARGUMENTS`.
+(Command lo: 4 path (stack trace / reproduce / test fail / câu hỏi code) · bảng lỗi theo từng platform/module · stack-trace đọc dưới-lên.)
+
+## /validate-traces — Traceability Coverage
+→ **Đọc và tuân theo `commands/validate-traces.md`** với cùng `$ARGUMENTS`.
+(Command lo: đọc trace TSV 22 cột authoritative · tính OK/DRIFT/GAP/UNTRACKED + PRD/TECHDOC drift · sync `uc_status` ← `@trace.status` · aggregate dashboard.)

package/skills/design-spec/SKILL.md

@@ -0,0 +1,11 @@
+---
+description: Sinh tài liệu Design Specification cho platform FE hoặc App từ một Business PRD. Trigger when: "/generate-design-spec", "tạo design spec", "generate design spec", "viết design spec", "tạo tài liệu thiết kế UI", "generate UI spec", "cần design spec cho", "tôi muốn spec UI", "tài liệu cho FE", "tài liệu cho app".
+---
+
+# /generate-design-spec — Generate Design Specification (FE / App)
+
+Skill này xử lý `/generate-design-spec`. Để **không lệch gate/schema**, skill KHÔNG nhân bản — thực thi **y hệt** command.
+
+→ **Đọc và tuân theo `commands/generate-design-spec.md`** với cùng `$ARGUMENTS`.
+
+Command lo: guard PRD approved (mềm) · ghi `Built from PRD` + Version Check drift · Figma per-screen node-level link (`?node-id=`) fetch qua MCP, màn thiếu link → ❌ Missing → Status giữ `draft` · Screen Inventory/Specs/States · Interaction Patterns + Platform Considerations theo platform · AC-UI (Verified by) · **Self-Review Gate** trước khi ghi · chỉ FE/App (BE bị từ chối).

package/skills/design-spec/SKILL.tmpl

@@ -0,0 +1,11 @@
+---
+description: Sinh tài liệu Design Specification cho platform FE hoặc App từ một Business PRD. Trigger when: "/generate-design-spec", "tạo design spec", "generate design spec", "viết design spec", "tạo tài liệu thiết kế UI", "generate UI spec", "cần design spec cho", "tôi muốn spec UI", "tài liệu cho FE", "tài liệu cho app".
+---
+
+# /generate-design-spec — Generate Design Specification (FE / App)
+
+Skill này xử lý `/generate-design-spec`. Để **không lệch gate/schema**, skill KHÔNG nhân bản — thực thi **y hệt** command.
+
+→ **Đọc và tuân theo `commands/generate-design-spec.md`** với cùng `$ARGUMENTS`.
+
+Command lo: guard PRD approved (mềm) · ghi `Built from PRD` + Version Check drift · Figma per-screen node-level link (`?node-id=`) fetch qua MCP, màn thiếu link → ❌ Missing → Status giữ `draft` · Screen Inventory/Specs/States · Interaction Patterns + Platform Considerations theo platform · AC-UI (Verified by) · **Self-Review Gate** trước khi ghi · chỉ FE/App (BE bị từ chối).

package/skills/discovery/SKILL.md

@@ -0,0 +1,14 @@
+---
+description: Dẫn dắt product discovery cho một feature mới qua Q&A có cấu trúc. Trigger when: "/define-product", "khám phá tính năng", "define new feature", "start new feature", "product discovery", "tôi muốn build tính năng mới", "let's define a feature", "begin feature discovery".
+---
+
+# /define-product — Feature Discovery (Q&A theo phase)
+
+Lệnh này thực thi **y hệt** `commands/define-product.md` — không nhân bản logic ở đây để tránh lệch cấu trúc / phase / path output.
+
+`commands/define-product.md` dẫn PO qua các phase Q&A có checkpoint:
+Knowledge Sync → Feature Definition (Context/Problem/Goal/Actor/In&Out Scope/User Story/Phụ thuộc liên service) → User Flow (kèm Edge Cases) → Clarification Log → Business Rules → Business Logic → Acceptance Criteria → Validation Report.
+
+Output ghi `{paths.product_definitions_dir}/{TICKET-ID}-{slug}.md` theo `templates/product-definition.template.md` — input cho `/generate-prd`.
+
+→ **Đọc và tuân theo `commands/define-product.md`** với cùng `$ARGUMENTS`.