# Kế hoạch đồng bộ runtime ECC

## 1. Mục tiêu

Giữ dsh-ecc đồng bộ với runtime ECC upstream mà không cho phép thay đổi chưa
được kiểm tra làm thay đổi một phiên DSH đang chạy.

Mỗi bản phát hành dsh-ecc phải xác định ba đầu vào bất biến:

1. version của package dsh-ecc;
2. tag hoặc commit ECC được đóng gói trong `assets/ecc`;
3. runtime DSH và khoảng peer dependency đã kiểm tra.

Version dsh-ecc không dùng chung số version với ECC. Ví dụ, snapshot ECC
`2.2.0` có thể cần bản dsh-ecc `0.2.0` nếu adapter bổ sung mapping hoặc runtime
contract mới.

## 2. Baseline và kết quả kiểm tra upstream

Kiểm tra được thực hiện ngày `2026-08-18`.

| Hạng mục | Giá trị |
| --- | --- |
| dsh-ecc (baseline lịch sử) | `0.1.0` |
| ECC version trong metadata hiện tại | `2.2.0` |
| Tag phát hành ECC mới nhất | `v2.1.0` tại commit `4da6deac1888690e7fb8572d097ee23db630f7a0` |
| Metadata/package version trên `main` | `2.2.0` |
| Commit `main` mới nhất | `06c5e118c4d3e6c3b7f9445f973a2194c82de193` |
| Commit ECC snapshot baseline | `50743cec75852e32d6517c9894a3339a2462a713` |
| ECC source | `https://github.com/affaan-m/ECC.git` |
| DSH peer floor | `>=0.1.0-rc.5` |
| Runtime DSH đã kiểm tra | `0.1.0-rc.7` |
| Chính sách update | bundled snapshot, update explicit |

Nguồn đối chiếu chính thức:

- [ECC tags](https://github.com/affaan-m/ECC/tags)
- [ECC package.json trên main](https://github.com/affaan-m/ECC/blob/main/package.json)
- [ECC VERSION trên main](https://raw.githubusercontent.com/affaan-m/ECC/main/VERSION)
- [Commit main mới nhất](https://github.com/affaan-m/ECC/commit/06c5e118c4d3e6c3b7f9445f973a2194c82de193)

Commit `06c5e11` là con trực tiếp của `50743ce` và chỉ thay đổi ba file test
trong `tests/ci` để kiểm tra artifact Itô. Không có thay đổi trong `agents/`
hoặc `skills/` mà dsh-ecc đang đóng gói.

Kết luận cho lần kiểm tra baseline:

- Không cần tăng version dsh-ecc.
- Chưa cần thay đổi `assets/ecc/revision.json` ở thời điểm baseline.
- Không cần đồng bộ lại agents hoặc skills.
- Snapshot `50743ce` được giữ nguyên để bảo đảm reproducible build.
- Lần sync tiếp theo phải kiểm tra lại cả release tag và `main`; không được coi
  metadata version `2.2.0` là bằng chứng rằng tag `v2.2.0` tồn tại.

### Cập nhật sau baseline

Các kết luận trên là snapshot lịch sử trước khi model-catalog lifecycle adapter
được triển khai. Bản phát hành hiện tại dùng package identity scoped
`@staavanothanh/dsh-ecc@0.5.0` và phân phối bằng GitHub release tarball; không
dùng package unscoped `dsh-ecc` vì tên đó thuộc một project khác trên npm.

Bundle hiện tại bất biến sau khi cài đặt. Runtime startup không được fetch
`main`, `latest` hoặc một ref chưa xác minh.

`eccVersion` là metadata dễ đọc cho người dùng. Commit bất biến mới là source
of truth cho remote synchronization. Bản `v0.4.0` pin ECC vào commit
`06c5e118c4d3e6c3b7f9445f973a2194c82de193`; upstream không thay đổi
`agents/` hoặc `skills/` trong lần sync này, nên closure 68 agents và 285 skills
được giữ nguyên. Runtime chỉ yêu cầu hai closure đó và package chỉ phát hành
đúng các closure đã hỗ trợ.

`v0.4.0` cũng làm model-catalog lifecycle adapter nhận biết durable session
surface. Khi DSH compaction shadow catalog message cũ, `agent/pre-step` inject
lại catalog hiện tại trước request tiếp theo. Cơ chế này không phụ thuộc vào
`agent/session-start`.

### Snapshot đồng bộ ngày 2026-08-20

Đã kiểm tra `main` của ECC và xác minh commit mới nhất là
`d8409a4b0813771235555e32e3d8046a73988bfa` (ECC `2.2.0`). So với revision
`06c5e118c4d3e6c3b7f9445f973a2194c82de193`, commit này chỉ thêm skill
`skills/tasteforge-video/SKILL.md`; không thay đổi `agents/`.

Snapshot `assets/ecc` đã được bổ sung skill này, nâng closure lên 68 agents và
286 skills. `assets/ecc/revision.json`, `src/config.ts`, `cordis.patch.yml`,
test asset contract và hướng dẫn cài đặt đều pin cùng SHA mới. Đây là cập nhật
asset-only; chưa tăng version dsh-ecc và chưa tạo release mới.

### Nâng cấp theo DSH `0.1.1-rc.1` — dsh-ecc `0.5.0`

Đối chiếu DSH `dsh-v0.1.0-rc.8` → `dsh-v0.1.1-rc.1` xác nhận các seam mà
dsh-ecc sử dụng vẫn tương thích: `ctx.subagents.startContinuable`,
`followup`, `registerContinuableSetup`, `installModelSelection`,
`agent/pre-step` và `llm/adapters-updated`. RC1 cải thiện session snapshot,
projection/wire state và cleanup subagent; đây là nền tảng để adapter thêm
resolver resume durable mà không sửa DSH core.

Bản `@staavanothanh/dsh-ecc@0.5.0` có các thay đổi:

- đổi tên model-facing tool từ `spawn_subagent` thành `spawn` (không alias cũ);
- khôi phục binding follow-up từ live child hoặc
  `ctx.sessionPersistence.inspect(childId)` và validate parent/mode/route/effort;
- giữ persona ECC đã normalize (loại `tools`/`model`) và tool scope do DSH
  compose từ parent;
- tiếp tục refresh model-catalog ở `agent/pre-step` sau compaction và khi
  `llm/adapters-updated` phát hiện route mới;
- nâng runtime validation lên DSH `0.1.1-rc.1`, giữ peer floor hiện tại.

ECC snapshot không đổi trong release này: vẫn pin commit
`d8409a4b0813771235555e32e3d8046a73988bfa` (ECC `2.2.0`).

## 3. Các file source of truth

Một lần update phải giữ các file sau nhất quán:

| File | Trách nhiệm |
| --- | --- |
| `assets/ecc/revision.json` | repository, version/ref, commit và metadata snapshot ECC |
| `assets/ecc/agents/` | persona và instruction resources |
| `assets/ecc/skills/` | skill definitions và resource closure |
| `cordis.patch.yml` | source ref mặc định và adapter policy |
| `package.json` | version dsh-ecc và DSH peer ranges |
| `NOTICE` | attribution và revision notice của ECC |
| `docs/research/compatibility-matrix.md` | bằng chứng mapping và khoảng thiếu tương thích |
| `pnpm-lock.yaml` | dependency resolution có thể tái lập cho development |

Không được chỉ sửa `revision.json` trong khi asset tree hoặc patch ref vẫn trỏ
đến revision cũ.

## 4. Quy trình update

### Giai đoạn A — Phát hiện và pin upstream

1. Kiểm tra releases và tags của repository ECC.
2. Chọn một release tag hoặc commit cụ thể. Không dùng `main` cho release.
3. Resolve tag về commit SHA bất biến.
4. Ghi repository, tag, commit và thời điểm UTC vào update manifest tạm.
5. So sánh tree upstream với tree đang bundle. Phân loại thay đổi thành agents,
   skills, metadata hoặc surface không hỗ trợ.

### Giai đoạn B — Tạo lại snapshot

1. Checkout commit đã chọn vào thư mục tạm bên ngoài working tree.
2. Chỉ copy closure được hỗ trợ vào `assets/ecc`: `agents` và `skills`.
3. Xóa các file đã bị upstream xóa trước khi copy closure mới.
4. Loại `.git`, cache local, credential, generated output và binary/config MCP
   mà dsh-ecc không sở hữu.
5. Sinh `assets/ecc/revision.json` từ commit đã chọn; không gõ SHA thủ công.
6. Sinh file manifest deterministic và SHA-256 digest cho snapshot.
7. Cập nhật `eccSource.ref` trong `cordis.patch.yml` và version dsh-ecc nếu
   release policy yêu cầu.
8. Cập nhật `NOTICE` và compatibility matrix.

Về sau phải có một script sync có thể chạy lặp lại. Trước khi có script đó,
mỗi file được copy phải được review bằng diff sinh tự động cùng báo cáo số
lượng file và hash.

Revision manifest sinh tự động nên có tối thiểu:
`eccVersion`, `ref`, `commit`, `repository`, `sourceDate`,
`closureIntegrity` và số lượng agents, skills. Các field này
cho phép audit package mà không cần mở checkout upstream.

### Giai đoạn C — Kiểm tra adapter boundary

Chạy kiểm tra với cả DSH peer version thấp nhất và runtime DSH mới nhất đã xác
nhận:

```powershell
pnpm typecheck
pnpm test
pnpm build
pnpm pack:check
```

Test matrix phải bao phủ:

- parse agent frontmatter và persona lookup;
- exact mapping và alias mapping của built-in tools;
- MCP entry không map được và strict tool policy;
- skill discovery, metadata, body loading và duplicate-name behavior;
- giới hạn flat skill name hiện tại của DSH;
- `spawn`: start, provider/model và effort selection có điều kiện, persona injection,
  follow-up, cold resume và input invalid;
- revision/hash report của asset;
- package contents và cài đặt trên DSH profile sạch.

Namespace `/ecc:<name>` là release gate. Trước khi host resolver và client
picker cùng được implement và test, release notes phải ghi rõ runtime đang dùng
entrypoint flat `/name` native của DSH.

### Giai đoạn D — Review tương thích

Với mỗi thay đổi upstream, kiểm tra:

1. frontmatter keys và required fields;
2. tên `tools` của agent và thay đổi DSH tool schema;
3. skill names, invocation flags, metadata và resource paths;
4. script mới hoặc runtime dependency mới;
5. MCP hoặc command surface nằm ngoài scope của dsh-ecc;
6. thay đổi DSH peer API trong `ctx.skills`, `ctx.tools` và `ctx.subagents`.

Phân loại mỗi thay đổi:

- **Tương thích:** không cần đổi adapter hoặc user configuration.
- **Cần đổi adapter:** cập nhật normalizer/resolver/catalog và test tương ứng.
- **Không hỗ trợ:** chỉ giữ file nếu file an toàn và ghi rõ bị ignore; nếu không
  thì loại khỏi snapshot.
- **Breaking:** cần tăng major version hoặc có migration note rõ ràng.

Cập nhật `docs/research/compatibility-matrix.md` với evidence cho mọi phân
loại không tầm thường. Baseline source hiện tại đã được refresh theo DSH
`0.1.1-rc.1`; peer floor là package contract, không phải bằng chứng rằng mọi
build DSH trung gian đều tương thích.

Peer range hiện tại bắt đầu từ `0.1.0-rc.5` và chưa có upper bound. Trước release
tiếp theo, phải test minimum version và runtime hiện tại, sau đó chọn upper
bound rõ ràng nếu DSH không bảo đảm API ổn định qua minor line kế tiếp.

### Giai đoạn E — Release và publish

1. Áp dụng semantic version bump.
2. Cập nhật release notes với version dsh-ecc, ECC tag/commit, DSH compatibility
   range và migration note.
3. Chạy `npm pack --dry-run` hoặc `pnpm pack:check`, sau đó kiểm tra tarball
   file list.
4. Cài tarball vào DSH profile tạm và sạch.
5. Chạy DSH Web, kiểm tra skill, persona spawn, follow-up và
   model/effort selection có điều kiện.
6. Chỉ tạo Git tag và GitHub release sau khi clean-profile test thành công.
7. Giữ package và ECC snapshot tốt trước đó làm rollback target.

## 5. Chính sách version

Version dsh-ecc độc lập với ECC:

| Thay đổi | Bump dsh-ecc |
| --- | --- |
| Documentation, test, metadata nội bộ hoặc ECC content snapshot tương thích | patch |
| Thêm ECC agent/skill hoặc public capability tương thích ngược | minor |
| Thêm public tool field, alias bridge hoặc đổi default | minor |
| Xóa/đổi tên field public, đổi persona normalization hoặc tăng DSH floor | major |

Mỗi release phải cập nhật revision ECC được bundle ngay cả khi source adapter
không đổi. Release notes phải nói rõ thay đổi đến từ ECC, DSH hay dsh-ecc.

## 6. Lộ trình tự động hóa

### Follow-up sau MVP

- Thêm command deterministic `scripts/sync-ecc.mjs` hoặc tương đương.
- Thêm CI job so sánh upstream release mới nhất với `assets/ecc/revision.json`
  và tạo update report.
- Ghi số lượng file và hash snapshot vào test output.
- Thêm release checklist chặn publish nếu revision manifest, patch ref và asset
  tree không đồng nhất.

### Remote update hậu MVP

Remote update chỉ opt-in và explicit:

1. tải tag/commit đã pin vào
   `<DSH_HOME>/cache/dsh-ecc/ecc/<revision>`;
2. verify commit identity, file manifest và integrity digest;
3. chạy compatibility checks trước khi activate;
4. đổi active revision pointer atomically;
5. giữ revision tốt trước đó;
6. khôi phục pointer cũ nếu catalog initialization lỗi.

Session đang chạy giữ immutable revision đã chọn lúc spawn. Update chỉ áp dụng
cho session mới được mount.

## 7. Quy trình rollback

Nếu release lỗi sau khi publish:

1. đánh dấu GitHub release là superseded;
2. cài lại package dsh-ecc tốt trước đó;
3. xác minh ECC commit trong `assets/ecc/revision.json`;
4. chạy lại clean-profile smoke test;
5. mở compatibility issue ghi rõ thay đổi upstream gây lỗi;
6. không xóa snapshot lỗi cho đến khi regression có thể tái hiện.

Ở remote mode trong tương lai, rollback chỉ là đổi atomic pointer. Không được
mutate hoặc xóa revision mà child session đang sử dụng.

## 8. Tiêu chí hoàn thành

Một lần update ECC chỉ hoàn tất khi:

- snapshot được pin vào commit đã verify;
- mọi source-of-truth file đồng nhất;
- compatibility và security review được ghi lại;
- unit, integration, package và clean-profile checks đều pass;
- release notes tách riêng version ECC, DSH và dsh-ecc;
- release tốt trước đó vẫn cài đặt được;
- thay đổi không hỗ trợ được ghi rõ, không bị ignore im lặng.