@educa-corp/fw 0.0.0-stage → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Có gì mới
+
+> `fw install` in các mục của những version mới hơn bản đang cài trong dự án.
+> Mỗi lần sửa lệnh, khuôn, bộ câu hỏi hay công cụ đều phải tăng version và thêm một mục ở đây. Test sẽ báo lỗi nếu version chưa có mục.
+
+## 0.6.0 — 2026-09-30
+
+- Sẵn sàng publish lên npmjs với tên **`@educa-corp/fw`**. Cài lần đầu: `npx @educa-corp/fw install`.
+- **`fw upgrade [version]`**: nâng cấp lên bản mới nhất, hoặc đúng một version (ví dụ `npx @educa-corp/fw upgrade 0.7.0`).
+- `fw install` chép cả **`fw.js`** vào `.fw/core/bin/`. Hook và CI chạy bản này **offline**, luôn đúng version đã commit, không gọi `@latest`.
+- `fw install` cảnh báo khi Python cài từ Microsoft Store (bản này thỉnh thoảng thoát lỗi mà không chạy script). Lệnh AI gặp lỗi mà không có thông báo nào thì chạy lại một lần.
+
+## 0.5.0 — 2026-09-30
+
+- **Mã mục ổn định**: mỗi mục trong khuôn có mã ẩn cạnh tiêu đề, ví dụ `## 6. Ràng buộc <!-- sec:constraints -->`. Số và tên tiêu đề đổi tự do. Script và AI tìm mục theo mã.
+- `spec_edit.py`: `section <file> <mã>` đọc đúng một mục · `upgrade <file>` gắn mã cho file theo khuôn cũ và liệt kê mục còn thiếu · chặn tạo file thiếu mục của khuôn · chặn sửa làm mất mã mục.
+- Thay cho cách tìm mục theo tên ở 0.4.0: đổi tên tiêu đề sẽ làm cách đó không tìm thấy mục.
+
+## 0.4.0 — 2026-09-30
+
+- Tầng sản phẩm (tham khảo BRD): thêm cột **Giai đoạn** (MVP, Phase 2…) cho bảng epic, mục **Ràng buộc** có mã `CON-01`…, trường duyệt `approved_by` / `approved_at`. Ba mục tuỳ chọn: Stakeholders, Giả định và phụ thuộc, Rủi ro. Ba mục này chỉ trích từ tài liệu PO đưa vào, không hỏi riêng.
+- `/prd` đọc Ràng buộc của tầng sản phẩm. Rule bắt nguồn từ ràng buộc thì ghi `(nguồn: CON-xx)`.
+- Duyệt tầng sản phẩm hoặc PRD phải ghi rõ người duyệt. `spec_edit` chặn nếu thiếu.
+- Mục trong `product.md` giờ được tìm theo **tên**, không theo số thứ tự. File theo khuôn cũ được bổ sung mục và cột còn thiếu khi chạy lại `/product`.
+
+## 0.3.0 — 2026-09-30
+
+- Lệnh mới `/prd`: `/prd <EPIC-ID>` tạo PRD từ epic đã `ready` · `/prd <EPIC-ID> change <mô tả>` thêm, sửa hoặc bỏ nội dung. Mã ổn định (`UC-001`, `UC-001-BR01`, `UC-001-AC01`), không bao giờ đánh số lại.
+- `spec_edit.py`: `next-uc` (cấp mã UC kế tiếp) · `coverage` (kiểm mọi rule và tiêu chí của epic đều có trong PRD) · chặn đặt `ready` / `approved` khi còn 🤖 hoặc còn câu hỏi mở.
+- Khuôn epic: rule và tiêu chí đánh số `R1.`, `AC1.` để `/prd` kiểm được không rơi mục nào.
+
+## 0.2.0 — 2026-09-30
+
+- `spec_edit.py` có thêm `pending` (liệt kê các dòng còn 🤖) và `confirm <mã…>` (đổi 🤖 → ✅ theo mã, ví dụ `AC2 R8b`). AI không phải tự viết script cho hai việc này nữa.
+- `/product`: tối đa 4 câu hỏi mỗi lượt, **tính cả câu phụ**.
+- `/product`: khuôn tầng sản phẩm có thêm mục "Câu hỏi còn mở". File cũ được bổ sung mục này khi chạy tiếp.
+- `/product`: có `business-dictionary.md` của framework cũ thì đề xuất gộp vào `glossary.md`.
+- `/product`: chốt xong một checkpoint thì gợi ý `/clear` rồi chạy tiếp ở phiên mới, để giảm chi phí. Nếu lệnh được gọi trong một phiên đã có hội thoại khác thì nhắc `/clear` ngay từ đầu.
+- `fw install` in ra version cũ → mới kèm danh sách thay đổi.
+
+## 0.1.0 — 2026-09-29
+
+- Lệnh đầu tiên: `/product` (tầng sản phẩm và một epic).
+- `fw install`: cài lệnh, bộ câu hỏi, khuôn; sao lưu file bạn đã sửa; tạo `.fw/config.yaml`.
+- AI sửa file spec bằng `tools/spec_edit.py` (bắt buộc có Python 3.8+).

package/bin/config.template.yaml

@@ -0,0 +1,16 @@
+# .fw/config.yaml — cấu hình của dự án.
+# Bạn được sửa file này. `fw install` chỉ tạo khi chưa có, không bao giờ ghi đè.
+
+workspace: {{WORKSPACE}}
+
+# Thư mục chứa mọi tài liệu (product, PRD, BDD, TDD, kiến trúc).
+# Umbrella: trỏ vào repo spec, ví dụ: spec-repo/specs
+specs: specs
+
+# [jira] | [builtin] | [jira, builtin]
+tracker: [builtin]
+
+# Mỗi unit là một codebase build/deploy độc lập.
+units: []
+#  - { name: web-phuhuynh, path: apps/parent-web, stack: react }
+#  - { name: api,          path: services/api,    stack: java-spring }

package/bin/fw.js

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+const PACKAGE = '@educa-corp/fw';
+const MANIFEST = '.fw/core/manifest.json';
+
+// fw.js chạy ở hai nơi:
+//  - trong gói npm (có commands/, ref/…): cài được vào dự án;
+//  - bản đã chép vào dự án (.fw/core/bin/fw.js): để hook và CI chạy offline, đúng version đã commit.
+//    Bản này không có nguồn để cài; nâng cấp thì gọi gói npm qua `upgrade`.
+const FW_ROOT = path.join(__dirname, '..');
+const IS_PACKAGE = fs.existsSync(path.join(FW_ROOT, 'commands'));
+const VERSION = IS_PACKAGE
+  ? require(path.join(FW_ROOT, 'package.json')).version
+  : JSON.parse(fs.readFileSync(path.join(FW_ROOT, 'manifest.json'), 'utf8')).version;
+
+// Nguồn trong package → đích trong dự án.
+const SOURCES = [
+  { from: 'commands', to: '.claude/commands' },
+  { from: 'ref', to: '.fw/core/ref' },
+  { from: 'templates', to: '.fw/core/templates' },
+  { from: 'tools', to: '.fw/core/tools' },
+  { from: 'bin/fw.js', to: '.fw/core/bin/fw.js' },
+];
+// Mọi file gói npm phải mang theo để fw.js chạy được — test đối chiếu với `files` của package.json.
+const RUNTIME_FILES = ['package.json', 'CHANGELOG.md', 'bin/config.template.yaml', ...SOURCES.map((s) => s.from)];
+const CONFIG = '.fw/config.yaml';
+const SETTINGS = '.claude/settings.json';
+
+// Lệnh AI dùng để sửa file spec (xem tools/spec_edit.py). Cho phép sẵn để PO không bị hỏi quyền mỗi lần.
+const SPEC_EDIT = '.fw/core/tools/spec_edit.py';
+const PYTHON_CANDIDATES = [['python'], ['python3'], ['py', '-3']];
+const ALLOW_RULES = PYTHON_CANDIDATES.map((c) => `Bash(${c.join(' ')} ${SPEC_EDIT}:*)`);
+const MIN_PY_MINOR = 8;
+
+const sha = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
+const toPosix = (p) => p.split(path.sep).join('/');
+
+function walk(dir) {
+  if (!fs.existsSync(dir)) return [];
+  if (fs.statSync(dir).isFile()) return [dir];
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) return walk(p);
+    return e.name === '.gitkeep' ? [] : [p];
+  });
+}
+
+function readManifest(target) {
+  const p = path.join(target, MANIFEST);
+  return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf8')) : { files: {} };
+}
+
+// Chép một file đè lên bản cũ; bản cũ mà người dùng đã sửa thì sao lưu trước.
+function backup(target, rel, stamp) {
+  const dest = path.join(target, '.fw/backup', stamp, rel);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(path.join(target, rel), dest);
+}
+
+// Tìm Python 3.8+. Trên Windows, `python` có thể là lối tắt của Microsoft Store: chạy được nhưng
+// chỉ in lời mời cài — nên phải đọc số version, không chỉ xem lệnh có chạy hay không.
+function findPython() {
+  for (const [cmd, ...args] of PYTHON_CANDIDATES) {
+    const r = spawnSync(cmd, [...args, '--version'], { encoding: 'utf8' });
+    const m = /Python 3\.(\d+)/.exec(`${r.stdout || ''}${r.stderr || ''}`);
+    if (r.status === 0 && m && Number(m[1]) >= MIN_PY_MINOR) {
+      const exe = spawnSync(cmd, [...args, '-c', 'import sys; print(sys.executable)'], { encoding: 'utf8' });
+      return { cmd: [cmd, ...args].join(' '), store: /WindowsApps/i.test(exe.stdout || '') };
+    }
+  }
+  return null;
+}
+
+// Thêm luật cho phép vào .claude/settings.json, giữ nguyên mọi cấu hình khác của dự án.
+function allowSpecEdit(target) {
+  const p = path.join(target, SETTINGS);
+  let settings = {};
+  if (fs.existsSync(p)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(p, 'utf8'));
+    } catch {
+      return { error: `${SETTINGS} không phải JSON hợp lệ — không sửa. Tự thêm vào permissions.allow: ${ALLOW_RULES.join(', ')}` };
+    }
+  }
+  settings.permissions = settings.permissions || {};
+  const allow = (settings.permissions.allow = settings.permissions.allow || []);
+  const added = ALLOW_RULES.filter((r) => !allow.includes(r));
+  if (!added.length) return { added };
+  allow.push(...added);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(settings, null, 2) + '\n');
+  return { added };
+}
+
+function install(target) {
+  const old = readManifest(target);
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const next = {};
+  const report = { added: [], updated: [], backedUp: [], removed: [], kept: [] };
+
+  for (const { from, to } of SOURCES) {
+    const srcDir = path.join(FW_ROOT, from);
+    for (const src of walk(srcDir)) {
+      const rel = toPosix(path.join(to, path.relative(srcDir, src)));
+      const dest = path.join(target, rel);
+      const content = fs.readFileSync(src);
+      next[rel] = sha(content);
+
+      if (fs.existsSync(dest)) {
+        const current = sha(fs.readFileSync(dest));
+        if (current === next[rel]) continue;
+        // Không có trong manifest (file sẵn của dự án) hoặc lệch manifest (người dùng đã sửa).
+        if (old.files[rel] !== current) {
+          backup(target, rel, stamp);
+          report.backedUp.push(rel);
+        }
+        report.updated.push(rel);
+      } else {
+        report.added.push(rel);
+      }
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, content);
+    }
+  }
+
+  // Gỡ file framework đã bỏ — chỉ khi còn nguyên bản; người dùng đã sửa thì giữ lại.
+  for (const [rel, hash] of Object.entries(old.files)) {
+    if (next[rel]) continue;
+    const dest = path.join(target, rel);
+    if (!fs.existsSync(dest)) continue;
+    if (sha(fs.readFileSync(dest)) === hash) {
+      fs.unlinkSync(dest);
+      report.removed.push(rel);
+    } else {
+      report.kept.push(rel);
+    }
+  }
+
+  fs.mkdirSync(path.join(target, '.fw/core'), { recursive: true });
+  fs.writeFileSync(
+    path.join(target, MANIFEST),
+    JSON.stringify({ version: VERSION, files: next }, null, 2) + '\n'
+  );
+
+  const configPath = path.join(target, CONFIG);
+  const configCreated = !fs.existsSync(configPath);
+  if (configCreated) {
+    const tpl = fs.readFileSync(path.join(__dirname, 'config.template.yaml'), 'utf8');
+    fs.writeFileSync(configPath, tpl.replace('{{WORKSPACE}}', path.basename(path.resolve(target))));
+  }
+
+  return {
+    ...report,
+    configCreated,
+    stamp,
+    fromVersion: old.version || null,
+    changes: changesSince(old.version),
+    python: findPython(),
+    permissions: allowSpecEdit(target),
+  };
+}
+
+const cmpVersion = (a, b) => {
+  const [x, y] = [a, b].map((v) => v.split('.').map(Number));
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] - y[i];
+  return 0;
+};
+
+// Các mục CHANGELOG của những version mới hơn bản đang cài. Cài mới (chưa có bản nào) thì không in.
+function changesSince(fromVersion) {
+  if (!fromVersion || cmpVersion(fromVersion, VERSION) >= 0) return [];
+  const text = fs.readFileSync(path.join(FW_ROOT, 'CHANGELOG.md'), 'utf8');
+  return text
+    .split(/^## /m)
+    .slice(1)
+    .map((block) => ({ version: block.split(/\s/)[0], body: block }))
+    .filter((c) => /^\d+\.\d+\.\d+$/.test(c.version) && cmpVersion(c.version, fromVersion) > 0)
+    .map((c) => c.body.split('\n').filter((l) => l.startsWith('- ')));
+}
+
+function printReport(r) {
+  const upgrade = r.fromVersion && r.fromVersion !== VERSION;
+  console.log(upgrade ? `fw ${r.fromVersion} → ${VERSION} — đã nâng cấp` : `fw ${VERSION} — đã cài`);
+  if (r.changes.length) {
+    console.log('  Có gì mới:');
+    r.changes.flat().forEach((l) => console.log(`    ${l}`));
+  }
+  console.log(`  thêm ${r.added.length} · cập nhật ${r.updated.length} · gỡ ${r.removed.length}`);
+  if (r.configCreated) console.log(`  tạo ${CONFIG} — hãy mở file này và khai specs, tracker, units`);
+  if (r.permissions.error) console.log(`  ⚠ ${r.permissions.error}`);
+  else if (r.permissions.added.length) console.log(`  thêm ${r.permissions.added.length} luật cho phép vào ${SETTINGS} (AI sửa spec không phải hỏi quyền)`);
+  if (r.python) {
+    console.log(`  Python: ${r.python.cmd}`);
+    if (r.python.store) {
+      console.log('  ⚠ Python này cài từ Microsoft Store. Khi đo trên máy phát triển framework, bản Store thỉnh thoảng');
+      console.log('    thoát lỗi mà không chạy script (~6% khi nhiều tiến trình cùng lúc). Lệnh AI tự chạy lại một lần,');
+      console.log('    nhưng nên cài bản python.org: winget install Python.Python.3.12');
+    }
+  } else {
+    console.log('');
+    console.log(`  ❌ KHÔNG TÌM THẤY PYTHON 3.${MIN_PY_MINOR}+ — các lệnh AI sẽ dừng ngay cho tới khi cài.`);
+    console.log('     Windows : winget install Python.Python.3.12   (hoặc tải ở https://www.python.org/downloads/)');
+    console.log('     macOS   : brew install python');
+    console.log(`     Sau khi cài, mở terminal mới và chạy lại: npx ${PACKAGE} install`);
+    process.exitCode = 1;
+  }
+  if (r.backedUp.length) {
+    console.log(`  ⚠ ${r.backedUp.length} file bạn đã sửa bị ghi đè, bản cũ ở .fw/backup/${r.stamp}/:`);
+    r.backedUp.forEach((f) => console.log(`    - ${f}`));
+  }
+  if (r.kept.length) {
+    console.log(`  ⚠ ${r.kept.length} file framework đã bỏ nhưng bạn có sửa, nên được giữ lại:`);
+    r.kept.forEach((f) => console.log(`    - ${f}`));
+  }
+}
+
+// Nâng cấp = chạy `install` của gói npm ở đúng version cần lên. Đang chạy đúng gói đó rồi thì cài luôn,
+// không tải lại lần nữa.
+function upgradeCommand(want, target) {
+  const version = want || 'latest';
+  if (IS_PACKAGE && (version === VERSION || (!want && require.main === module && isNpxLatest()))) return null;
+  return ['npx', '-y', `${PACKAGE}@${version}`, 'install', '--target', target];
+}
+
+// Chạy qua `npx @educa-corp/fw upgrade` (không ghi version) thì npx vừa tải bản mới nhất rồi.
+const isNpxLatest = () => /[\\/]_npx[\\/]/.test(__dirname);
+
+function upgrade(want, target, dryRun) {
+  const cmd = upgradeCommand(want, target);
+  if (!cmd) return printReport(install(target));
+  console.log(`Chạy: ${cmd.join(' ')}`);
+  if (dryRun) return;
+  const r = spawnSync(cmd[0], cmd.slice(1), { stdio: 'inherit', shell: process.platform === 'win32' });
+  process.exitCode = r.status === null ? 1 : r.status;
+}
+
+const HELP = `fw ${VERSION}${IS_PACKAGE ? '' : ' (bản đã cài trong dự án)'}
+
+Cách dùng:
+  npx ${PACKAGE} install [--target <thư mục>]   Cài framework vào dự án (lần đầu)
+  npx ${PACKAGE} upgrade [version]              Nâng cấp lên bản mới nhất, hoặc đúng version (vd 0.7.0)
+  fw --version                                  In phiên bản`;
+
+function argValue(rest, flag) {
+  const i = rest.indexOf(flag);
+  return i >= 0 && rest[i + 1] ? rest[i + 1] : null;
+}
+
+function main(argv) {
+  const [cmd, ...rest] = argv;
+  const target = argValue(rest, '--target') || process.cwd();
+  if (cmd === '--version' || cmd === '-v') return console.log(VERSION);
+  if (cmd === 'install') {
+    if (!IS_PACKAGE) {
+      console.log(`Đây là bản fw đã cài trong dự án (${VERSION}), không mang theo nguồn để cài.`);
+      console.log(`Nâng cấp: npx ${PACKAGE} upgrade`);
+      process.exitCode = 1;
+      return;
+    }
+    return printReport(install(target));
+  }
+  if (cmd === 'upgrade') {
+    const want = rest.find((a) => /^\d+\.\d+\.\d+$/.test(a)) || null;
+    return upgrade(want, target, rest.includes('--dry-run'));
+  }
+  console.log(HELP);
+  if (cmd && cmd !== 'help' && cmd !== '--help') process.exitCode = 1;
+}
+
+if (require.main === module) main(process.argv.slice(2));
+
+module.exports = { install, upgradeCommand, RUNTIME_FILES, SOURCES, PACKAGE };

package/commands/prd.md

@@ -0,0 +1,62 @@
+---
+description: Viết PRD chính thức từ epic đã làm rõ (EPIC-ID), hoặc đổi PRD đã có (EPIC-ID change)
+argument-hint: "<EPIC-ID> [change <mô tả thay đổi>] [--force]"
+---
+
+# /prd
+
+Mục đích: biến epic đã làm rõ (`/product`) thành **PRD chính thức**, gồm các use case, rule và tiêu chí chấp nhận có **mã ổn định**. Sau đó PRD là nguồn cho BDD, TDD và code.
+
+- `/prd <EPIC-ID>`: tạo PRD từ epic `ready`.
+- `/prd <EPIC-ID> change <mô tả>`: thêm, sửa hoặc bỏ nội dung trong PRD đã có.
+
+Tham số: `$ARGUMENTS`
+
+## Bước 1 — Nạp context
+
+Nếu **trước lệnh này** phiên đã có hội thoại khác, dòng đầu tiên in: *"💡 Phiên này đã dài. Nên `/clear` rồi gọi lại lệnh để rẻ hơn, vì mọi thứ đã chốt đều nằm trong file."*
+
+1. Chạy **một** lệnh Bash: `python .fw/core/tools/spec_edit.py --check && cat .fw/config.yaml`
+   - Lỗi không tìm thấy python: thử `python3`, rồi `py -3`, và dùng lệnh chạy được cho cả phiên. Cả ba đều lỗi thì **DỪNG NGAY** và báo: *"❌ Máy chưa có Python 3.8+. Cài Python (Windows: `winget install Python.Python.3.12`), mở terminal mới rồi chạy lại lệnh."*
+   - Không có `.fw/config.yaml`: dừng và báo *"Chưa cài framework. Chạy `npx @educa-corp/fw install` ở thư mục gốc dự án."*
+2. Tìm file epic: `{specs}/product/epics/{EPIC-ID}-*.md`. Đọc frontmatter để lấy `slug`, `domain`, `status`.
+3. File PRD: `D = {specs}/{domain}/{slug}/prd.md`.
+4. Đọc `{specs}/product/glossary.md` nếu có, và `SE section {specs}/product/product.md constraints`. Viết đúng thuật ngữ. PRD không được đi ngược ràng buộc nào. Rule bắt nguồn từ ràng buộc thì ghi `(nguồn: CON-01)`. `SE` báo không có mục đó (khuôn cũ): coi như chưa có ràng buộc, và nhắc một dòng *"Chạy `/product` để bổ sung Ràng buộc và Giai đoạn cho tầng sản phẩm."*
+
+## Bước 2 — Chọn chế độ
+
+| Tình huống | Làm gì |
+|---|---|
+| Không có `change`, chưa có `D`, epic `ready` | Chế độ **tạo**: đọc `.fw/core/ref/prd/new.md` |
+| Không có `change`, chưa có `D`, epic **chưa** `ready` | Dừng: *"EP-xx chưa làm rõ xong. Chạy `/product EP-xx` trước."* Có `--force` thì làm tiếp, nhưng in cảnh báo, ghi vào mục 4 của PRD dòng *"Tạo khi epic chưa ready (--force)"*, và không cho `approved` khi epic còn câu hỏi mở |
+| Không có `change`, **đã có** `D` | Dừng: *"PRD đã có. Muốn đổi thì chạy `/prd EP-xx change <mô tả>`."* Không ghi đè |
+| Có `change`, đã có `D` | Chế độ **đổi**: đọc `.fw/core/ref/prd/change.md` |
+| Có `change`, chưa có `D` | Dừng: *"Chưa có PRD. Chạy `/prd EP-xx` trước."* |
+
+## Bước 3 — Luật chung
+
+1. **Mã ổn định.** `UC-NNN` đánh số trên toàn sản phẩm. `UC-NNN-BRnn`, `UC-NNN-ACnn` đánh số trong từng UC. Mã đã cấp thì **không bao giờ đổi, không dùng lại**. Thêm mới thì lấy số kế tiếp trong UC đó. Mục bỏ đi thì giữ dòng, gạch ngang nội dung, và ghi *"Đã bỏ (v…)"*.
+2. **Nguồn.** Mọi rule và tiêu chí lấy từ epic phải ghi `(nguồn: R3, AC1)`, đúng mã của epic.
+3. **Dấu.** Nội dung chuyển nguyên ý từ mục `✅` của epic thì giữ `✅`. Chỗ nào AI **tự thêm, tách hoặc suy ra** thì gắn `🤖`. Chỉ PO mới đổi được `🤖` thành `✅`.
+4. **Ngôn ngữ nghiệp vụ.** Không nói API, bảng dữ liệu hay framework.
+5. **Tối đa 4 câu hỏi mỗi lượt, tính cả câu phụ.**
+6. **Sửa file: CHỈ dùng `spec_edit.py`** (gọi là `SE`). Không dùng Edit/Write, không tự viết script:
+   - Tạo: `SE create <file> <<'EOF'` … `EOF` · Sửa: `SE edit <file> <<'EOF'` `[{"old": "…", "new": "…"}]` `EOF` (gom mọi chỗ sửa của một lượt vào một lần gọi)
+   - Frontmatter: `SE set <file> version=1.1 status=draft updated=YYYY-MM-DD`
+   - `SE pending <file>` · `SE confirm <file> UC-003-BR02 UC-003-AC01` · `SE next-uc {specs}` · `SE coverage <epic> <prd>`
+   - Đọc **một mục**: `SE section <file> <mã>`. Mã mục là `<!-- sec:… -->` ở tiêu đề (vd `constraints`, `usecases`, `open`). **Luôn tìm mục theo mã**, không theo số hay tên tiêu đề, không tự cắt file bằng `sed`/`grep`. Khi sửa, giữ nguyên `<!-- sec:… -->`.
+   - `SE` báo lỗi thì **không có gì được ghi**. Đọc lại file, sửa lệnh rồi chạy lại. Không bỏ qua lỗi. Lỗi mà **không in dòng nào** là Python chưa kịp chạy: chạy lại đúng lệnh đó một lần.
+7. **Duyệt.** `status=approved` chỉ đặt được khi không còn `🤖`, `open_questions=0`, và có người duyệt. Hỏi PO *"Ai duyệt PRD này?"* (mặc định là PO của epic), rồi đặt trong **một** lệnh: `SE set D status=approved approved_by=<tên> approved_at=YYYY-MM-DD`. `SE` tự chặn nếu chưa đủ. Không tìm cách lách.
+
+## Bước 4 — Kết thúc
+
+In ra đúng khối sau:
+
+```
+---
+Trạng thái : {✅ Đã duyệt v{version} | 🟡 Nháp v{version} — còn {n} mục 🤖, {k} câu hỏi mở}
+Đã ghi     : {D} {· epic → handed-off · product.md nếu có}
+Kiểm       : coverage {đủ | thiếu …} · {số UC} UC · {số BR} rule · {số AC} tiêu chí
+Luồng      : Product → [PRD ◀ bạn ở đây] → BDD → TDD · Design-spec → Code → Test → QC
+Bước tiếp  : {/bdd UC-xxx | trả lời / xác nhận các mục trên | `/clear` rồi `/prd {id}` để tiếp}
+```

package/commands/product.md

@@ -0,0 +1,92 @@
+---
+description: Làm rõ yêu cầu — tầng sản phẩm (không tham số) hoặc một epic (có tham số)
+argument-hint: "[EPIC-ID | tên tính năng]"
+---
+
+# /product
+
+Mục đích: **hỏi ngược lại PO** để làm rõ những gì PO biết mà chưa viết ra, **trước** khi viết PRD. Giá trị của lệnh nằm ở **câu hỏi**, không nằm ở việc chép lại tài liệu.
+
+- `/product`: tầng **sản phẩm**, gồm tầm nhìn, nhóm người dùng, danh sách epic.
+- `/product <EPIC-ID | tên>`: làm rõ yêu cầu cho **một epic**.
+
+Tham số: `$ARGUMENTS`
+
+## Bước 1 — Nạp context (chỉ những gì cần)
+
+Nếu **trước lệnh này** phiên đã có hội thoại khác (một lệnh khác, hoặc một lần `/product` trước), thì dòng đầu tiên in ra: *"💡 Phiên này đã dài. Nên `/clear` rồi gọi lại lệnh để rẻ hơn, vì mọi thứ đã chốt đều nằm trong file."* Sau đó vẫn làm tiếp bình thường.
+
+1. Chạy **một** lệnh Bash: `python .fw/core/tools/spec_edit.py --check && cat .fw/config.yaml`
+   - Lỗi "không tìm thấy python": thử lại lần lượt với `python3`, rồi `py -3`, và dùng lệnh chạy được cho cả phiên. Cả ba đều lỗi thì **DỪNG NGAY**, không hỏi gì thêm, và báo: *"❌ Máy chưa có Python 3.8+. Cài Python (Windows: `winget install Python.Python.3.12`), mở terminal mới rồi chạy lại lệnh."*
+   - Không có `.fw/config.yaml`: dừng và báo *"Chưa cài framework vào dự án này. Chạy `npx @educa-corp/fw install` ở thư mục gốc dự án."*
+   - Lấy `specs` (thư mục spec) và `tracker` từ config.
+2. Đặt `P = {specs}/product`.
+3. Chế độ epic: đọc thêm `SE section P/product.md actors`, `… epics`, `… constraints` (gộp trong một lệnh Bash) và `P/glossary.md` nếu có. Epic không được đi ngược một ràng buộc `CON-xx`. PO muốn làm vậy thì hỏi PO có sửa ràng buộc ở tầng sản phẩm không.
+   **Không** đọc PRD khác, trừ khi PO nhắc tới một tính năng liên quan.
+4. **Bảng thuật ngữ cũ.** Nếu `{specs}/domain-knowledge/business-dictionary.md` (của framework cũ) có **dòng thuật ngữ thật** (không chỉ là khuôn trống), thì ở lượt hỏi đầu, đề xuất gộp các thuật ngữ đó vào `P/glossary.md`. PO đồng ý thì gộp, sau đó hỏi PO xoá file cũ hay giữ. Mục tiêu là dự án chỉ còn **một** bảng thuật ngữ.
+
+## Bước 2 — Xác định file đích
+
+| Chế độ | File đích | Khuôn |
+|---|---|---|
+| Sản phẩm | `P/product.md` | `.fw/core/templates/product.md` |
+| Epic | `P/epics/{id}-{slug}.md` | `.fw/core/templates/product-epic.md` |
+
+Xác định `id` và `slug` của epic:
+- `$ARGUMENTS` khớp một mã trong bảng epic của `product.md` thì dùng mã đó.
+- `$ARGUMENTS` là tên tính năng: tìm trong bảng epic. Không thấy thì hỏi PO mã epic (Jira key, hoặc để AI đánh `EP-xx` nếu `tracker` chỉ có `builtin`).
+- `slug` = kebab-case của tên, chỉ gồm `a-z 0-9 -`. Chỉ sinh **một lần** ở đây. PRD, BDD, TDD của epic dùng lại nguyên văn.
+- Epic mà chưa có `product.md` thì vẫn chạy được, nhưng báo trước một dòng: *"Chưa có tầng sản phẩm, nhóm người dùng sẽ không được chuẩn hoá."*
+
+**File đích đã tồn tại** thì đọc `.fw/core/ref/product/resume.md` và làm theo đó. Không ghi đè.
+
+## Bước 3 — Luật khi hỏi (áp cho mọi checkpoint)
+
+1. **AI trích, PO xác nhận.** PO dán tài liệu vào thì đó là **nguyên liệu**, không phải câu trả lời thay cho các bước.
+   - Mục mà tài liệu đã có: trình bản trích với dấu `🤖`, rồi hỏi *"Đúng chưa, cần sửa gì?"*
+   - Mục mà tài liệu chưa có: hỏi mới.
+   - Chỉ khi PO xác nhận thì mới đổi `🤖` thành `✅`. **Không bao giờ tự đổi thay PO.**
+2. **Không bỏ checkpoint**, kể cả khi tài liệu rất dày.
+3. **Tối đa 4 câu hỏi mỗi lượt, tính cả câu phụ.** Mọi chỗ cần PO trả lời hoặc xác nhận đều được **đánh số** trong 4 câu đó, không kèm thêm "còn vài điểm…" ở ngoài. Còn câu thì để lượt sau.
+4. **Chỉ nói ngôn ngữ nghiệp vụ.** Không hỏi và không đề xuất API, bảng dữ liệu hay framework.
+5. Gặp **thuật ngữ mới** (lặp từ 2 lần trở lên, chưa có trong `glossary.md`) thì đưa vào lượt hỏi kế tiếp: nghĩa là gì, có thêm vào `glossary.md` không.
+
+## Bước 4 — Đi qua các checkpoint
+
+Đọc bộ câu hỏi, và **chỉ đọc phần của checkpoint đang làm**:
+- Sản phẩm: `.fw/core/ref/product/product-level.md` (2 checkpoint)
+- Epic: `.fw/core/ref/product/epic.md` (3 checkpoint)
+
+Trước checkpoint 1 của epic, AI tự điền mục **Bối cảnh hệ thống** (nhóm người dùng liên quan, tính năng đã có liên quan, thuật ngữ mới). Mục này không cần PO.
+
+**Sửa file: CHỈ dùng `spec_edit.py`** (gọi là `SE` bên dưới). Không dùng Edit/Write, không tự viết script:
+- Tạo file mới: `SE create <file> <<'EOF'` … nội dung … `EOF`
+- Sửa nội dung: `SE edit <file> <<'EOF'` `[{"old": "…", "new": "…"}]` `EOF`. Gom mọi chỗ sửa của một lượt vào **một** lần gọi. Đoạn lặp giống nhau thì thêm `"all": true`.
+- Frontmatter: `SE set <file> checkpoint=1 open_questions=3 updated=YYYY-MM-DD`
+- Xem các mục còn chờ PO: `SE pending <file>`. PO xác nhận các mục có mã: `SE confirm <file> AC2 AC3 R8b`
+- Đọc một mục: `SE section <file> <mã>` (mã là `<!-- sec:… -->` ở tiêu đề). **Luôn tìm mục theo mã**, không theo số hay tên. Khi sửa, giữ nguyên `<!-- sec:… -->`.
+- `SE` báo lỗi thì **không có gì được ghi**. Đọc lại file, sửa lệnh rồi chạy lại. Không bỏ qua lỗi. Lỗi mà **không in dòng nào** là Python chưa kịp chạy: chạy lại đúng lệnh đó một lần.
+
+**Sau mỗi checkpoint** mà PO đã chốt:
+1. **Ghi file ngay.** Không đợi tới cuối, để lần sau chạy tiếp được.
+2. `SE set` các trường `checkpoint`, `open_questions` (đếm số dòng trong mục `sec:open` của file, **không** đếm câu vừa hỏi trong lượt), `updated`.
+3. Checkpoint chỉ được tính là chốt khi **mọi mục của nó mang `✅`**. Còn mục `🤖` thì không tăng `checkpoint`.
+
+PO muốn dừng giữa chừng thì ghi file với trạng thái hiện tại (câu chưa trả lời đưa vào mục `sec:open`) rồi báo: *"Đã lưu. Chạy lại `/product {id}` để tiếp tục."*
+
+**Mở phiên mới sau mỗi checkpoint.** Mọi thứ đã chốt đều nằm trong file, nên phiên mới không mất gì, và ngữ cảnh quay về mức ban đầu thay vì phình dần. Vì vậy ngay sau khi một checkpoint được chốt (còn checkpoint tiếp theo), khối kết thúc ghi *Bước tiếp* là: `/clear` rồi `/product {id}`.
+
+## Bước 5 — Kết thúc
+
+- Epic đủ điều kiện `ready` (xem cuối `epic.md`): đặt `status: ready`, và cập nhật cột **Trạng thái** của epic đó trong `P/product.md` thành `sẵn sàng PRD`.
+- Glossary: PO đồng ý thêm thuật ngữ nào thì ghi vào `P/glossary.md` (tạo file nếu chưa có), dạng bảng `| Thuật ngữ | Nghĩa | Tên tiếng Anh |`.
+
+In ra đúng khối sau:
+
+```
+---
+Trạng thái : {✅ Sẵn sàng | 🟡 Đang làm rõ — checkpoint {n}/{tổng}, còn {k} câu hỏi mở}
+Đã ghi     : {đường dẫn file} {· glossary.md nếu có sửa}
+Luồng      : [Product ◀ bạn ở đây] → PRD → BDD → TDD · Design-spec → Code → Test → QC
+Bước tiếp  : {/prd {id} | vừa chốt checkpoint: `/clear` rồi `/product {id}` (phiên mới, rẻ hơn) | đang giữa checkpoint: trả lời các câu trên}
+```

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@educa-corp/fw",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.0",
+  "description": "Framework làm việc với Claude Code cho phòng PTPM",
+  "bin": {
+    "fw": "bin/fw.js"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\"",
+    "release:check": "node scripts/release-check.js",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm test && node scripts/release-check.js",
+    "pub": "npm publish --access public"
+  },
+  "files": [
+    "bin/",
+    "commands/",
+    "ref/",
+    "templates/",
+    "tools/",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude-code",
+    "spec-driven",
+    "workflow"
+  ],
+  "author": "duclm2 <duclm2@edupia.vn>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/ref/prd/change.md

@@ -0,0 +1,32 @@
+# /prd — chế độ đổi
+
+Dùng cho **mọi** thay đổi: thêm, sửa, bỏ. Mã không bao giờ đánh số lại, nên không cần tách riêng "thêm" với "sửa".
+
+## Lượt 1 — Kế hoạch thay đổi
+
+1. Đọc `D`. Lấy mô tả thay đổi từ `$ARGUMENTS`. Không có mô tả thì hỏi PO *"Bạn muốn đổi gì?"* rồi dừng.
+2. Xác định các mục bị ảnh hưởng. Mô tả thay đổi có thể kéo theo mục khác (một rule đổi thì tiêu chí liên quan cũng phải đổi), nên phải tìm cả những mục đó.
+3. Cấp mã cho mục mới:
+   - Rule hoặc tiêu chí mới trong UC có sẵn: số lớn nhất **đang có trong UC đó**, kể cả dòng đã bỏ, cộng một.
+   - UC mới: `SE next-uc {specs}`.
+4. Trình kế hoạch:
+
+| Mã | Loại | Hiện tại | Sẽ thành |
+|---|---|---|---|
+| UC-003-BR02 | sửa | Khoá sau 5 lần sai | Khoá sau 3 lần sai |
+| UC-003-AC05 | thêm | — | Khi sai 3 lần thì … |
+| UC-003-BR04 | bỏ | … | ~~…~~ Đã bỏ (v1.1) |
+
+   Nếu thư mục `{specs}/{domain}/{slug}/bdd/` đã có file của các UC bị ảnh hưởng thì thêm một dòng: *"⚠ UC-003 đã có BDD. Sau khi đổi PRD cần chạy lại `/bdd UC-003`."*
+   Kèm tối đa 3 câu hỏi, chỉ khi thay đổi còn mơ hồ.
+
+## Lượt 2 — Áp thay đổi
+
+Khi PO đồng ý kế hoạch:
+
+1. **Một** lần `SE edit D` cho mọi chỗ sửa:
+   - Mục sửa và mục thêm mang `✅`, vì PO vừa duyệt kế hoạch.
+   - Mục bỏ: giữ dòng, gạch ngang nội dung, ghi *"Đã bỏ (v{mới})"*.
+   - Thêm dòng vào **5. Lịch sử thay đổi**, dạng *"v1.1 — UC-003: khoá sau 3 lần sai (BR02 sửa, AC05 thêm, BR04 bỏ)"*.
+2. Tăng version phụ (1.0 → 1.1): `SE set D version=1.1 updated=…`. PRD đang `approved` thì đặt luôn `status=draft approved_by=— approved_at=—`.
+3. Báo lại cho PO. Không in lại cả PRD, chỉ tóm tắt những gì đã đổi. Nếu không còn `🤖` và không còn câu hỏi mở thì hỏi: *"Duyệt lại bản v1.1 không?"* PO đồng ý thì duyệt theo luật 7 của lệnh. Bản mới cần người duyệt mới, nên đặt lại `approved_by` và `approved_at`.

package/ref/prd/new.md

@@ -0,0 +1,39 @@
+# /prd — chế độ tạo
+
+Chỉ **2 lượt** hỏi-đáp, vì epic đã được làm rõ kỹ. Không hỏi lại những gì epic đã `✅`.
+
+## Lượt 1 — Chia use case
+
+1. Đọc **toàn bộ** file epic.
+2. Chạy `SE next-uc {specs}` để lấy mã UC đầu tiên. Các UC tiếp theo tăng dần từ mã đó.
+3. Đề xuất cách chia UC.
+   - **Một UC = một mục tiêu của một actor**, xong trong một lần tương tác. Ví dụ "Đổi và quên mật khẩu", không phải "Quản lý bảo mật".
+   - Mỗi UC nên có khoảng 2–8 rule. Nhiều hơn thì cân nhắc tách, ít hơn một thì cân nhắc gộp.
+   - **Mọi `R…` và `AC…` của epic phải thuộc ít nhất một UC.** Một rule áp cho nhiều UC thì ghi ở tất cả các UC đó.
+4. Trình cho PO dạng bảng:
+
+| UC | Tên | Actor | Lấy từ epic |
+|---|---|---|---|
+| UC-001 | … | ACT-01 | R8, R9, R10, AC4, AC5 |
+
+   Kèm tối đa 3 câu hỏi khác, chỉ khi cần. Ví dụ: một rule nên đặt vào UC nào, hoặc hai UC có nên gộp không. Không có gì cần hỏi thì chỉ hỏi *"Cách chia này được chưa?"*.
+
+## Lượt 2 — Viết PRD
+
+Khi PO đồng ý cách chia UC:
+
+1. Tạo `D` bằng **một** lần `SE create`, theo khuôn `.fw/core/templates/prd.md`:
+   - **1. Tổng quan:** chuyển từ checkpoint 1 của epic. Ghi các ràng buộc `CON-xx` áp cho epic này.
+   - **2. Use case:** mỗi UC gồm điều kiện trước, kết quả sau, luồng chính (lấy các bước liên quan ở checkpoint 2 của epic), bảng rule, tiêu chí.
+     - **Cột Rule:** một rule mỗi dòng, dạng *"Hệ thống PHẢI / KHÔNG ĐƯỢC …"*.
+     - **Cột Logic:** rẽ nhánh, công thức, thông báo khi lỗi. Lấy từ edge case và nhật ký làm rõ của epic.
+     - **Tiêu chí:** dạng *"Khi … thì …"*, mô tả **kết quả nhìn thấy được**, không mô tả cơ chế.
+   - **3. Màn hình:** chuyển từ "Màn hình chính" của epic, kèm cột UC.
+   - **4. Câu hỏi còn mở:** chỉ những gì phát sinh khi viết PRD.
+   - **5. Lịch sử thay đổi:** dòng `1.0`.
+2. Chạy `SE coverage <epic> D`. **Thiếu mục nào thì bổ sung vào UC phù hợp rồi chạy lại cho tới khi đủ.** Mục mà PO muốn bỏ thì hỏi PO. Không được tự bỏ.
+3. Epic giờ chỉ còn là lịch sử:
+   - `SE set <epic> status=handed-off`
+   - Trong `{specs}/product/product.md`, sửa cột Trạng thái của epic thành `đã có PRD`.
+4. Chạy `SE pending D`. **Chỉ trình các mục `🤖`**, không in lại cả PRD. Mỗi dòng gồm mã và nội dung ngắn gọn. Kèm câu hỏi mở nếu có. Nhắc PO: *"Mở file để đọc toàn bộ. Trả lời, hoặc xác nhận theo mã, ví dụ 'OK UC-003-BR04'."*
+5. Khi PO xác nhận: `SE confirm D <mã…>`. Không còn `🤖` và không còn câu hỏi mở thì duyệt theo luật 7 của lệnh.