nccgs 1.1.0 → 1.3.0

package/UPGRADING.md

@@ -2,6 +2,43 @@
 
 Always inspect a dry run and preserve project policy.
 
+## 1.3.0: executable gates and focused agent activation
+
+Read the [1.3 guide](docs/NCCGS-1.3.md). Routing now comes from
+`.claude/nccgs/pipeline.json`; generated files are checked for drift. Only ten core
+agents are active by default; 35 additional roles are available through `agents
+--enable`. Project customizations are preserved for explicit migration review.
+
+Astra must map existing checks, closure artifacts and manual decisions into
+`.nccgs/gates.json`, referencing the current project policy hash. A 1.2 policy with
+embedded `profile_contracts` needs migration to the canonical `pipeline_policy`
+reference. Do not discard project requirements during this migration.
+
+Task records now enforce implementation -> independent review -> report -> Astra
+check -> Product Owner acceptance. Missing observed effort blocks the gate; requested
+settings alone do not prove runtime behavior. Each workflow loads only its selected
+Astra or legacy branch. The legacy instructions later in this document apply only
+to explicitly selected legacy profiles.
+
+## Astra / Opus / Fable routing
+
+New installations default to `astra-claude`: Astra plans and owns documents;
+Opus 5.5/xhigh implements; Fable/high reviews; Claude hands the reviewed report to
+Astra; Astra checks it; the Product Owner accepts before DONE. See the
+[handoff protocol](.claude/nccgs/protocols/astra-claude.md).
+
+Existing projects keep their profile unless explicitly changed. In each Unity
+project, run `npx nccgs@latest update --model-profile astra-claude --dry-run`, inspect
+it, then remove `--dry-run`. Source checkouts can use `node <NCCGS>/scripts/cli.mjs`
+instead of `npx nccgs@latest`. Publishing alone does not update installed projects.
+Use `install` instead of `update` for a new installation. Require Claude Code
+2.1.280+ and access to Opus 5.5 and Fable. Review any
+preserved agent/settings overrides so the observed model and effort match policy.
+The configurator preserves unrelated shared settings and backs up replacements;
+existing sessions and local/environment overrides still require a runtime check.
+
+## Earlier update behavior
+
 ```powershell
 cd "D:\path\to\UnityProject"
 npx nccgs@latest update --dry-run
@@ -9,10 +46,23 @@ npx nccgs@latest update
 npx nccgs@latest doctor
 ```
 
-Version 1.1 adds hash-aware, idempotent updates. Managed files that still match the
-previous install state update automatically. Project-modified framework files stop
-the update and require review; `--force` backs them up before replacement. Existing
-`.nccgs/project.yaml` remains project-owned and is never blindly overwritten.
+Version 1.1.1 makes updates hash-aware, line-ending-aware, and override-aware.
+Managed files that still match the previous install state update automatically;
+CRLF/LF conversion alone is accepted as the same text. Genuine project-modified or
+intentionally missing framework files are preserved and recorded in
+`.nccgs/framework-overrides.json` as `pending_review`. The rest of the framework is
+updated normally, so `--force` is no longer required to get past intentional local
+customizations. Existing `.nccgs/project.yaml` remains project-owned and is never
+blindly overwritten.
+
+When pending overrides are reported, open a fresh Claude Code session and run
+`/migrate-project` once. The workflow reviews and rebases each override, migrates the
+project policy when needed, and records approval of the final hashes. A direct
+`doctor` remains red until pending override review is complete. Use `--force` only
+when you intentionally want to back up and discard every detected customization.
+
+NCCGS 1.1.1 also names its specialized review command `/nccgs-code-review` to avoid
+colliding with Claude Code's built-in `/code-review` command.
 
 When the installer reports that project migration is required, open a new Claude
 Code session and run one command:

package/VERSION

@@ -1 +1 @@
-1.1.0
+1.3.0

package/docs/ARCHITECTURE.md

@@ -11,8 +11,8 @@ distinct decision surface, failure mode, artifact, or verification lens.
 1. **Kernel** — constitution, authority, project policy, ownership, state, closure.
 2. **Router** — domain/risk classification, model profile, context packet, execution
    graph and write ownership.
-3. **Studio roles** — 45 leadership, lead, specialist, Unity, quality, and release
-   agents with shared handoff contracts.
+3. **Studio roles** — ten active core agents, with 35 optional roles in a 45-agent
+   library. Activation choices survive updates; customized files are preserved.
 4. **Workflow modules** — 36 composable skills with eight user-facing entrypoints.
 5. **Unity operations** — unmodified official Unity Skills and Unity CLI/Pipeline.
 6. **Automation** — Node hooks for recovery, audit and safety.
@@ -20,7 +20,9 @@ distinct decision surface, failure mode, artifact, or verification lens.
 
 ## Bounded orchestration
 
-The primary Claude Code session is the sole orchestrator. It constructs a DAG,
+The primary Claude Code session is the sole Claude subagent orchestrator. Under the
+default astra-claude profile, Astra owns planning/documents outside that session;
+Claude executes within Astra's plan. It constructs an implementation DAG,
 selects the smallest complete role set, passes a context packet, assigns one writer
 per path, and merges handoffs. Studio agents do not recursively delegate.
 
@@ -40,14 +42,16 @@ require reconstructing truth from chat history.
 
 ## Model architecture
 
-Each catalog role has a capability class: lightweight, standard, deep, or leadership.
-An installation profile compiles that class into agent frontmatter. The package
-defaults to quality but supports balanced and inherit profiles without duplicating
-agent prompts.
+Each catalog role has a capability class: lightweight, standard, deep, leadership,
+or review. `pipeline.json` is the routing source; the compiler generates catalog
+routes and agent frontmatter, and validation rejects drift. The default
+astra-claude profile uses claude-opus-5-5/xhigh for Claude work and fable/high for
+independent review. It also configures the main project session. Legacy quality,
+balanced, and inherit profiles remain available without duplicating agent prompts.
 
-The router selects role/domain first and model second. Risk escalation is evidence
-based. Project policy records fallback behavior so model availability failure does
-not become an unexplained task blocker.
+Legacy profiles support policy-directed fallback. The astra-claude profile instead
+blocks a required stage when its model/effort cannot be confirmed; it never labels
+an inherited model's output as Fable review or Opus 5.5 implementation.
 
 ## Unity boundary
 
@@ -57,9 +61,22 @@ SHA-256 manifest makes upstream modifications visible.
 
 ## Evidence and closure
 
-Implementation and verification are separate work nodes. STANDARD work normally has
-independent verification; CONTROLLED work adds adversarial review. Evidence is mapped
-to requirements and source revision.
+For astra-claude, every code change follows Opus implementation -> Fable review ->
+report to Astra -> Astra check -> explicit Product Owner acceptance. Opus fixes
+findings and Fable re-reviews each changed snapshot. These gates apply to FAST and
+lean work as well. `task.mjs` enforces this sequence using snapshot hashes, immutable
+artifact references, runtime observations and explicit external decisions. A changed
+snapshot invalidates previous review/acceptance. Re-recording an earlier stage clears
+downstream stages while retaining history. Hooks supplement the task gate; they are
+not a security sandbox. There is no automatic cross-app transport.
+
+Requested model settings and observed runtime values are separate fields. Native
+events can report the resolved model and fallback history; absent observed effort
+stays unknown until supporting runtime evidence is imported.
+
+Every workflow dispatcher loads exactly one `references/astra.md` or
+`references/legacy.md`. Risk affects the extent of verification, never the mandatory
+Fable gate in the Astra profile. Legacy profiles retain their risk-based review.
 
 One canonical closure record links existing project artifacts. `lean`, `linked`, and
 `strict` policies determine what blocks DONE. Waivers are item-specific and retain

package/docs/HUONG-DAN-MIGRATE-VA-SU-DUNG.md

@@ -1,334 +1,46 @@
-# Hướng dẫn migrate và sử dụng NCCGS 1.1
+# Hướng dẫn migrate và sử dụng NCCGS 1.3
 
-NCCGS 1.1 là studio operating system dành cho Unity project trong Claude Code. Nó
-không thay thế cách chat trực tiếp; nó tự phân loại rủi ro, chọn workflow, agent và
-model phù hợp, sử dụng official Unity Skills, thu thập bằng chứng và áp dụng closure.
+Đọc [hướng dẫn vận hành 1.3](NCCGS-1.3.md) trước khi bắt đầu task. Luồng mặc định:
+Astra lập kế hoạch/tài liệu → Opus 5.5/xhigh triển khai → Fable/high review →
+report cho Astra → Astra kiểm tra → bạn nghiệm thu.
 
-## 1. Thành phần
+## Cài hoặc nâng cấp
 
-- 45 studio agents chuyên biệt.
-- 36 NCCGS workflows; 8 entrypoint chính.
-- 3 model profiles: `quality`, `balanced`, `inherit`.
-- 11 path-scoped rules.
-- 8 Node hooks cho recovery, audit và safety.
-- 22 official Unity Skills giữ nguyên và kiểm tra hash.
+Trong từng Unity project, chạy `npx nccgs@latest update --model-profile astra-claude
+--dry-run`. Đọc kết quả, bỏ `--dry-run` để áp dụng, rồi chạy `npx nccgs@latest doctor`.
+Dùng CLI `scripts/cli.mjs` với `--project <UnityProject>` nếu cài từ mã nguồn.
+Dùng `install` thay `update` nếu chưa cài. Update giữ profile hiện tại nếu không
+truyền `--model-profile`. Cần Node.js 18+ và Claude Code tương thích các model.
 
-```text
-Bạn
-  -> Claude Code chính
-  -> NCCGS router (domain + risk + model)
-  -> studio agents cần thiết
-  -> official Unity Skills + Unity CLI/Pipeline
-  -> evidence + review + closure
-```
+## Astra chuẩn bị migration
 
-Claude Code chính là orchestrator duy nhất. Agent không tự tạo thêm cây subagent.
-Mỗi path chỉ có một writing owner trong một batch.
+Astra kiểm tra tài liệu chuẩn, `.nccgs/project.yaml`, yêu cầu kiểm chứng, artifact
+và manual gate đang có. Giữ nguyên các bảo đảm hiện hành; chỉ giảm gate khi bạn đã
+quyết định rõ ràng.
 
-## 2. Cài mới hoặc cập nhật
+Với policy cũ chứa `profile_contracts`, chuyển sang tham chiếu
+`pipeline_policy: .claude/nccgs/pipeline.json`. Map đầy đủ nghĩa vụ của dự án vào
+`.nccgs/gates.json` và điền hash project policy đã kiểm tra. Sau đó cung cấp plan
+migration cho Claude. Không dùng fallback thay Opus/Fable trong profile này.
 
-Trong PowerShell:
+Claude chạy `/migrate-project` theo plan của Astra, xử lý override đã được phân tích,
+kiểm chứng, rồi qua Fable review. Tùy chỉnh local được bảo toàn để review; không dùng
+`--force` chỉ để làm biến mất cảnh báo. Mở phiên Claude mới sau khi đổi cấu hình.
 
-```powershell
-cd "D:\path\to\UnityProject"
-npx nccgs@latest install --dry-run
-npx nccgs@latest install
-```
+## Vận hành hằng ngày
 
-Nếu project đã có NCCGS:
+Có 10 agent lõi hoạt động mặc định, 35 vai trò tùy chọn trong thư viện. Bật/tắt vai
+trò bổ sung bằng `agents --enable/--disable`; lựa chọn được giữ qua update. 36 workflow
+chỉ nạp nhánh Astra hoặc legacy tương ứng với profile hiện tại.
 
-```powershell
-npx nccgs@latest update --dry-run
-npx nccgs@latest update
-npx nccgs@latest doctor
-```
+Astra cung cấp plan và gate; Claude khởi tạo/bind task, triển khai và ghi bằng chứng.
+Fable review độc lập trên cùng snapshot. Chỉ sau PASS mới ghi report; Astra và bạn
+quyết định các bước cuối ngoài phiên Claude. `task close` kiểm tra toàn bộ chuỗi.
+Schema và lệnh chi tiết có trong [hướng dẫn 1.3](NCCGS-1.3.md).
 
-NCCGS mặc định cài vào directory hiện tại. Bạn không cần truyền đường dẫn project;
-hãy mở PowerShell tại Unity project root hoặc dùng `cd` đến đó trước.
+`/status` đọc trạng thái và gate còn thiếu. Cấu hình model/effort yêu cầu được phân
+biệt với quan sát runtime. Thiếu bằng chứng effort thực chạy thì task chưa đủ điều
+kiện bàn giao. Report là file; NCCGS chưa tự gửi giữa ứng dụng.
 
-Từ 1.1, update kiểm tra hash của lần cài trước. File NCCGS chưa bị project sửa sẽ tự
-được backup và cập nhật. File đã sửa tay sẽ chặn update; chỉ dùng `--force` sau khi
-đã review và chấp nhận thay thế bản override.
-
-Installer sẽ:
-
-1. validate NCCGS;
-2. backup file framework/settings bị thay thế vào `.nccgs/backups/<timestamp>/`;
-3. cập nhật `.claude/`;
-4. chỉ tạo những scaffold file `.nccgs/` còn thiếu, không ghi đè project truth;
-5. merge NCCGS hooks vào `.claude/settings.json` mà không xóa settings khác;
-6. cấu hình model cho agents;
-7. thêm NCCGS import vào `CLAUDE.md`.
-
-Sau khi cài, đóng phiên Claude Code cũ và mở phiên mới tại project root.
-
-## 3. Chọn model profile
-
-| Profile | Cách dùng |
-|---|---|
-| `quality` | Mặc định; Opus cho deep/leadership, Sonnet cho implementation, Haiku cho việc nhẹ |
-| `balanced` | Giữ Opus cho deep reasoning, leadership thông thường chạy Sonnet |
-| `inherit` | Bỏ toàn bộ model pin; agents dùng model của phiên chính |
-
-Cài với profile cụ thể:
-
-```powershell
-npx nccgs@latest update --model-profile quality
-```
-
-Đổi profile trong project đã cài:
-
-```powershell
-node .\.claude\nccgs\tools\configure-models.mjs --project . --profile inherit
-```
-
-Profile được ghi trong `.nccgs/project.yaml`. Nếu model pin không dùng được với tài
-khoản hoặc context mode hiện tại, dùng `inherit` hoặc cho phép inherit fallback.
-
-## 4. Migrate project cũ
-
-Thông thường chỉ cần gọi một command:
-
-```text
-/migrate-project
-```
-
-NCCGS vẫn thực hiện bốn phase `review -> plan -> apply -> verify` ở bên trong một
-lần chạy. Nó chỉ dừng khi có quyết định Product Owner thật sự, thao tác destructive,
-external side effect hoặc thiếu authority. Các mode riêng dưới đây vẫn tồn tại để
-debug hoặc kiểm soát thủ công.
-
-### Review
-
-```text
-/migrate-project review
-```
-
-Review là read-only. Nó phải tìm canonical sources, architecture, ownership,
-protected paths, Unity tooling, tests/baselines, reports/registers/checklists, global
-skills xung đột, model policy, hooks, local settings và Git state.
-
-Mỗi artifact nhận một nhãn: KEEP, ADAPT, MIGRATE, DEPRECATE, REMOVE hoặc MISSING.
-
-### Plan
-
-```text
-/migrate-project plan
-```
-
-Plan phải có policy schema 2 được đề xuất, batches có rollback, model profile,
-departments, context packets, hook merge, Unity integration, verification, closure,
-Git tracking và những quyết định Product Owner cần chốt.
-
-Hai quyết định thường gặp:
-
-```text
-D1: Use strict closure mode. Keep existing implementation reports, register
-entries, evidence, and safety checklists as required linked artifacts. They block
-DONE unless an item-specific Product Owner waiver exists.
-
-D2: Commit shared .claude/ and .nccgs/ framework and policy to Git. Keep
-.claude/settings.local.json local. Ignore only .nccgs/backups/ and .nccgs/runtime/.
-```
-
-### Apply
-
-```text
-/migrate-project apply
-```
-
-Claude áp dụng từng batch, xem diff, validate và cập nhật ledger trước khi sang batch
-tiếp theo. Xóa dữ liệu, đổi canon/gameplay, dependency/service, compatibility hoặc
-migration không thể hoàn tác cần bạn phê duyệt.
-
-### Verify
-
-```text
-/migrate-project verify
-/status full
-```
-
-Verify kiểm tra schema 2, model routing/fallback, 45 agent files, 36 workflow files,
-hooks, context packet, official Unity Skill hashes, CLI/Pipeline, compile/tests,
-baseline, evidence mapping và closure gate.
-
-`VERIFIED, not DONE` không phải lỗi nếu artifact, decision hoặc PO gate còn thiếu.
-
-## 5. Dùng NCCGS hằng ngày
-
-Bạn có thể chat như trước:
-
-```text
-Implement campaign walkthrough sessions C–G from the canonical design documents.
-Preserve protected tuning values and verify the result in Unity.
-```
-
-NCCGS sẽ tự chọn:
-
-- risk tier FAST/STANDARD/CONTROLLED;
-- domains và studio roles;
-- model theo profile;
-- context packet và working set;
-- tests, runtime/build evidence và review cần thiết;
-- closure artifacts và PO gates.
-
-### Entry commands
-
-| Command | Dùng khi |
-|---|---|
-| `/work` | Implement/fix/refactor/integrate hoàn chỉnh |
-| `/design` | Thiết kế hoặc thay đổi player-facing semantics |
-| `/audit` | Chẩn đoán read-only |
-| `/migrate-project` | Cài/migrate/nâng cấp framework |
-| `/test` | Thu thập bằng chứng objective |
-| `/review` | Review độc lập, không sửa |
-| `/release` | Tạo release candidate |
-| `/status` | Xem trạng thái, model, agents, evidence và blockers |
-
-Các workflow chuyên biệt như `/architecture-decision`, `/code-review`,
-`/performance-audit`, `/security-audit`, `/balance-review`, `/playtest`, `/hotfix`,
-`/incident-recovery` có thể gọi trực tiếp, nhưng thông thường `/work` tự phối hợp.
-
-## 6. Context packet
-
-STANDARD và CONTROLLED work dùng:
-
-```text
-.nccgs/context/<feature-id>.yaml
-```
-
-Packet chứa link/anchor tới requirements, decisions, ownership, dependencies và
-verification; nó không copy toàn bộ GDD/ADR. Agent chỉ đọc full source khi summary
-thiếu, stale, mâu thuẫn hoặc risk yêu cầu.
-
-Nếu muốn chuẩn bị riêng:
-
-```text
-/context-pack FEATURE-ID
-/story-readiness FEATURE-ID
-/plan-feature FEATURE-ID
-```
-
-## 7. Model và agents hoạt động thế nào?
-
-NCCGS chọn domain role trước rồi áp model class. Ví dụ:
-
-```text
-CONTROLLED save migration
-  -> technical architect (Opus)
-  -> engine/network specialists (Sonnet)
-  -> verification engineer (Sonnet)
-  -> adversarial reviewer (Opus)
-```
-
-Một bug FAST thường không gọi cả studio. Một feature UI STANDARD có thể dùng UX,
-accessibility, UI programmer, Unity UI specialist và verification, nhưng các phần
-read-only/không trùng ownership mới được chạy song song.
-
-## 8. Evidence và closure
-
-- IMPLEMENTED: thay đổi tồn tại.
-- VERIFIED: bằng chứng objective chứng minh requirement.
-- VALIDATED: subjective gate đã được bạn chấp nhận.
-- DONE: mọi objective, artifact và PO gate bắt buộc đã đóng.
-
-Implementation không tự chứng minh chính nó. STANDARD work nên có independent
-verification; CONTROLLED work có adversarial review.
-
-Closure modes:
-
-- `lean`: closure record đủ, link khác optional;
-- `linked`: artifact `required` chặn DONE;
-- `strict`: mọi artifact/checklist khai báo chặn DONE nếu không có waiver cụ thể.
-
-Không hạ closure mode chỉ để trạng thái chuyển xanh.
-
-## 9. Git
-
-Khuyến nghị commit:
-
-```text
-.claude/
-.nccgs/
-CLAUDE.md
-```
-
-Không commit:
-
-```text
-.claude/settings.local.json
-.nccgs/backups/
-.nccgs/runtime/
-```
-
-Nested `.nccgs/.gitignore` đã bỏ qua backup và runtime events.
-
-Sau migration:
-
-```powershell
-git add .claude .nccgs CLAUDE.md
-git status --short
-git commit -m "chore: adopt NCCGS 1.1 studio workflow"
-```
-
-Luôn đọc diff trước commit.
-
-## 10. Xử lý blocker thường gặp
-
-### Global Unity MCP skill còn hoạt động
-
-Di chuyển/xóa legacy global skill khỏi user skills directory, mở phiên Claude mới,
-rồi chạy `/status full`. Đây không phải 22 official Unity Skills trong project.
-
-### Report thiếu register entry
-
-Đọc từng report, dùng report và Git history để backfill. Không đoán commit. Nếu không
-xác định được, ghi unknown và để item bị block cho tới khi có quyết định/waiver riêng.
-
-### Model agent không spawn được
-
-Chuyển sang `inherit`, mở phiên mới và verify routing. Đừng coi lỗi model/context là
-lỗi implementation.
-
-### `project.yaml` vẫn schema 1/template
-
-Installer không ghi đè policy. Chạy lại migration plan/apply để nâng schema và map
-project truth.
-
-### Hook xung đột settings cũ
-
-Xem `.claude/settings.json` và bản backup timestamp. Installer chỉ thay các hook có
-command `.claude/nccgs/hooks/`, giữ nhóm hook và permission khác.
-
-## 11. Validate và rollback
-
-Trong NCCGS source:
-
-```powershell
-npm run validate
-npm test
-```
-
-Nếu upgrade lỗi, dừng thay đổi mới, xem `.nccgs/backups/<timestamp>/`, phục hồi đúng
-file framework/settings hoặc Git revert commit nâng cấp, mở phiên mới, rồi chạy
-`/migrate-project verify`. Không dùng destructive reset khi worktree còn dữ liệu.
-
-## 12. Checklist hoàn tất migration
-
-- [ ] Project policy dùng schema 2.
-- [ ] Canonical sources và ownership được map.
-- [ ] Model profile/fallback được quyết định.
-- [ ] Departments và orchestration depth được cấu hình.
-- [ ] Context packet mẫu hoạt động.
-- [ ] Managed Node hooks hoạt động.
-- [ ] Official Unity Skills khớp manifest.
-- [ ] Unity CLI/Pipeline và compile/tests đạt baseline.
-- [ ] D1 closure và D2 Git tracking được ghi nhận.
-- [ ] Legacy routing conflicts được xử lý.
-- [ ] Closure gate chặn đúng artifact thiếu.
-- [ ] Representative `/work` path thành công.
-- [ ] `/status full` không còn blocker ngoài ý muốn.
-- [ ] Framework/policy đã được commit.
-
-Sau đó quay lại feature sản phẩm có giá trị cao nhất; không tiếp tục làm framework
-nếu không còn blocker thực tế.
+Các profile `quality`, `balanced`, `inherit` giữ quy trình cũ trong từng
+`references/legacy.md`. Chọn chúng là chủ động dùng luồng legacy.

package/docs/MIGRATION-MATRIX.md

@@ -3,7 +3,7 @@
 | CCGS capability | NCCGS 1.1 treatment | Reason |
 |---|---|---|
 | Three-tier studio hierarchy | ADAPT into 44 roles and a central one-level orchestrator | Preserve specialization without recursive context chains |
-| Opus/Sonnet/Haiku agent pins | ADAPT into quality/balanced/inherit profiles | Preserve model routing while handling compatibility and cost |
+| Opus/Sonnet/Haiku agent pins | ADAPT into astra-claude or explicit legacy profiles | Preserve model routing while handling compatibility and cost |
 | 73 large workflow skills | ADAPT into 36 composable workflows and focused references | Preserve lifecycle coverage without repeated prompt/context payload |
 | Team commands spawning departments | MIGRATE to risk/domain execution DAGs | Select roles by deliverable, not ceremony |
 | Per-file approval protocol | REMOVE for ordinary authorized implementation | Keep approval at product, compatibility, dependency and irreversible boundaries |

package/docs/NCCGS-1.3.md

@@ -0,0 +1,125 @@
+# NCCGS 1.3 — quy trình Astra / Claude có kiểm tra bằng mã
+
+NCCGS dùng một nguồn cấu hình tại `.claude/nccgs/pipeline.json`:
+Opus 5.5/xhigh triển khai, Fable/high review, Astra kiểm tra report và bạn nghiệm thu.
+Mỗi Unity project cần chạy update để nhận bản mới; publish không tự sửa các dự án.
+
+## 1. Nguồn cấu hình và nhóm agent
+
+`pipeline.json` quyết định model, effort, phiên chính, vai trò mặc định và chủ sở hữu
+workflow. `npm run policy:build` sinh các bản cấu hình phụ; `npm run validate` phát
+hiện nếu chúng lệch nguồn. Không chỉnh trực tiếp model trong file agent được sinh.
+
+Mặc định chỉ có 10 agent được nạp: gameplay, engine, UI programmer, Unity implementer,
+Unity systems, Unity UI, Unity build, QA, verification và adversarial reviewer.
+35 vai trò khác ở `.claude/nccgs/agent-library/`, không xuất hiện trong danh sách
+agent mặc định. Astra sở hữu planning/documents; vai trò tư vấn chỉ bật khi cần.
+
+Trong Unity project đã cài:
+
+```powershell
+node .claude/nccgs/tools/configure-models.mjs --project . --enable nccgs-network-programmer
+node .claude/nccgs/tools/configure-models.mjs --project . --disable nccgs-network-programmer
+```
+
+Lựa chọn được lưu trong `.nccgs/agent-activation.json` và giữ qua update. File agent
+đã tùy chỉnh được bảo toàn và báo để review; không âm thầm xóa hoặc ghi đè. Profile
+legacy vẫn có đủ 45 vai trò. Không được tắt reviewer hoặc các agent lõi.
+
+## 2. Astra chuẩn bị đầu vào
+
+Astra cung cấp plan và map các yêu cầu kiểm chứng của dự án vào `.nccgs/gates.json`:
+`requiredChecks`, `requiredArtifacts`, `manualGates`. Trường `policySha256` phải là
+hash của `.nccgs/project.yaml` mà Astra đã kiểm tra. Có thể lấy hash qua lệnh `ref`
+dưới đây. Manifest không thay thế yêu cầu cũ: cần map đầy đủ gate/artifact đang dùng.
+
+```powershell
+node .claude/nccgs/tools/task.mjs ref --file .nccgs/project.yaml
+node .claude/nccgs/tools/task.mjs init --id feature-1 --plan .nccgs/features/feature-1.md
+```
+
+Có thể thêm `--requirements .nccgs/features/feature-1-gates.json` để bổ sung yêu cầu
+riêng của task. File dùng schemaVersion 1 và ba mảng giống gate manifest của dự án.
+
+## 3. Claude triển khai và Fable review
+
+Hook SessionStart hiển thị session ID để bind task. Các lệnh `snapshot`, `ref`,
+`observe`, `verify`, `record`, `check` hỗ trợ ghi bằng chứng:
+
+```powershell
+node .claude/nccgs/tools/task.mjs bind --id feature-1 --session SESSION_ID
+node .claude/nccgs/tools/task.mjs snapshot
+node .claude/nccgs/tools/task.mjs verify --id feature-1 --name regression -- node scripts/run-tests.mjs
+node .claude/nccgs/tools/task.mjs record --id feature-1 --stage implementation --evidence .nccgs/evidence/implementation.json
+node .claude/nccgs/tools/task.mjs record --id feature-1 --stage review --evidence .nccgs/evidence/review.json
+node .claude/nccgs/tools/task.mjs check --id feature-1 --target report
+```
+
+Lệnh test ở ví dụ phải được thay bằng test runner thật của dự án. `verify` chạy
+trực tiếp executable, lưu exit code/log/hash và đánh FAIL nếu test lỗi hoặc thay đổi
+source. Nó không chạy qua shell để diễn giải lại chuỗi lệnh.
+
+Report chỉ được ghi vào pipeline sau khi Fable PASS. Nếu sửa source/test/asset sau
+review, cần ghi lại implementation và review; các gate sau tự bị xóa khi ghi lại
+bước trước. Nội dung cũ được giữ trong history. File task nằm ở `.nccgs/tasks/` và
+là bản ghi chính thức; nhãn DONE trong Markdown không thay thế bản ghi này.
+
+## 4. Astra kiểm tra và bạn nghiệm thu
+
+Astra nhập kết quả kiểm tra ngoài phiên Claude. Chỉ sau quyết định nghiệm thu rõ
+ràng của bạn mới nhập acceptance, kèm tham chiếu quyết định và cùng snapshot:
+
+```powershell
+node .claude/nccgs/tools/task.mjs record --id feature-1 --stage report --evidence .nccgs/evidence/report-stage.json
+node .claude/nccgs/tools/task.mjs record --id feature-1 --stage astra --evidence .nccgs/evidence/astra-stage.json
+node .claude/nccgs/tools/task.mjs record --id feature-1 --stage acceptance --evidence .nccgs/evidence/acceptance-stage.json
+node .claude/nccgs/tools/task.mjs check --id feature-1 --target done
+node .claude/nccgs/tools/task.mjs close --id feature-1
+```
+
+Mỗi JSON stage chứa snapshot và tham chiếu evidence `{path, sha256}`; evidence của
+astra/acceptance là quyết định JSON riêng. Xem schema và thứ tự chi tiết trong
+[task-gates](../.claude/nccgs/protocols/task-gates.md). Không tạo quyết định thay bạn.
+
+## 5. Quan sát runtime và giới hạn
+
+Hook lưu model thực chạy khi Claude cung cấp, cả danh sách model nếu có fallback.
+Effort không xuất hiện trong mọi sự kiện; trường thiếu được để null và chưa qua gate.
+Có thể dùng `task observe` nhập bằng chứng từ provider log hoặc quan sát runtime
+có tham chiếu. Cấu hình yêu cầu không được dùng làm chứng cứ thực chạy.
+
+Các gate kiểm tra thứ tự, độc lập reviewer, model/effort, snapshot, hash evidence,
+check bắt buộc, artifact, manual gate, Astra check và nghiệm thu. Hook chặn một số
+thao tác ghi DONE trực tiếp; `task close` là đường đóng task chính thức. Đang đợi
+Astra/bạn là điểm dừng hợp lệ, không ép agent chạy vô hạn.
+
+Đây là kiểm soát quy trình local, không phải xác thực danh tính bằng mật mã. Người
+có quyền sửa toàn bộ tool và evidence vẫn có thể sửa dữ liệu. Report chưa tự gửi
+giữa ứng dụng. Thử nghiệm fixture không chứng minh một phiên Opus/Fable thật đã chạy.
+
+## 6. Cập nhật từ npm và kiểm chứng
+
+Chạy trong thư mục gốc của từng Unity project đã cài NCCGS:
+
+```powershell
+npx nccgs@latest update --model-profile astra-claude --dry-run
+npx nccgs@latest update --model-profile astra-claude
+npx nccgs@latest doctor
+```
+
+Dùng `install` thay `update` với dự án chưa cài. Nếu bỏ `--model-profile`, update
+giữ profile hiện tại. Mở phiên Claude Code mới sau khi cập nhật cấu hình.
+
+Dùng CLI của bản nguồn này với `install` hoặc `update --model-profile astra-claude`
+và `--project` trỏ đúng Unity project. Chạy `--dry-run` trước. Không cần dùng force
+để bỏ qua tùy chỉnh. `doctor` kiểm tra integrity, trạng thái agent và closure hiện tại;
+closure lịch sử của snapshot cũ không được dùng để duyệt code hiện tại.
+
+```powershell
+npm run policy:check
+npm run validate
+npm test
+```
+
+Mỗi workflow giờ chỉ điều hướng sang `references/astra.md` hoặc
+`references/legacy.md`. Claude chỉ đọc nhánh của profile đang dùng.