@educa-corp/sdd-framework 0.3.0 → 0.4.2

package/bin/trace-schema.json

@@ -0,0 +1,692 @@
+{
+  "$comment": [
+    "NGUỒN-SỰ-THẬT MÁY ĐỌC cho contract trace của framework. bin/self-check.js đối chiếu",
+    "file này với commands/*.tmpl + steps/*.md mỗi lần `npm run build`, và FAIL build khi lệch.",
+    "",
+    "Vì sao tồn tại: 19/23 GAP trong GAPS.md là cùng một lỗi — contract được phát biểu lại",
+    "bằng prose ở nhiều lệnh rồi lệch nhau qua từng lần sửa. Ca thuần khiết nhất là",
+    "@trace.sc_version: 3 consumer, 0 producer, tồn tại qua nhiều version mà không lệnh nào,",
+    "không cổng nào, không test nào phát hiện. Rule R1 dưới đây bắt đúng lớp lỗi đó.",
+    "",
+    "ĐỔI CONTRACT: sửa file này TRƯỚC, rồi mới sửa lệnh. Build fail nếu lệnh lệch schema.",
+    "Bản dành cho người đọc: docs/04-reference/trace-schema.md (giữ đồng bộ với file này).",
+    "",
+    "Định dạng JSON chứ không YAML vì package.json có ZERO dependency (npx chạy không cần",
+    "install) — thêm js-yaml chỉ để đọc một file cấu hình build-time là không đáng."
+  ],
+  "actors": {
+    "$comment": "Tên logic → file nguồn. self-check tìm chuỗi field trong các file này.",
+    "generate-bdd": "commands/generate-bdd.tmpl",
+    "generate-code": "commands/generate-code.tmpl",
+    "generate-tech-docs": "commands/generate-tech-docs.tmpl",
+    "generate-prd": "commands/generate-prd.tmpl",
+    "generate-design-spec": "commands/generate-design-spec.tmpl",
+    "review-context": "commands/review-context.tmpl",
+    "review-tech-docs": "commands/review-tech-docs.tmpl",
+    "review-code": "commands/review-code.tmpl",
+    "validate-traces": "commands/validate-traces.tmpl",
+    "dev-gen-test": "commands/dev-gen-test.tmpl",
+    "dev-run-test": "commands/dev-run-test.tmpl",
+    "dev-smoke-test": "commands/dev-smoke-test.tmpl",
+    "qc-run-test": "commands/qc-run-test.tmpl",
+    "report-bug": "commands/report-bug.tmpl",
+    "propose-scenario": "commands/propose-scenario.tmpl",
+    "fix-bug": "commands/fix-bug.tmpl",
+    "refine-prd": "commands/refine-prd.tmpl",
+    "sync": "commands/sync.tmpl",
+    "setup-ai-first": "commands/setup-ai-first.tmpl",
+    "context-loader": "steps/context-loader.md",
+    "gate": "steps/gate.md",
+    "report-footer": "steps/report-footer.md",
+    "feature-template": "templates/feature.template",
+    "prd-template": "templates/prd.template.md",
+    "tech-design-template": "templates/tech-design.template.md"
+  },
+  "tags": [
+    {
+      "name": "@trace.sc_version",
+      "artifact": ".feature",
+      "scope": "scenario",
+      "shape": "semver-lite (1.0, 1.1)",
+      "written_by": [
+        "generate-bdd",
+        "feature-template"
+      ],
+      "bumped_by": [
+        "generate-bdd",
+        "review-context"
+      ],
+      "read_by": [
+        "generate-bdd",
+        "validate-traces",
+        "review-context"
+      ],
+      "why": "Tín hiệu DUY NHẤT cho DRIFT (spec_ver != gen_ver). Không có producer = DRIFT chết."
+    },
+    {
+      "name": "@trace.bdd_version",
+      "artifact": ".feature",
+      "scope": "file",
+      "shape": "semver-lite scalar",
+      "written_by": [
+        "generate-bdd",
+        "feature-template"
+      ],
+      "bumped_by": [
+        "generate-bdd",
+        "review-context"
+      ],
+      "read_by": [
+        "generate-bdd",
+        "generate-code",
+        "generate-tech-docs",
+        "validate-traces",
+        "review-tech-docs",
+        "review-context"
+      ],
+      "why": "Drift cấp file (Background/dataset/business-definition) mà sc_version không thấy."
+    },
+    {
+      "name": "@trace.bdd_versions",
+      "artifact": "tech-design.md",
+      "scope": "file",
+      "shape": "map theo platform (system=1.5, web=1.9)",
+      "written_by": [
+        "generate-tech-docs",
+        "tech-design-template"
+      ],
+      "read_by": [
+        "generate-code",
+        "validate-traces",
+        "review-tech-docs"
+      ],
+      "why": "Số NHIỀU, cố ý khác @trace.bdd_version (scalar) — cùng tên cho hai kiểu dữ liệu làm vỡ parser generic."
+    },
+    {
+      "name": "@trace.platform",
+      "artifact": ".feature",
+      "scope": "file",
+      "required": "always",
+      "values_from": "platform",
+      "written_by": [
+        "generate-bdd",
+        "feature-template"
+      ],
+      "read_by": [
+        "generate-code",
+        "generate-tech-docs",
+        "review-context",
+        "context-loader"
+      ],
+      "why": "Quyết BE/FE ở generate-code (cấm fallback platform_type) + tên sổ trace + lookup design-spec. Lưu ý: validate-traces và report-bug KHÔNG đọc tag này — chúng suy platform từ TÊN FILE .tsv ({UC-ID}-{platform}.tsv), nên không phải consumer của tag."
+    },
+    {
+      "name": "@trace.prd_version",
+      "artifact": ".feature + code",
+      "scope": "file + method",
+      "written_by": [
+        "generate-bdd",
+        "generate-code",
+        "feature-template"
+      ],
+      "read_by": [
+        "generate-bdd",
+        "validate-traces",
+        "review-context"
+      ],
+      "why": "Nguồn của PRD_DRIFT (validate-traces Step 4 so 3 tầng: PRD file, TSV, tag trong code)."
+    },
+    {
+      "name": "@trace.implements",
+      "artifact": "code",
+      "scope": "method",
+      "shape": "{UC-ID}-SC{N}",
+      "written_by": [
+        "generate-code",
+        "setup-ai-first"
+      ],
+      "read_by": [
+        "validate-traces",
+        "review-code",
+        "dev-gen-test",
+        "dev-smoke-test",
+        "fix-bug"
+      ],
+      "why": "Khoá chính của trace ở tầng code. Tra bằng khớp chuỗi CHÍNH XÁC → cấm trỏ thư mục."
+    },
+    {
+      "name": "@trace.source",
+      "artifact": "code",
+      "scope": "method",
+      "shape": "{specs_dir}/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature",
+      "written_by": [
+        "generate-code",
+        "setup-ai-first"
+      ],
+      "read_by": [
+        "review-code"
+      ],
+      "why": "Con trỏ ngược về spec. PHẢI gồm segment {platform}."
+    },
+    {
+      "name": "@trace.tech_doc_revision",
+      "artifact": "code",
+      "scope": "method",
+      "written_by": [
+        "generate-code"
+      ],
+      "read_by": [
+        "review-code"
+      ],
+      "why": "Ghi revision tech-doc mà method này được sinh theo. BẤT ĐỐI XỨNG ĐÃ BIẾT: validate-traces Step 5 tính TECHDOC_DRIFT từ cột TSV tech_doc_revision chứ không từ tag này (khác Step 4, có so tag @trace.prd_version trong code). Nên hiện chỉ review-code kiểm sự CÓ MẶT của nó. Muốn đối xứng thì Step 5 phải đọc thêm tag trong code."
+    },
+    {
+      "name": "@trace.verifies",
+      "artifact": "test",
+      "scope": "method",
+      "shape": "{UC-ID}-SC{N}",
+      "written_by": [
+        "dev-gen-test",
+        "qc-run-test",
+        "fix-bug"
+      ],
+      "read_by": [
+        "validate-traces",
+        "review-code",
+        "dev-run-test",
+        "qc-run-test"
+      ],
+      "why": "Khớp test → sc_id khi ghi test_count/dev_selftest/qc_status."
+    },
+    {
+      "name": "@trace.scenario",
+      "artifact": ".feature",
+      "scope": "scenario",
+      "shape": "{UC-ID}-SC{N}",
+      "written_by": [
+        "generate-bdd",
+        "propose-scenario",
+        "feature-template"
+      ],
+      "read_by": [
+        "generate-bdd",
+        "review-context"
+      ],
+      "why": "Sinh sc_id cho row TSV. Thiếu nó = scenario vô hình với toàn bộ coverage."
+    },
+    {
+      "name": "@trace.status",
+      "artifact": ".feature + tech-design.md",
+      "scope": "file",
+      "values_from": "approval_status",
+      "written_by": [
+        "feature-template",
+        "review-context",
+        "review-tech-docs",
+        "generate-tech-docs",
+        "tech-design-template"
+      ],
+      "read_by": [
+        "generate-code",
+        "validate-traces",
+        "review-tech-docs"
+      ],
+      "why": "Cổng duyệt: DS1 của generate-code, và uc_status sync từ đây."
+    },
+    {
+      "name": "@trace.revision",
+      "artifact": "tech-design.md",
+      "scope": "file",
+      "shape": "integer",
+      "written_by": [
+        "generate-tech-docs",
+        "review-tech-docs",
+        "tech-design-template"
+      ],
+      "read_by": [
+        "generate-code",
+        "validate-traces"
+      ],
+      "why": "Nguồn của tech_doc_revision + TECHDOC_DRIFT."
+    },
+    {
+      "name": "@trace.api_source",
+      "artifact": ".feature + tech-design.md",
+      "scope": "file",
+      "written_by": [
+        "generate-bdd",
+        "tech-design-template"
+      ],
+      "read_by": [
+        "review-tech-docs",
+        "review-context"
+      ],
+      "why": "existing → bỏ cổng T7 + skip System BDD Synthesis S1-S3."
+    },
+    {
+      "name": "@trace.stub",
+      "artifact": "code",
+      "scope": "method",
+      "written_by": [
+        "generate-code"
+      ],
+      "read_by": [
+        "validate-traces",
+        "review-code"
+      ],
+      "why": "Method trắng nội-feature. Nguồn của STUB_UNRESOLVED."
+    },
+    {
+      "name": "@trace.seam_pending",
+      "artifact": "code",
+      "scope": "class",
+      "written_by": [
+        "generate-code"
+      ],
+      "read_by": [
+        "validate-traces",
+        "review-code"
+      ],
+      "why": "Port cross-UC chưa có hàng thật. Nguồn của SEAM_UNWIRED."
+    },
+    {
+      "name": "@trace.fixes",
+      "artifact": "code",
+      "scope": "method",
+      "written_by": [
+        "fix-bug"
+      ],
+      "read_by": [],
+      "allow_no_reader": "Nhãn cho người đọc code, không có consumer tự động."
+    }
+  ],
+  "tsv_columns": [
+    {
+      "n": 1,
+      "name": "sc_id",
+      "written_by": [
+        "generate-bdd"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-code",
+        "dev-gen-test",
+        "dev-run-test",
+        "qc-run-test",
+        "report-bug",
+        "fix-bug"
+      ]
+    },
+    {
+      "n": 2,
+      "name": "sc_title",
+      "written_by": [
+        "generate-bdd"
+      ],
+      "read_by": [
+        "validate-traces"
+      ]
+    },
+    {
+      "n": 3,
+      "name": "spec_ver",
+      "written_by": [
+        "generate-bdd",
+        "validate-traces",
+        "review-context"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-code"
+      ]
+    },
+    {
+      "n": 4,
+      "name": "gen_ver",
+      "written_by": [
+        "generate-code"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-bdd"
+      ]
+    },
+    {
+      "n": 5,
+      "name": "implemented_by",
+      "written_by": [
+        "generate-code"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-bdd"
+      ]
+    },
+    {
+      "n": 6,
+      "name": "test_count",
+      "written_by": [
+        "dev-gen-test",
+        "fix-bug"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-bdd"
+      ]
+    },
+    {
+      "n": 7,
+      "name": "test_classes",
+      "written_by": [
+        "dev-gen-test",
+        "fix-bug"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-bdd"
+      ]
+    },
+    {
+      "n": 8,
+      "name": "dev_selftest",
+      "written_by": [
+        "dev-run-test",
+        "dev-gen-test",
+        "generate-code",
+        "fix-bug"
+      ],
+      "read_by": [
+        "validate-traces",
+        "qc-run-test"
+      ]
+    },
+    {
+      "n": 9,
+      "name": "dev_selftest_at",
+      "written_by": [
+        "dev-run-test",
+        "generate-code",
+        "fix-bug"
+      ],
+      "read_by": [
+        "validate-traces",
+        "qc-run-test"
+      ]
+    },
+    {
+      "n": 10,
+      "name": "qc_status",
+      "written_by": [
+        "qc-run-test"
+      ],
+      "read_by": [
+        "validate-traces",
+        "dev-run-test",
+        "generate-code",
+        "report-bug",
+        "fix-bug"
+      ]
+    },
+    {
+      "n": 11,
+      "name": "qc_run_at",
+      "written_by": [
+        "qc-run-test"
+      ],
+      "read_by": [
+        "validate-traces",
+        "dev-run-test",
+        "generate-code"
+      ]
+    },
+    {
+      "n": 12,
+      "name": "qc_owner",
+      "written_by": [
+        "qc-run-test",
+        "report-bug"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-code",
+        "fix-bug"
+      ]
+    },
+    {
+      "n": 13,
+      "name": "qc_blocked_by",
+      "written_by": [
+        "qc-run-test",
+        "report-bug"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-code",
+        "qc-run-test"
+      ]
+    },
+    {
+      "n": 14,
+      "name": "prd_version",
+      "written_by": [
+        "generate-bdd"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-code"
+      ]
+    },
+    {
+      "n": 15,
+      "name": "bdd_version",
+      "written_by": [
+        "generate-bdd",
+        "review-context"
+      ],
+      "read_by": [
+        "validate-traces"
+      ]
+    },
+    {
+      "n": 16,
+      "name": "tech_doc_revision",
+      "written_by": [
+        "generate-code",
+        "review-tech-docs"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-bdd"
+      ]
+    },
+    {
+      "n": 17,
+      "name": "fe_tech_doc_revision",
+      "written_by": [
+        "generate-code"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-bdd",
+        "review-tech-docs"
+      ]
+    },
+    {
+      "n": 18,
+      "name": "prd_status",
+      "written_by": [
+        "generate-bdd",
+        "validate-traces"
+      ],
+      "read_by": [
+        "validate-traces"
+      ]
+    },
+    {
+      "n": 19,
+      "name": "uc_status",
+      "written_by": [
+        "generate-bdd",
+        "validate-traces",
+        "review-context"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-code"
+      ]
+    },
+    {
+      "n": 20,
+      "name": "fe_phase",
+      "written_by": [
+        "generate-code",
+        "generate-bdd"
+      ],
+      "read_by": [
+        "validate-traces"
+      ]
+    },
+    {
+      "n": 21,
+      "name": "status",
+      "written_by": [
+        "validate-traces",
+        "generate-bdd"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-code",
+        "dev-run-test",
+        "qc-run-test"
+      ]
+    },
+    {
+      "n": 22,
+      "name": "last_updated",
+      "written_by": [
+        "generate-bdd",
+        "generate-code",
+        "dev-gen-test",
+        "dev-run-test",
+        "qc-run-test",
+        "review-context",
+        "review-tech-docs",
+        "fix-bug"
+      ],
+      "read_by": [
+        "validate-traces"
+      ]
+    }
+  ],
+  "vocabularies": {
+    "$comment": "Mọi giá trị phải xuất hiện ở ít nhất một actor — giá trị chết là dấu hiệu contract lệch.",
+    "trace_status": {
+      "values": [
+        "OK",
+        "DRIFT",
+        "GAP",
+        "UNTRACKED",
+        "ORPHANED"
+      ],
+      "column": "status"
+    },
+    "platform": {
+      "values": [
+        "web",
+        "app",
+        "system"
+      ]
+    },
+    "approval_status": {
+      "values": [
+        "draft",
+        "in-review",
+        "approved"
+      ]
+    },
+    "fe_phase": {
+      "values": [
+        "ui",
+        "integrated"
+      ],
+      "column": "fe_phase"
+    },
+    "seam_status": {
+      "values": [
+        "PENDING",
+        "READY",
+        "RESOLVED"
+      ]
+    },
+    "audit_flags": {
+      "values": [
+        "PRD_DRIFT",
+        "BDD_DRIFT",
+        "TECHDOC_DRIFT",
+        "FE_TECHDOC_DRIFT",
+        "TECHDOC_STALE_VS_BDD",
+        "TRACE_ORPHAN",
+        "SEAM_UNWIRED",
+        "STUB_UNRESOLVED",
+        "SEAM_PENDING",
+        "STUB_PENDING"
+      ]
+    }
+  },
+  "path_keys": {
+    "$comment": "Key phải có trong templates/project-context.yaml VÀ được dùng bởi ít nhất một actor. Key khai mà không ai dùng = key chết (GAPS.md G17).",
+    "config_file": "templates/project-context.yaml",
+    "ignore_unused": [
+      "specs_dir",
+      "src_dir",
+      "trace_dir",
+      "tech_docs_dir",
+      "lessons_file"
+    ]
+  },
+  "forbidden_patterns": [
+    {
+      "pattern": "bdd/{UC-ID}.feature",
+      "reason": "@trace.source thiếu segment {platform}. Layout thật: bdd/{platform}/{UC-ID}-{slug}.feature",
+      "gap": "G8"
+    },
+    {
+      "pattern": "{UC-ID}*-tech-design",
+      "reason": "Glob không bao giờ khớp: tech-doc là doc GỘP cấp PRD, tên mang {TICKET-ID} chứ không mang {UC-ID}",
+      "gap": "G10",
+      "except": {
+        "steps/gate.md": "Trích dẫn pattern trong cảnh báo tại chỗ: \"Đừng glob {UC-ID}*-tech-design*.md — nó nở thành ... và không bao giờ khớp\""
+      }
+    },
+    {
+      "pattern": "{prd-slug}/{UC-ID}.tsv",
+      "reason": "Tên sổ trace thiếu -{platform}. Một sổ cho mỗi UC × platform",
+      "gap": "G18"
+    },
+    {
+      "pattern": "claude-opus-4",
+      "reason": "Hardcode version model — dùng \"model Opus mới nhất\" để không phải sửa framework mỗi lần lên model",
+      "gap": "G21"
+    },
+    {
+      "pattern": "{paths.feature_template}",
+      "reason": "Key chết: template được {{include}} nướng cứng lúc build, lệnh không đọc path template lúc chạy",
+      "gap": "G17"
+    },
+    {
+      "pattern": "{paths.prd_template}",
+      "reason": "Key chết — xem G9/G17",
+      "gap": "G17"
+    },
+    {
+      "pattern": "{paths.trace_report}",
+      "reason": "Key chết và trỏ sai: report thật là {trace_dir}/trace-report.json",
+      "gap": "G17"
+    },
+    {
+      "pattern": "{paths.templates_dir}",
+      "reason": "Key chết — xem G17",
+      "gap": "G17"
+    }
+  ]
+}