optimize docs

2026-07-23 23:30:43 +07:00
parent a6c3a5d02f
commit 2ca1eabca9
7 changed files with 390 additions and 201 deletions
@@ -69,6 +69,9 @@ casan level set 2                       # đổi level project (không cần ini
  `init` nhiều lần không nhân đôi hook.
 - **Guardrail:** `init` **từ chối** khi target chính là một CASAN source hub (để
  không tự chặn agent đang phát triển CASAN); dùng `--force` nếu thực sự cần.
+- Project cũ có vendored `packages/casan-harness` **không bị xem là source hub**:
+  init tự migrate sang hybrid, giữ nguyên harness/CI/scripts cũ để tương thích và
+  không yêu cầu `--force`.

 `--level 3` (platform) chỉ áp base L2 + nhắc rằng platform là service deploy riêng;
 `--level 4` (enterprise) bị từ chối (chưa ship).
@@ -100,6 +103,33 @@ Bootstrap `.casan/casan-hook.py` tự đọc `config.json`; developer không cò
 source `.casan/agentic.env` trước khi mở IDE. Mỗi invocation kiểm tra live hash
 của harness global so với `version.lock` trước khi chạy adapter.

+### Project đã có `.claude`, `.github`, agents, skills hoặc CASAN vendored
+
+Chỉ cần commit/backup trạng thái hiện tại, cài CASAN global rồi chạy init tại
+project root, kể cả khi đường dẫn có khoảng trắng:
+
+```bash
+cd '/path/to/Basic Design (Screen&Report)_v2.7'
+casan init --project basic-design-v27 --client claude,codex,vscode-copilot
+casan doctor
+```
+
+Quy tắc migration:
+
+- `.claude/agents`, `.claude/skills`, `.claude/commands`, `.github/**` và
+  workflow hiện hữu không bị xóa hoặc ghi đè.
+- CASAN chỉ merge handler của mình vào `.claude/settings.json` và
+  `.codex/hooks.json`; cấu hình/hook không thuộc CASAN được giữ nguyên.
+- Nếu có CASAN vendored cũ, `packages/casan-harness`, `bin/casan-chat`, CI và
+  evidence cũ được giữ lại. Chỉ xóa chúng sau khi CI/scripts/domain smoke đã
+  chuyển sang harness global.
+- Block legacy nằm đúng giữa marker
+  `CASAN_PROMPT_ENFORCEMENT_START/END` được nâng cấp tự động.
+- Prose legacy nằm ngoài marker không bị sửa âm thầm; `init` và `doctor` liệt kê
+  file cần review. Đặc biệt phải bỏ tuyên bố cũ rằng Claude/Codex direct chat
+  luôn nằm ngoài CASAN, vì Plan-20 project hooks đã thay đổi hành vi đó.
+- Codex vẫn cần `/hooks` trust; Copilot built-in vẫn cần explicit `@casan`.
+
 Sau `init`, developer gõ prompt bình thường trong client — trace H1→H7 + H6 theo
 Plan-20. Repo chỉ có mấy file config nhỏ; nâng cấp harness làm ở `$CASAN_HOME`.

@@ -3,8 +3,8 @@
 ## Outcome

 CASAN can create and govern multiple independent applications without embedding product knowledge
-in root `.github`, shared harness code, patch verification, or pipeline orchestration. OKR and
-Service Desk are consumers of the same versioned contract.
+in root `.github`, shared harness code, patch verification, or pipeline orchestration. Demo
+fixtures and Service Desk are consumers of the same versioned contract.

 ## Trust boundaries

@@ -70,6 +70,6 @@ update fails, the incomplete directory is removed and the project is not exposed
 ## Verification evidence

 Automated tests cover valid manifests, traversal rejection, command allowlisting, conflicting-file
-protection, idempotent scaffold/harness registration, generated NestJS/React build and tests, OKR
-compatibility, Service Desk isolation, source-generation review loops, and per-project patch
+protection, idempotent scaffold/harness registration, generated NestJS/React build and tests,
+demo-fixture compatibility, Service Desk isolation, source-generation review loops, and per-project patch
 verification command selection.
@@ -222,7 +222,7 @@ coding agent. Miễn command đi qua harness, evidence được ghi theo cùng c

 ## 7. Case 3 — dự án Service Desk thật đã có trong repository này

-Đây là bằng chứng CASAN không chỉ dùng được cho OKR:
+Đây là ví dụ một project consumer độc lập với các demo fixture:

 ```bash
 node --test apps/service-desk/test/ticket.test.mjs
@@ -237,7 +237,8 @@ bash packages/casan-harness/scripts/bash/verify-harness-reuse.sh
 ```

 Service Desk có source/test riêng và Domain Pack riêng. Nó dùng chung đúng một
-harness version với OKR. Không có gate nào được copy riêng cho Service Desk.
+harness version với các project khác. Không có gate nào được copy riêng cho
+Service Desk.

 ## 8. Case 4 — muốn model thực sự “xây dự án cho tôi”

@@ -1,7 +1,7 @@
 # CASAN Plan-21 — Hybrid Global Install + `casan init`

 > Ngày lập: 2026-07-23  
-> Trạng thái: **IMPLEMENTED + HARDENED — global install + selectable IDE init + pinned global bootstrap + VS Code `@casan` + merge-safe (60/60 hybrid acceptance)**
+> Trạng thái: **IMPLEMENTED + HARDENED — global install + selectable IDE init + pinned global bootstrap + VS Code `@casan` + merge-safe/vendored migration (66/66 hybrid acceptance)**
 > Liên quan: [Plan-20](CASAN_PLAN_20_AGENTIC_CLIENT_INTEGRATION.md) (adapter/hook là base phổ quát), [CASAN_INSTALL_HYBRID.md](../casan/CASAN_INSTALL_HYBRID.md)

 ## 1. Mục tiêu
@@ -42,7 +42,7 @@ harness global thao tác đúng trên state của dự án hiện tại.
 | Integrity hash primitive | `packages/casan-harness/scripts/python/harness_hash.py` |
 | `casan init` / `verify` | `packages/casan-devkit/casan-init.py` |
 | CLI wiring | `bin/casan` (`init`, `verify-harness`) |
-| Acceptance suite | `packages/casan-devkit/tests/hybrid-install-tests.sh` — **60/60 PASS** |
+| Acceptance suite | `packages/casan-devkit/tests/hybrid-install-tests.sh` — **66/66 PASS** |
 | Adoption doc | `docs/casan/CASAN_INSTALL_HYBRID.md` |

 ### Level selection (4 packaging levels) & safe adoption
@@ -65,6 +65,10 @@ harness global thao tác đúng trên state của dự án hiện tại.
  `@casan` Chat Participant. Built-in Copilot không bị claim là global-intercept.
 - **Source-hub guardrail:** `init` refuses to adopt a CASAN source hub into itself
  (would block the developing agent); `--force` overrides.
+- **Vendored migration:** a consumer repo containing an older
+  `packages/casan-harness` is distinguished from the product source hub,
+  migrated without `--force`, and retains its project-owned agents, skills,
+  prompts, workflows, scripts, evidence, and compatibility harness.

 ## 5. Definition of Done