CASAN/casan-next-plans/CASAN_PLAN_01_RESTRUCTURE.md

KẾ HOẠCH 01 — Tái cấu trúc thư mục (Phase 0→6) & tách package harness

Status 2026-07-06: 📋 chưa bắt đầu (task-level). Đây là nền cho Plan-06 (onboard dự án 2) và Plan-12 (Domain Pack SDK): chỉ khi core harness được tách thành package độc lập, không lẫn domain OKR, thì mới chứng minh được "reuse thật". Rủi ro cao (đụng nhiều path) → làm trên nhánh riêng, giữ 218/0 core harness xuyên suốt.

Nhãn trạng thái dùng chung: xem legend ở CASAN_BACKLOG_STATUS.md. Phụ thuộc: không phụ thuộc plan khác để bắt đầu; chặn 06 và 12.

Bối cảnh code hiện tại

• Core harness (gate H1→H7) nằm ở .specify/scripts/bash/, .specify/security/, .specify/governance/, .specify/agentops/, .specify/level5/; tests ở .specify/tests/.
• Domain OKR (golden-runs, redteam-corpus, input, requirement/architecture) hiện lẫn trong cùng cây thư mục dự án, chưa tách rõ packages/ (harness) vs apps/<project>/domain/ (dữ liệu domain).
• project-registry.json đã có khái niệm project, nhưng ranh giới "package vs app" chưa được phản ánh ở tầng thư mục.

Nguyên tắc

• Không đổi hành vi gate: tái cấu trúc là dời path + cập nhật tham chiếu, không sửa logic H1→H7. Sau mỗi bước: full harness vẫn 218/0.
• Tách package vs domain: packages/casan-harness/ (gate, script, test khung) tuyệt đối không chứa dữ liệu domain; apps/<project>/domain/ chứa golden/corpus/input theo dự án.
• Một biến gốc đường dẫn: mọi script trỏ tới harness qua một biến/entrypoint duy nhất (ví dụ CASAN_HARNESS_ROOT) thay vì hardcode .specify/... rải rác.
• Làm trên nhánh riêng + freeze bản demo: không để restructure làm vỡ bản đang trình bày.
• Đổi từng Phase, chạy test giữa mỗi Phase, không dời tất cả một lần.

Cấu trúc đích (Phase 0→6)

flowchart TD
    ROOT["repo root"]
    ROOT --> PKG["packages/casan-harness/<br/>(gate H1→H7 + tests khung)"]
    ROOT --> APPS["apps/"]
    APPS --> OKR["apps/okr/<br/>domain OKR (golden/corpus/input)"]
    APPS --> X["apps/&lt;project-2&gt;/<br/>domain khác (Plan-06)"]
    ROOT --> REG["project-registry.json"]
    PKG --> REG
    OKR --> REG
    X --> REG
    style PKG fill:#d0e8ff,stroke:#2c3e91,stroke-width:2px
    style REG fill:#fff3cd,stroke:#8a6d3b,stroke-width:2px

Tasks

Task	Việc	File/Đối tượng	Verify	Done khi
1.1	Kiểm kê mọi tham chiếu hardcode .specify/... trong script/test	toàn repo	có danh sách đầy đủ path phụ thuộc	inventory xong
1.2	Định nghĩa biến gốc CASAN_HARNESS_ROOT + entrypoint duy nhất	bin/casan, model-router.sh	script trỏ qua biến, không hardcode	biến áp dụng
1.3	Phase 0: tạo packages/casan-harness/ (skeleton), chưa dời	mới	thư mục tồn tại, chưa đổi hành vi	skeleton sẵn
1.4	Phase 1–2: dời gate H1→H4 (security/context/tool/validation) sang package	.specify/** → packages/**	full harness 218/0 sau khi dời	H1–H4 đã dời
1.5	Phase 3–4: dời H5/H6/H7 (governance/agentops/orchestration)	.specify/** → packages/**	full harness 218/0	H5–H7 đã dời
1.6	Phase 5: tách domain OKR sang apps/okr/domain/	golden/corpus/input	pipeline OKR chạy trọn, drift/H3 hoạt động	domain tách bạch
1.7	Phase 6: cập nhật project-registry.json + verify-harness-reuse.sh theo cấu trúc mới	registry, script	registry hợp lệ, reuse-check chạy	registry đồng bộ
1.8	Cập nhật CI/CD (Plan-05) & Docker infra lab theo path mới	.gitea/**, infra/**	CI gate xanh với path mới	CI thích ứng
1.9	Ghi "nợ kỹ thuật phải sửa gate" (nếu buộc phải) làm đầu vào cho Plan-06/12	mới notes	có danh sách gap	rút kinh nghiệm

Tiêu chí HOÀN THÀNH

• packages/casan-harness/ không chứa dữ liệu domain; apps/okr/domain/ chứa toàn bộ golden/corpus/input OKR.
• Mọi script trỏ harness qua CASAN_HARNESS_ROOT/entrypoint, không còn hardcode .specify/... rải rác.
• Full harness 218/0 giữ nguyên sau mỗi Phase; local-prod infra lab vẫn 2/0.
• CI/CD (Plan-05) xanh trên cấu trúc mới.
• verify-harness-reuse.sh chạy đúng trên cấu trúc mới → sẵn sàng cho Plan-06.

---

Liên quan: CASAN_PLAN_00_INDEX.md (mục lục) · Plan-05 (CI phải thích ứng path) · Plan-06/12 (phụ thuộc plan này).