@educa-corp/fw 0.8.1 → 0.10.0

package/tools/spec_edit.py

@@ -17,9 +17,19 @@ Cách dùng (nội dung truyền qua stdin):
   spec_edit.py section <file> <mã>        in đúng một mục theo mã `<!-- sec:… -->` (vd constraints)
   spec_edit.py upgrade <file>             gắn mã mục cho file theo khuôn cũ (chạy một lần)
   spec_edit.py next-uc <thư mục specs>    in mã UC kế tiếp (quét mọi prd.md)
+  spec_edit.py item <file>                stdin = JSON [{"id": mã, "new": dòng} | {"after": mã, "new": dòng}] — sửa / thêm theo mã
+  spec_edit.py uc <file> <UC-…>…          in đúng các UC đó
+  spec_edit.py finding <file> <F…>…       in đúng các finding đó (file refine)
+  spec_edit.py decide <file>              stdin = JSON [{"f": "F17", "decision": "nhận | sửa: … | bác: … | hoãn"}]
   spec_edit.py flowcheck <prd>            kiểm User flow: có sơ đồ, mọi UC có mặt trong một hành trình
   spec_edit.py create --replace <file>    chỉ cho file tạm trong .fw/tmp/ (kết quả của agent)
   spec_edit.py coverage <epic> <prd>      liệt kê BR / AC của epic chưa được PRD dùng tới
+  spec_edit.py where <specs> <UC-…>       in đường dẫn PRD chứa UC đó
+  spec_edit.py context <prd> <UC-…>       phần PRD cần cho BDD của một UC (Tổng quan, hành trình, màn hình, UC, mục được trỏ tới)
+  spec_edit.py next-sc <feature>          mã kịch bản kế tiếp (tính cả mã đã bỏ)
+  spec_edit.py scenario <feature> <SC…>…  in đúng các kịch bản đó
+  spec_edit.py sc <feature>               stdin = JSON [{"id": mã, "new": khối} | {"after": mã | "end", "new": khối} | {"remove": mã, "version": "1.1"}]
+  spec_edit.py bddcheck <feature> [prd]   kiểm khuôn, tag, độ phủ AC / BR của file BDD
 
 Mã thoát: 0 = thành công · 1 = lỗi dữ liệu (không ghi gì) · 2 = sai cách dùng.
 """
@@ -38,9 +48,10 @@ FRONTMATTER = {
     "epic": {"status": ["in-progress", "ready", "handed-off"], "checkpoint": (0, 3)},
     "prd": {"status": ["draft", "approved"]},
     "prd-refine": {"status": ["pending", "applied", "done"], "round": (1, 2)},
+    "bdd": {"status": ["draft", "approved"]},
 }
 # Trạng thái "đã xong": chỉ đặt được khi không còn 🤖 và không còn câu hỏi mở.
-DONE_STATUS = {"product": "ready", "epic": "ready", "prd": "approved", "prd-refine": "done"}
+DONE_STATUS = {"product": "ready", "epic": "ready", "prd": "approved", "prd-refine": "done", "bdd": "approved"}
 COMMON_INT = {"open_questions": (0, 999)}
 DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
 VERSION = re.compile(r"^\d+\.\d+$")
@@ -89,6 +100,10 @@ def cmd_create(path, replace=False):
     if os.path.exists(path) and not replace:
         fail(path + " đã tồn tại — không ghi đè. Dùng `edit` hoặc `set`.")
     text = stdin_text()
+    if path.endswith(".feature"):
+        head = feature_header(text)
+        if head.get("type") != "bdd" or head.get("uc") != uc_of(path):
+            fail("file BDD phải mở đầu bằng header theo khuôn bdd.feature: `# type: bdd`, `# uc: %s`, …" % uc_of(path))
     check_keys(file_type(text), [], sec_keys(text), creating=True)
     check_sources(file_type(text), text)
     write(path, text)
@@ -201,6 +216,7 @@ def cmd_flowcheck(path):
     if problems:
         fail("\n  - ".join([""] + problems))
     print("User flow đủ — mọi UC đều có mặt trong ít nhất một hành trình")
+    size_warning(path)
 
 
 def refine_path(prd_path):
@@ -244,18 +260,37 @@ def guard_done(ftype, block, body, path):
             fail("không đặt được status=%s: chưa có %s. Đặt cùng lệnh, ví dụ: "
                  "set <file> status=%s approved_by=<tên> approved_at=YYYY-MM-DD" % (done, field, done))
     if ftype == "prd":
+        ptext = read(path)
+        no_platform = [u for u in re.findall(r"^###\s+(UC-\d{3})(?![\d-])", ptext, re.M) if not uc_platforms(ptext, u)]
+        if no_platform:
+            fail("không đặt được status=approved: chưa khai Nền tảng cho %s. Thêm dòng `- **Nền tảng:** web · app` "
+                 "ở Tổng quan (mặc định cho cả PRD), hoặc trong UC chạy khác mặc định." % ", ".join(no_platform))
         guard_refined(path, block)
+    if ftype == "bdd":
+        guard_bdd(path, block)
     if ftype == "prd-refine" and undecided_findings(body):
         fail("không đặt được status=done: còn finding critical/major chưa có quyết định: %s"
              % ", ".join(undecided_findings(body)))
 
 
+def header_span(path, text):
+    """(đầu, cuối, chỗ bắt đầu thân file, tiền tố dòng) của khối frontmatter.
+    File .feature không có `---` (Gherkin không đọc được), header là các dòng `# key: value` ở đầu file."""
+    if path.endswith(".feature"):
+        m = FEATURE_HEADER.match(text)
+        if not m:
+            fail("file .feature không có header (các dòng `# key: value` ở đầu file, theo khuôn bdd.feature)")
+        return 0, m.end(), m.end(), "# "
+    m = split_frontmatter(text)
+    return m.start(1), m.end(1), m.end(), ""
+
+
 def cmd_set(path, pairs):
     if not pairs:
         fail("cần ít nhất một cặp key=value", 2)
     text = read(path)
-    m = split_frontmatter(text)
-    block = m.group(1)
+    start, end, body_at, prefix = header_span(path, text)
+    block = "\n".join(l[len(prefix):] if l.startswith(prefix) else l for l in text[start:end].split("\n"))
     tm = re.search(r"^type:\s*(\S+)", block, re.M)
     ftype = tm.group(1) if tm else None
 
@@ -271,8 +306,10 @@ def cmd_set(path, pairs):
         # Giữ nguyên comment đi kèm ở cuối dòng, chỉ đổi giá trị.
         block = line.sub(lambda mm: mm.group(1) + value + (mm.group(3) or ""), block, count=1)
 
-    guard_done(ftype, block, text[m.end():], path)
-    write(path, text[: m.start(1)] + block + text[m.end(1):])
+    guard_done(ftype, block, text[body_at:], path)
+    if prefix:
+        block = "\n".join(prefix + l if l else l for l in block.split("\n"))
+    write(path, text[:start] + block + text[end:])
     print("đã đặt %s trong %s" % (", ".join(pairs), path))
 
 
@@ -300,7 +337,7 @@ def sec_keys(text):
 
 
 def file_type(text):
-    m = re.search(r"^type:\s*(\S+)", text, re.M)
+    m = re.search(r"^(?:# )?type:\s*(\S+)", text, re.M)
     return m.group(1) if m else None
 
 
@@ -448,6 +485,120 @@ def cmd_upgrade(path):
               + " · ".join("%s (sec:%s)" % (orig, k) for k, orig in missing))
 
 
+# ── Theo mã: sửa / thêm một dòng BR, AC; đọc một UC, một finding; ghi quyết định ──────────
+# Dòng có mã ở đầu: "| ✅ UC-003-BR10 | …" (bảng BR) · "- ✅ UC-003-AC01. …" (AC) · có thể có ~~ khi đã bỏ.
+def item_line_re(code):
+    return re.compile(r"^(?:\|\s*|-\s+)(?:[\U0001F916\u2705]\s*)?(?:~~)?%s(?![\w-])" % re.escape(code))
+
+
+def find_item(lines, code):
+    pat = item_line_re(code)
+    return [i for i, l in enumerate(lines) if pat.match(l)]
+
+
+def cmd_item(path):
+    """stdin = JSON [{"id": mã, "new": dòng mới} | {"after": mã, "new": dòng(s) mới}]. Sai một là không ghi gì."""
+    try:
+        ops = json.loads(stdin_text())
+    except json.JSONDecodeError as e:
+        fail("stdin không phải JSON hợp lệ: " + str(e), 2)
+    if not isinstance(ops, list) or not ops:
+        fail('stdin phải là danh sách [{"id": …, "new": …}] hoặc [{"after": …, "new": …}]', 2)
+    text = read(path)
+    before = sec_keys(text)
+    lines = text.split("\n")
+    for n, op in enumerate(ops, 1):
+        new = op.get("new")
+        if not isinstance(new, str) or not new.strip():
+            fail("thao tác #%d thiếu `new`" % n, 2)
+        code = op.get("id") or op.get("after")
+        if not code or ("id" in op) == ("after" in op):
+            fail("thao tác #%d phải có đúng một trong `id` (sửa) hoặc `after` (thêm sau)" % n, 2)
+        hits = find_item(lines, code)
+        if len(hits) != 1:
+            fail("thao tác #%d: mã %s khớp %d dòng (cần đúng 1). Dùng `SE uc` để xem lại." % (n, code, len(hits)))
+        if "id" in op:
+            if "\n" in new:
+                fail("thao tác #%d: sửa theo `id` chỉ nhận một dòng" % n, 2)
+            if not item_line_re(code).match(new):
+                fail("thao tác #%d: dòng mới phải giữ nguyên mã %s ở đầu dòng (mã không bao giờ đổi)" % (n, code))
+            lines[hits[0]] = new
+        else:
+            for nl in new.split("\n"):
+                m = re.match(r"^(?:\|\s*|-\s+)(?:[\U0001F916\u2705]\s*)?(?:~~)?(UC-\d{3}-(?:BR|AC)\d+)", nl)
+                if m and find_item(lines, m.group(1)):
+                    fail("thao tác #%d: mã %s đã có — mã không bao giờ dùng lại, lấy số kế tiếp" % (n, m.group(1)))
+            lines[hits[0] + 1:hits[0] + 1] = new.split("\n")
+    out = "\n".join(lines)
+    check_keys(file_type(out), before, sec_keys(out), creating=False)
+    check_sources(file_type(out), out)
+    write(path, out)
+    print("đã áp %d thao tác theo mã trong %s" % (len(ops), path))
+
+
+def print_blocks(path, codes, start_re, kind):
+    lines = read(path).split("\n")
+    for code in codes:
+        pat = start_re(code)
+        hits = [i for i, l in enumerate(lines) if pat.match(l)]
+        if not hits:
+            fail("không có %s %s trong %s" % (kind, code, path))
+        i = hits[0]
+        end = next((j for j in range(i + 1, len(lines)) if re.match(r"^#{2,3}\s", lines[j])), len(lines))
+        print("\n".join(lines[i:end]).rstrip())
+        print()
+
+
+def cmd_uc(path, codes):
+    if not codes:
+        fail("cách dùng: uc <file> UC-003 [UC-005 …]", 2)
+    print_blocks(path, codes, lambda c: re.compile(r"^###\s+(?:~~)?%s(?![\d-])" % re.escape(c)), "UC")
+
+
+def cmd_finding(path, codes):
+    if not codes:
+        fail("cách dùng: finding <file refine> F17 [F18 …]", 2)
+    print_blocks(path, codes, lambda c: re.compile(r"^###\s+%s\s·" % re.escape(c)), "finding")
+
+
+DECISION_VALUE = re.compile(r"^(nhận|hoãn|chờ|sửa:\s*\S.*|bác:\s*\S.*)$")
+
+
+def cmd_decide(path):
+    """stdin = JSON [{"f": "F17", "decision": "nhận" | "sửa: …" | "bác: lý do" | "hoãn"}]. Ghi ngay sau mỗi đợt PO quyết."""
+    try:
+        ops = json.loads(stdin_text())
+    except json.JSONDecodeError as e:
+        fail("stdin không phải JSON hợp lệ: " + str(e), 2)
+    if not isinstance(ops, list) or not ops:
+        fail('stdin phải là danh sách [{"f": "F17", "decision": "…"}]', 2)
+    lines = read(path).split("\n")
+    for n, op in enumerate(ops, 1):
+        code, dec = op.get("f"), (op.get("decision") or "").strip()
+        if not DECISION_VALUE.match(dec):
+            fail("quyết định #%d (%s) không hợp lệ: \"%s\". Nhận: nhận · sửa: <nội dung> · bác: <lý do> · hoãn" % (n, code, dec))
+        head = [i for i, l in enumerate(lines) if re.match(r"^###\s+%s\s·" % re.escape(code or "?"), l)]
+        if len(head) != 1:
+            fail("quyết định #%d: không tìm thấy đúng một finding %s" % (n, code))
+        end = next((j for j in range(head[0] + 1, len(lines)) if re.match(r"^#{2,3}\s", lines[j])), len(lines))
+        dl = [j for j in range(head[0], end) if lines[j].startswith("- Quyết định:")]
+        if len(dl) != 1:
+            fail("finding %s không có đúng một dòng `- Quyết định:`" % code)
+        lines[dl[0]] = "- Quyết định: " + dec
+    write(path, "\n".join(lines))
+    print("đã ghi %d quyết định vào %s" % (len(ops), path))
+
+
+PRD_SIZE_WARN = 60 * 1024
+
+
+def size_warning(path):
+    size = os.path.getsize(path)
+    if size > PRD_SIZE_WARN:
+        print("⚠ PRD %d KB (ngưỡng %d KB): mọi bước sau đều nạp toàn bộ PRD. Cân nhắc tách epic thành nhiều PRD nhỏ hơn."
+              % (size // 1024, PRD_SIZE_WARN // 1024))
+
+
 def cmd_next_uc(specs_dir):
     if not os.path.isdir(specs_dir):
         fail("không có thư mục " + specs_dir)
@@ -481,6 +632,423 @@ def cmd_coverage(epic_path, prd_path):
     if problems:
         fail("\n  - ".join([""] + problems))
     print("đủ — mọi BR/AC của epic đều có trong PRD")
+    size_warning(prd_path)
+
+
+# ── BDD: một file .feature cho mỗi UC, tag Gherkin thật (xem docs/design/bdd.md) ──────────
+FEATURE_HEADER = re.compile(r"(?:# [a-z_]+:[^\n]*\n)+")
+ITEM_CODE = re.compile(r"UC-\d{3}-(?:BR|AC)\d+")
+ITEM_LINE = re.compile("^(?:\\|\\s*|-\\s+)(?:[\U0001F916\u2705]\\s*)?(~~)?(UC-\\d{3}-(?:BR|AC)\\d+)")
+SC_TAG = re.compile(r"@(UC-\d{3}-SC\d+)(?![\w-])")
+SC_ANY = re.compile(r"(UC-(\d{3})-SC(\d+))(?![\w-])")
+SC_TYPES = ("happy", "alternative", "edge", "negative")
+SCENARIO_LINE = re.compile(r"^\s*(Scenario Outline|Scenario Template|Scenario|Example):\s*(.*)$")
+STEP_LINE = re.compile(r"^\s*(Given|When|Then|And|But|\*)\s")
+REMOVED_SC = re.compile(r"^\s*#\s*Đã bỏ \(v[\d.]+\)\s*@(UC-\d{3}-SC\d+)")
+GROUP_LINE = re.compile(r"^\s*#\s*──")
+MARK_COMMENT = re.compile("^\\s*#\\s*[\U0001F916\u2705]")
+PLATFORM_LINE = re.compile("^\\s*-\\s*(?:[\U0001F916\u2705]\\s*)?\\*\\*Nền tảng:\\*\\*\\s*(.+)$")
+
+
+def prd_of(feature):
+    """bdd/UC-001.feature nằm cạnh prd.md: {specs}/{domain}/{slug}/bdd/ → {specs}/{domain}/{slug}/prd.md"""
+    return os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(feature))), "prd.md")
+
+
+def uc_of(feature):
+    m = re.match(r"^(UC-\d{3})\.feature$", os.path.basename(feature))
+    if not m:
+        fail("tên file BDD phải là <UC-NNN>.feature, ví dụ UC-001.feature (đang là %s)" % os.path.basename(feature))
+    return m.group(1)
+
+
+def uc_span(lines, uc):
+    """(đầu, cuối, đã bỏ?) của khối UC trong PRD, hoặc None."""
+    pat = re.compile(r"^###\s+(~~)?%s(?![\d-])" % re.escape(uc))
+    for i, l in enumerate(lines):
+        m = pat.match(l)
+        if m:
+            end = next((j for j in range(i + 1, len(lines)) if re.match(r"^#{2,3}\s", lines[j])), len(lines))
+            return i, end, bool(m.group(1)) or "Đã bỏ (v" in l
+    return None
+
+
+def prd_items(text):
+    """{mã BR/AC: còn dùng?} trên toàn PRD. Dòng có ~~ trước mã, hoặc thuộc UC đã bỏ, là đã bỏ."""
+    lines = text.split("\n")
+    removed_ucs = set(re.findall(r"^###\s+~~(UC-\d{3})", text, re.M))
+    out = {}
+    for l in lines:
+        m = ITEM_LINE.match(l)
+        if m:
+            out[m.group(2)] = not m.group(1) and m.group(2)[:6] not in removed_ucs
+    return out
+
+
+def platform_values(value):
+    value = re.split(r"\(| — ", value)[0]
+    return [v for v in re.findall(r"[a-z][a-z0-9-]*", value.lower())]
+
+
+def uc_platforms(text, uc):
+    """Nền tảng của UC: dòng `Nền tảng` trong UC, không có thì lấy ở Tổng quan. [] = PRD chưa khai."""
+    lines = text.split("\n")
+    span = uc_span(lines, uc)
+    if span:
+        for l in lines[span[0]:span[1]]:
+            m = PLATFORM_LINE.match(l)
+            if m:
+                return platform_values(m.group(1))
+    overview = section_text(text, "overview") or ""
+    for l in overview.split("\n"):
+        m = PLATFORM_LINE.match(l)
+        if m:
+            return platform_values(m.group(1))
+    return []
+
+
+def prd_version(text):
+    m = re.search(r"^version:\s*(\S+)", text, re.M)
+    return m.group(1) if m else None
+
+
+def feature_header(text):
+    m = FEATURE_HEADER.match(text)
+    if not m:
+        return {}
+    out = {}
+    for l in m.group(0).split("\n"):
+        k = re.match(r"^# ([a-z_]+):\s*([^#\n]*?)\s*(?:#.*)?$", l)
+        if k:
+            out[k.group(1)] = k.group(2)
+    return out
+
+
+def parse_feature(text):
+    """Danh sách kịch bản: {line, kind, title, tags, steps, examples} + các mã đã bỏ."""
+    scenarios, removed, tags, cur, in_examples = [], [], [], None, False
+    for i, l in enumerate(text.split("\n")):
+        s = l.strip()
+        rm = REMOVED_SC.match(l)
+        if rm:
+            removed.append(rm.group(1))
+            continue
+        if s.startswith("#") or not s:
+            continue
+        if s.startswith("@"):
+            tags += re.findall(r"@([^\s@]+)", s)
+            continue
+        if re.match(r"^(Feature|Background|Rule):", s):
+            tags, cur = [], None
+            continue
+        m = SCENARIO_LINE.match(l)
+        if m:
+            cur = {"line": i + 1, "outline": m.group(1) in ("Scenario Outline", "Scenario Template"),
+                   "title": m.group(2).strip(), "tags": tags, "steps": [], "examples": -1}
+            scenarios.append(cur)
+            tags, in_examples = [], False
+            continue
+        if cur is None:
+            continue
+        if re.match(r"^(Examples|Scenarios):", s):
+            in_examples, cur["examples"] = True, max(cur["examples"], 0) - 1
+            continue
+        if in_examples and s.startswith("|"):
+            cur["examples"] += 1          # dòng đầu là tiêu đề cột
+            continue
+        st = STEP_LINE.match(l)
+        if st:
+            cur["steps"].append(st.group(1))
+    for sc in scenarios:
+        sc["ids"] = [t for t in sc["tags"] if SC_TAG.match("@" + t)]
+    return scenarios, removed
+
+
+def bdd_report(feature, prd=None):
+    """(lỗi, cảnh báo, số liệu) của một file BDD. Độ phủ tính trên mọi .feature trong cùng thư mục."""
+    prd = prd or prd_of(feature)
+    uc = uc_of(feature)
+    text, ptext = read(feature), read(prd)
+    errors, warns = [], []
+    head = feature_header(text)
+    if head.get("type") != "bdd":
+        errors.append("header thiếu `# type: bdd` ở đầu file")
+    if head.get("uc") != uc:
+        errors.append("header `# uc:` phải là %s (theo tên file), đang là %s" % (uc, head.get("uc") or "trống"))
+    for key in ("prd_version", "version"):
+        if not VERSION.match(head.get(key, "")):
+            errors.append("header `# %s:` phải dạng số.số, ví dụ 1.0" % key)
+    if head.get("status") not in FRONTMATTER["bdd"]["status"]:
+        errors.append("header `# status:` chỉ nhận draft | approved")
+    plines = ptext.split("\n")
+    span = uc_span(plines, uc)
+    if not span:
+        errors.append("PRD %s không có %s" % (prd, uc))
+        return errors, warns, {}
+    if span[2]:
+        errors.append("%s đã bỏ trong PRD — không viết BDD cho UC đã bỏ" % uc)
+    items = prd_items(ptext)
+    own = [c for c, alive in items.items() if alive and c.startswith(uc + "-")]
+    platforms = uc_platforms(ptext, uc)
+    if not platforms:
+        errors.append("PRD chưa khai Nền tảng cho %s (dòng `- **Nền tảng:** web · app` ở Tổng quan, hoặc trong UC). "
+                      "Chạy `/prd <EPIC-ID> change khai nền tảng …` trước." % uc)
+    scenarios, removed = parse_feature(text)
+    if not scenarios:
+        errors.append("file chưa có kịch bản nào")
+    seen = list(removed)
+    per_platform = {p: 0 for p in platforms}
+    for sc in scenarios:
+        where = "dòng %d (%s)" % (sc["line"], sc["title"][:60])
+        if len(sc["ids"]) != 1:
+            errors.append("%s: cần đúng 1 mã @%s-SCnn, đang có %d" % (where, uc, len(sc["ids"])))
+        for sid in sc["ids"]:
+            if not sid.startswith(uc + "-"):
+                errors.append("%s: mã %s không thuộc %s" % (where, sid, uc))
+            if sid in seen:
+                errors.append("%s: mã %s đã dùng (kể cả mã đã bỏ) — lấy `next-sc`" % (where, sid))
+            seen.append(sid)
+        refs = [t for t in sc["tags"] if ITEM_CODE.fullmatch(t)]
+        others = [t for t in sc["tags"] if t not in sc["ids"] and t not in refs]
+        kinds = [t for t in others if t in SC_TYPES]
+        plats = [t for t in others if t in platforms]
+        unknown = [t for t in others if t not in SC_TYPES and t not in platforms]
+        if len(kinds) != 1:
+            errors.append("%s: cần đúng 1 loại (@%s), đang có %d" % (where, " @".join(SC_TYPES), len(kinds)))
+        # PRD chưa khai nền tảng thì đã có một lỗi chung ở trên — không báo lặp lại ở từng kịch bản.
+        if platforms and not plats:
+            errors.append("%s: thiếu tag nền tảng (UC khai: %s)" % (where, " · ".join(platforms)))
+        if platforms and unknown:
+            errors.append("%s: tag lạ %s — không phải nền tảng UC khai (%s), loại, hay mã AC/BR"
+                          % (where, " ".join("@" + t for t in unknown), " · ".join(platforms)))
+        for p in plats:
+            per_platform[p] += 1
+        if not refs:
+            errors.append("%s: không trỏ tới AC/BR nào — mọi kịch bản phải có nguồn trong PRD" % where)
+        for r in refs:
+            if r not in items:
+                errors.append("%s: @%s không có trong PRD" % (where, r))
+            elif not items[r]:
+                errors.append("%s: @%s đã bỏ trong PRD — sửa hoặc bỏ kịch bản này" % (where, r))
+        if "Then" not in sc["steps"]:
+            errors.append("%s: thiếu bước Then (kết quả quan sát được)" % where)
+        if sc["outline"] and sc["examples"] < 1:
+            errors.append("%s: Scenario Outline cần Examples có ít nhất 1 dòng dữ liệu" % where)
+        if not sc["outline"] and sc["examples"] >= 0:
+            errors.append("%s: có Examples thì phải là Scenario Outline" % where)
+    covered = set()
+    for f in glob.glob(os.path.join(os.path.dirname(os.path.abspath(feature)), "*.feature")):
+        for sc in parse_feature(read(f))[0]:
+            covered.update(t for t in sc["tags"] if ITEM_CODE.fullmatch(t))
+    missing = [c for c in own if c not in covered]
+    if missing:
+        errors.append("AC/BR của %s chưa có kịch bản nào: %s" % (uc, ", ".join(missing)))
+    pv = prd_version(ptext)
+    if pv and head.get("prd_version") and pv != head.get("prd_version"):
+        warns.append("PRD đã ở v%s, BDD viết theo v%s — xem Lịch sử thay đổi của PRD, chạy `/bdd %s` để bù"
+                     % (pv, head.get("prd_version"), uc))
+    acs = [c for c in own if "-AC" in c]
+    stats = {"scenarios": len(scenarios), "removed": len(removed),
+             "ac": (len([c for c in acs if c in covered]), len(acs)),
+             "br": (len([c for c in own if "-BR" in c and c in covered]), len(own) - len(acs)),
+             "platforms": per_platform}
+    return errors, warns, stats
+
+
+def cmd_bddcheck(feature, prd=None):
+    errors, warns, st = bdd_report(feature, prd)
+    if st:
+        print("%s: %d kịch bản (%d đã bỏ) · AC %d/%d · BR %d/%d · %s" % (
+            uc_of(feature), st["scenarios"], st["removed"], st["ac"][0], st["ac"][1], st["br"][0], st["br"][1],
+            " · ".join("%s %d" % kv for kv in st["platforms"].items()) or "chưa khai nền tảng"), flush=True)
+        ptext = read(prd or prd_of(feature))
+        todo = [u for u in re.findall(r"^###\s+(UC-\d{3})(?![\d-])", ptext, re.M)
+                if not os.path.isfile(os.path.join(os.path.dirname(os.path.abspath(feature)), u + ".feature"))]
+        print("UC chưa có BDD trong PRD này: " + (", ".join(todo) or "không còn"), flush=True)
+    for w in warns:
+        print("⚠ " + w, flush=True)
+    if errors:
+        fail("\n  - ".join([""] + errors))
+    print("đủ — khuôn, tag và độ phủ AC/BR đều đạt")
+
+
+def guard_bdd(path, block):
+    """BDD chỉ được duyệt khi bddcheck sạch, PRD đang approved và BDD viết đúng version PRD hiện tại."""
+    errors, _, _ = bdd_report(path)
+    if errors:
+        fail("không đặt được status=approved: `bddcheck` còn lỗi:\n  - " + "\n  - ".join(errors))
+    ptext = read(prd_of(path))
+    ps = re.search(r"^status:\s*(\S+)", ptext, re.M)
+    if not ps or ps.group(1) != "approved":
+        fail("không đặt được status=approved: PRD chưa approved. Duyệt PRD trước.")
+    bv = re.search(r"^prd_version:\s*(\S+)", block, re.M)
+    if not bv or bv.group(1) != prd_version(ptext):
+        fail("không đặt được status=approved: BDD viết theo PRD v%s, PRD đang ở v%s. Chạy `/bdd <UC>` để bù trước."
+             % (bv.group(1) if bv else "?", prd_version(ptext)))
+
+
+def cmd_where(specs_dir, ucs):
+    if len(ucs) != 1:
+        fail("cách dùng: where <thư mục specs> UC-001", 2)
+    pat = re.compile(r"^###\s+(?:~~)?%s(?![\d-])" % re.escape(ucs[0]), re.M)
+    hits = [p for p in glob.glob(os.path.join(specs_dir, "**", "prd.md"), recursive=True) if pat.search(read(p))]
+    if len(hits) != 1:
+        fail("%s có trong %d PRD (cần đúng 1)%s" % (ucs[0], len(hits), (": " + ", ".join(hits)) if hits else ""))
+    print(hits[0].replace("\\", "/"))
+
+
+def cmd_context(path, ucs):
+    """Phần PRD cần để viết BDD của một UC — thay cho đọc cả PRD."""
+    if len(ucs) != 1:
+        fail("cách dùng: context <prd> UC-001", 2)
+    uc = ucs[0]
+    text = read(path)
+    lines = text.split("\n")
+    span = uc_span(lines, uc)
+    if not span:
+        fail("không có %s trong %s" % (uc, path))
+    mention = re.compile(r"%s(?![\d-])" % re.escape(uc))
+    out = ["# PRD %s — v%s · status %s" % (path, prd_version(text), (re.search(r"^status:\s*(\S+)", text, re.M) or [None, "?"])[1])]
+    out.append(section_text(text, "overview") or "(PRD chưa có mục Tổng quan)")
+    flow = (section_text(text, "userflow") or "").split("\n")
+    rows = [l for l in flow if l.startswith("| J") and mention.search(l)]
+    if rows:
+        out += ["", "## User flow — các hành trình có " + uc, "| Mã | Hành trình | Actor | Đi qua UC | Điểm vào | Điểm ra |"] + rows
+        blocks = [i for i, l in enumerate(flow) if re.match(r"^### J\d+", l)]
+        for n, i in enumerate(blocks):
+            end = blocks[n + 1] if n + 1 < len(blocks) else len(flow)
+            if mention.search("\n".join(flow[i:end])):
+                out += [""] + [l for l in flow[i:end]]
+    screens = (section_text(text, "screens") or "").split("\n")
+    srows = [l for l in screens if l.startswith("|") and mention.search(l)]
+    if srows:
+        out += ["", "## Màn hình có " + uc, "| Màn hình | Thành phần chính | Hành động → kết quả | UC |"] + srows
+    block = lines[span[0]:span[1]]
+    out += [""] + block
+    body = "\n".join(block)
+    foreign = sorted({c for c in ITEM_CODE.findall(body) if not c.startswith(uc + "-")})
+    ucs_ref = sorted({u for u in re.findall(r"UC-\d{3}(?![\d-])", body) if u != uc})
+    if foreign or ucs_ref:
+        out += ["", "## Mục của UC khác mà %s trỏ tới" % uc]
+        for u in ucs_ref:
+            s = uc_span(lines, u)
+            if s:
+                out.append(lines[s[0]])
+        for c in foreign:
+            hits = find_item(lines, c)
+            out.append(lines[hits[0]] if hits else "(không tìm thấy %s trong PRD)" % c)
+    print("\n".join(out).rstrip())
+
+
+def used_sc(text, uc):
+    return sorted({int(m.group(3)) for m in SC_ANY.finditer(text) if m.group(2) == uc[3:]})
+
+
+def cmd_next_sc(path):
+    uc = uc_of(path)
+    nums = used_sc(read(path), uc) if os.path.isfile(path) else []
+    print("%s-SC%02d" % (uc, max(nums, default=0) + 1))
+
+
+def scenario_blocks(lines):
+    """[(mã, đầu, cuối)] — khối gồm tag, comment 🤖/✅ ngay trên, dòng Scenario, các bước, Examples."""
+    starts = []
+    for i, l in enumerate(lines):
+        if SCENARIO_LINE.match(l):
+            s = i
+            while s > 0 and (lines[s - 1].strip().startswith("@") or MARK_COMMENT.match(lines[s - 1])):
+                s -= 1
+            ids = SC_TAG.findall("\n".join(lines[s:i]))
+            starts.append((ids[0] if len(ids) == 1 else None, s))
+    out = []
+    for n, (sid, s) in enumerate(starts):
+        limit = starts[n + 1][1] if n + 1 < len(starts) else len(lines)
+        e = next((j for j in range(s + 1, limit) if GROUP_LINE.match(lines[j]) or REMOVED_SC.match(lines[j])), limit)
+        while e > s and not lines[e - 1].strip():
+            e -= 1
+        out.append((sid, s, e))
+    return out
+
+
+def find_block(lines, sid):
+    hits = [b for b in scenario_blocks(lines) if b[0] == sid]
+    if len(hits) != 1:
+        fail("kịch bản %s khớp %d khối (cần đúng 1). Dùng `scenario <file> %s` để xem lại." % (sid, len(hits), sid))
+    return hits[0]
+
+
+def cmd_scenario(path, codes):
+    """Mã kịch bản → đúng khối đó. Mã AC/BR → mọi kịch bản gắn tag mã đó."""
+    if not codes:
+        fail("cách dùng: scenario <feature> UC-001-SC03 | UC-001-BR04 […]", 2)
+    lines = read(path).split("\n")
+    shown = set()
+    for code in codes:
+        if ITEM_CODE.fullmatch(code):
+            tag = re.compile(r"@%s(?![\w-])" % re.escape(code))
+            blocks = [b for b in scenario_blocks(lines) if tag.search("\n".join(lines[b[1]:b[2]]))]
+            if not blocks:
+                print("(không có kịch bản nào gắn @%s)\n" % code)
+        else:
+            blocks = [find_block(lines, code)]
+        for _, s, e in blocks:
+            if s not in shown:
+                shown.add(s)
+                print("\n".join(lines[s:e]))
+                print()
+
+
+def cmd_sc(path):
+    """stdin = JSON: {"id", "new"} thay cả khối · {"after": mã | "end", "new"} thêm · {"remove", "version"} bỏ."""
+    try:
+        ops = json.loads(stdin_text())
+    except json.JSONDecodeError as e:
+        fail("stdin không phải JSON hợp lệ: " + str(e), 2)
+    if not isinstance(ops, list) or not ops:
+        fail('stdin phải là danh sách [{"id"|"after"|"remove": …}]', 2)
+    uc = uc_of(path)
+    lines = read(path).split("\n")
+    for n, op in enumerate(ops, 1):
+        keys = [k for k in ("id", "after", "remove") if k in op]
+        if len(keys) != 1:
+            fail("thao tác #%d phải có đúng một trong `id` (thay), `after` (thêm sau), `remove` (bỏ)" % n, 2)
+        if "remove" in op:
+            if not VERSION.match(str(op.get("version", ""))):
+                fail("thao tác #%d: bỏ kịch bản cần `version` mới của file BDD, ví dụ \"1.1\"" % n, 2)
+            sid = op["remove"]
+            _, s, e = find_block(lines, sid)
+            title = next((SCENARIO_LINE.match(l).group(2) for l in lines[s:e] if SCENARIO_LINE.match(l)), "")
+            lines[s:e] = ["  # Đã bỏ (v%s) @%s — %s" % (op["version"], sid, title.strip())]
+            continue
+        new = op.get("new")
+        if not isinstance(new, str) or not new.strip():
+            fail("thao tác #%d thiếu `new`" % n, 2)
+        new_lines = new.rstrip("\n").split("\n")
+        ids = SC_TAG.findall(new)
+        if sum(1 for l in new_lines if SCENARIO_LINE.match(l)) != 1 or len(ids) != 1:
+            fail("thao tác #%d: `new` phải là đúng một kịch bản, mang đúng một mã @%s-SCnn" % (n, uc), 2)
+        if "id" in op:
+            if ids[0] != op["id"]:
+                fail("thao tác #%d: kịch bản mới phải giữ mã %s (mã không bao giờ đổi)" % (n, op["id"]))
+            _, s, e = find_block(lines, op["id"])
+            lines[s:e] = new_lines
+        else:
+            if not ids[0].startswith(uc + "-"):
+                fail("thao tác #%d: mã %s không thuộc %s" % (n, ids[0], uc))
+            if int(SC_ANY.match(ids[0]).group(3)) in used_sc("\n".join(lines), uc):
+                fail("thao tác #%d: mã %s đã dùng (kể cả mã đã bỏ) — lấy `next-sc`" % (n, ids[0]))
+            if op["after"] == "end":
+                at = len(lines)
+                while at > 0 and not lines[at - 1].strip():
+                    at -= 1
+            else:
+                at = find_block(lines, op["after"])[2]
+            lines[at:at] = [""] + new_lines
+    out = "\n".join(lines)
+    if not out.endswith("\n"):
+        out += "\n"
+    write(path, out)
+    print("đã áp %d thao tác theo mã kịch bản trong %s" % (len(ops), path))
 
 
 PENDING, CONFIRMED = "\U0001F916", "✅"
@@ -528,7 +1096,8 @@ def main(argv):
     if argv[:1] == ["--check"]:
         print("ok — Python %s" % sys.version.split()[0])
         return
-    if len(argv) < 2 or argv[0] not in ("create", "edit", "set", "pending", "confirm", "next-uc", "coverage", "section", "upgrade", "flowcheck"):
+    if len(argv) < 2 or argv[0] not in ("create", "edit", "set", "pending", "confirm", "next-uc", "coverage", "section", "upgrade", "flowcheck", "item", "uc", "finding", "decide",
+                                            "where", "context", "next-sc", "scenario", "sc", "bddcheck"):
         fail(__doc__.split("Cách dùng")[1], 2)
     cmd, path, rest = argv[0], argv[1], argv[2:]
     if cmd == "create":
@@ -552,8 +1121,30 @@ def main(argv):
         cmd_upgrade(path)
     elif cmd == "flowcheck":
         cmd_flowcheck(path)
+    elif cmd == "item":
+        cmd_item(path)
+    elif cmd == "uc":
+        cmd_uc(path, rest)
+    elif cmd == "finding":
+        cmd_finding(path, rest)
+    elif cmd == "decide":
+        cmd_decide(path)
     elif cmd == "next-uc":
         cmd_next_uc(path)
+    elif cmd == "where":
+        cmd_where(path, rest)
+    elif cmd == "context":
+        cmd_context(path, rest)
+    elif cmd == "next-sc":
+        cmd_next_sc(path)
+    elif cmd == "scenario":
+        cmd_scenario(path, rest)
+    elif cmd == "sc":
+        cmd_sc(path)
+    elif cmd == "bddcheck":
+        if len(rest) > 1:
+            fail("cách dùng: bddcheck <feature> [prd]", 2)
+        cmd_bddcheck(path, rest[0] if rest else None)
     elif cmd == "coverage":
         if len(rest) != 1:
             fail("cách dùng: coverage <epic> <prd>", 2)