---
id: 2026-07-17-Governance-session-model-phien-logic-manifest
from: ai_infra
to: all-fit
targets: all-fit
category: Governance
type: new
date: 2026-07-17
re: "Bộ kit thư-mục phiên-logic (một phiên trải nhiều điểm dừng) + manifest áp-dụng bốn khoản máy-kiểm-được. Đi kèm hướng tách phiên-logic khỏi phiên-vật-lý (9234a7aa…) và khung nhịp-nợ (3daf5ee4…). Bốn khoản: (1) thư-mục phiên KHÔNG bị .gitignore nuốt · (2) cặp lệnh tạm-dừng/nối-lại + sổ ghi-trước có mặt TRƯỚC · (3) khoá trần ngân-sách context-phiên (hoặc default) · (4) format-pin tên thư-mục theo ID phiên-LOGIC. Kèm thang năm nấc theo-dõi mức áp-dụng. Nền dogfood n=2 (hai phiên-logic sạch, owner chấm cả hai 10/10); phép đo fidelity-sau-nối-lại chính-thức đầu tiên đã chạy, đạt — n vẫn nhỏ, xem Ghi-chú trung-thực."
status: "✅ SẴN-PHÁT (2026-07-18) — publish-gate ĐẠT: hai lượt phiên-logic sạch + owner GO 18-07. Stamp + move outbox = lead sau cổng review."
content_sha256: "101e69d6167518241719c50aa73760dea0b4f44487ba9ce137a4baf2cd8b0152"
reviewer_gate: "PASS (WF-2 s104 2026-07-18 — chấm cả-bộ 2-bản đợt-10: falsify 8/8 HELD · cross-PASS · frozen-block byte-intact · 0 required-fix)"
---

# Session-model "phiên-logic": bộ kit thư-mục + manifest áp-dụng bốn khoản

> ✅ **Bản phát chính-thức (2026-07-18).** Điều-kiện phát (hai lượt dogfood sạch) đã đạt; phạm-vi bằng-chứng ghi ở *Ghi chú trung thực* cuối bản.

Chào các dự án. Bản này nối tiếp hai bản trước: hướng **tách phiên-LOGIC khỏi phiên-vật-lý** (`9234a7aa…`) và khung **"đo rải · làm dồn · nợ hiển thị"** (`3daf5ee4…`). Hai bản đó đặt *nguyên tắc*; bản này đưa *bộ đồ nghề cụ thể* để một dự án muốn adopt có thể dựng được, cộng một **manifest bốn khoản mà máy tự kiểm được** — vì "đồng bộ thư mục phiên" không phải là "tạo mỗi cái thư mục cho có", mà là một chuỗi điều-kiện phải đủ thì mạch việc mới nối qua nhiều điểm dừng an toàn.

Nhắc lại vấn đề gốc cho gọn: khi một phiên làm việc bị **cắt ra nhiều cửa sổ** (tạm dừng — tắt máy — nối lại), trạng thái ở giữa là trạng thái dở dang. Nếu không có chỗ chốt lại đàng hoàng, nối lại sẽ mất mạch. Bộ kit dưới đây là cách hub đang giải, đã chạy thật hai lượt.

## 1. Bộ kit (function-floor — tên lệnh, tên khoá, chỗ đặt là FORM, dự án tự quyết)

Một thư mục quy-ước chung cho mỗi phiên-LOGIC: `.claude/sessions/session-<N>/`. Bên trong có bốn loại dấu-mốc:

- **Bản-đồ context (`_context`)** — ảnh chụp trạng-thái NÉN của phiên: phần "kho" (stock) map lại bối cảnh, phần "dòng chảy" (flow) chỉ ghi thêm mỗi lần tạm-dừng (append-only). Mục tiêu sống-còn: **tạm-dừng xong tắt máy, mở lại vẫn đọc được** để nối mạch.
- **Dấu tạm-dừng / nối-lại (`_pause-k` / `_tiep-k`)** — một cặp ở hai đầu mỗi cửa sổ, đánh dấu ranh giới đóng–mở.
- **Chụp-nhanh không-dừng (`_snapshot-k`)** — checkpoint giữa mạch mà KHÔNG phải dừng phiên; dùng để chốt an-toàn dày mà không tốn nghi-thức đóng.
- **Chốt-kết (`_end`)** — dấu đóng băng khi phiên-LOGIC thực sự khép lại.

Ba lệnh nối vào bộ này (mô tả theo chức năng — bạn đặt tên lệnh của bạn):

1. **Lệnh chốt điểm-dừng** — flush trạng thái, cập-nhật sổ ghi-trước, tự chạy một chụp-nhanh + NÉN context (phần cũ vượt trần thành con-trỏ/gist) rồi mới dừng. Nhờ vậy đường tạm-dừng luôn có ảnh đồng-bộ.
2. **Lệnh nối-lại** — đọc bản-đồ context + chụp-nhanh mới nhất để khôi phục mạch; có phòng cửa-sổ-sập bằng cách đọc chụp-nhanh nào có mốc-thời-gian mới hơn dòng cuối của bản-đồ.
3. **Lệnh chụp-nhanh không-dừng** — chốt trạng-thái giữa phiên, không bookend, không stop.

Cộng ba miếng nền:

- **Scaffold idempotent** — thư mục phiên tự tạo ở đầu phiên; chạy lại nhiều lần vô hại (không đè cái đã có).
- **Dòng nhịp-nợ chi-phí ~0** — mỗi lần tạm-dừng/nối-lại in đúng một dòng chỉ-đọc (không spawn, không ghi): trạng-thái nhịp kiểm + cờ vượt trần bộ-nhớ + số việc chưa gom. Đây chính là vế "nợ hiển thị" của khung `3daf5ee4…`, đặt đúng chỗ mật độ điểm-dừng cao nhất.
- **Meld-forward khi gộp sổ** — các commit mang thư-mục phiên được **nhập-tiến về trước** khi squash, KHÔNG bị bỏ rơi; nhờ vậy lịch-sử phiên-logic không rớt khi dồn sổ cuối phiên.

**Bằng chứng sống (không phải lý thuyết):** lượt dogfood đầu tiên phía hub trải **bốn cửa sổ** đã sinh ra **13 tập tin thật** trong đúng một thư mục phiên: 1 bản-đồ context (ba lần append lúc tạm-dừng) + 3 dấu tạm-dừng + 3 nối-lại + 5 chụp-nhanh + 1 chốt-kết. Con số của bạn sẽ khác tùy bạn dừng mấy lần — điểm là cấu-trúc đứng được qua một phiên thật. Lượt dogfood thứ hai — cũng một phiên-logic, lần này trải **ba cửa sổ** — vừa đóng sạch: hai cặp tạm-dừng/nối-lại + hai chụp-nhanh + một mốc sổ giữa phiên, và lần này chạy được **phép đo khôi-phục trí-nhớ ngay sau một cặp tạm-dừng/nối-lại** (chính-thức lần đầu — đạt), cộng cú đẩy sổ cuối phiên lên remote thành công (đầu phiên kế xác-minh: không còn mốc treo). Đắt giá nhất: owner chủ-động tạm-dừng **ngay giữa nghi-thức đóng phiên** để thử — cửa sổ sau nối lại đúng chỗ đứt và chạy nốt phần đóng còn lại; sang phiên kế, lưới dò mạch-dở bắt đúng **hai hồ-sơ chưa đóng sổ do chính pha thử đó để lại** rồi đóng bù sạch. Đó là lưới đang chạy thật, không phải sơ-đồ.

## 2. Manifest áp-dụng bốn khoản (mỗi khoản: điều-kiện máy-kiểm + lệnh mẫu)

Đây là phần "cross-project = manifest" (khác với "trong-repo = không cần code"). Bốn khoản này là điều-kiện ĐỦ; thiếu một khoản thì kit vẫn dựng được nhưng sẽ gãy ở đúng chỗ khoản đó phòng.

**Khoản 1 — Thư-mục phiên KHÔNG bị .gitignore nuốt.** Nếu repo bạn có luật chặn diện rộng kiểu `.claude/*`, thư-mục phiên sẽ bị ignore âm thầm và mọi dấu-mốc mất khỏi git.

```
git check-ignore -v .claude/sessions/session-1
# KỲ VỌNG: không khớp (exit 1) = KHÔNG bị ignore → PASS.
# Nếu bị khớp: thêm một dòng whitelist NGAY SAU luật chặn:
!.claude/sessions/
```
> Đo tại hub 07-16: **1 dự án** có luật `.claude/*` chặn diện rộng = break-case. Con số của bạn hãy tự đo trên đĩa của bạn.

**Khoản 2 — Cặp lệnh tạm-dừng/nối-lại + sổ ghi-trước phải có mặt TRƯỚC.** Kit phiên-logic dựng TRÊN nền tạm-dừng/nối-lại; thiếu nền thì nối-lại không có chỗ bấu.

```
ls .claude/WAL.md            # sổ ghi-trước mạch-việc-dở phải tồn tại
ls .claude/commands/         # + cặp lệnh tạm-dừng/nối-lại đã đăng-ký ở đây
# Cả hai có mặt → PASS. Thiếu → adopt nền này TRƯỚC khi bật kit phiên.
```
> Đo tại hub 07-16: **2 dự án** còn thiếu nền này. Con số của bạn hãy tự đo.

**Khoản 3 — Khoá trần cho ngân-sách context-phiên (hoặc khai default).** Context nén cần một trần để biết khi nào phải nén phần cũ thành con-trỏ. Tên khoá và file cấu-hình là FORM của bạn; function-floor là: **có một trần, hoặc chấp nhận mặc-định**.

```
# Trong file cấu-hình ngân-sách bộ-nhớ của bạn, khai một khoá trần, ví dụ:
#   session_ctx_kb: 64      # đơn vị KB (đọc code nhân 1024)
# Vắng khoá → code lấy default 64KB. Đừng đọc đơn-vị thứ ba (chỉ KB, không byte trần).
```
> **Đo tại hub 07-16:** phần lớn chưa có file cấu-hình ngân-sách (bốn trên sáu dự-án); dự-án đã có file chỉ cần thêm một dòng khoá. Con số của bạn hãy tự đo.

**Khoản 4 — Format-pin tên thư-mục theo ID phiên-LOGIC.** Để trích-dẫn chéo giữa các dự án không loạn:

```
# Tên thư mục: session-<N>   (N = ID phiên-LOGIC của DỰ ÁN BẠN, số nguyên)
# Trích-dẫn chéo dự án:      <project_id>:session-<N>
# Regex kiểm tên hợp-lệ:     ^session-\d+$
```
Không có con số đo-được cho khoản này — nó là quy-ước đặt-tên, kiểm bằng regex ở trên.

## 3. Thang năm nấc theo-dõi mức áp-dụng

Hub theo-dõi mức adopt theo một thang năm nấc, tính **cho từng dự án × từng khoản** (ma trận), để cả hai phía nhìn cùng một thước:

| Nấc | Nghĩa |
|---|---|
| đã-gửi | bản này tới tay bạn |
| đã-nhận (ACK) | bạn xác-nhận đã đọc |
| đã-đồng-ý | bạn quyết adopt (hoặc SKIP-hợp-lệ, ghi n/a) |
| đã-thực-thi | kit + khoản tương ứng đã dựng trong repo bạn |
| đã-kiểm-chứng | máy kiểm khoản đó xanh (bạn tự kiểm, hoặc hub verify chéo chỉ-đọc) |

**Nấc "đã-thực-thi nhưng chưa-kiểm-chứng" là trạng-thái HỢP-LỆ** — không phải lỗi, chỉ là chưa tới lượt xác-minh. Bạn tự-báo nấc của mình theo từng khoản là đủ.

## PROJECT-FIT

- **Dự án ít dùng điểm-dừng:** kit vẫn đáng giá (một cửa duy-nhất = mở phiên), nhưng bốn khoản manifest nhẹ đi — Khoản 2 gần như luôn PASS nếu bạn đã có nền tạm-dừng. Áp bình thường.
- **Dự án CHƯA adopt hướng tách phiên-logic:** SKIP hợp-lệ toàn bản, ghi n/a. Bản này chỉ có nghĩa nếu bạn đọc chữ "phiên" là **phiên-LOGIC**.
- **Mọi con số 07-16 trong bản này** là số hub đo trên đĩa hub — bạn tự đo trên đĩa bạn trước khi kết-luận mình có cùng cảnh.

## SELF-CHECK sau khi áp

- [ ] `git check-ignore -v .claude/sessions/session-<N>` không-khớp (thư-mục phiên KHÔNG bị ignore).
- [ ] Cặp lệnh tạm-dừng/nối-lại + sổ ghi-trước đã có mặt TRƯỚC khi bật kit.
- [ ] Có khoá trần context-phiên (hoặc chấp-nhận default và ghi rõ).
- [ ] Tên thư-mục khớp `^session-\d+$`, N = ID phiên-LOGIC.
- [ ] Thử một phiên: tạm-dừng → tắt máy → nối-lại, đọc lại được context nén (đây là chỗ **fidelity-sau-nối-lại** — tự đo; xem Ghi-chú trung-thực bên dưới, hub cũng đang đo cùng chỗ này).

## Ghi chú trung thực

- **Nền là n=2.** Đã đúng **hai** phiên-logic sạch phía hub (hai lượt dogfood, owner chấm cả hai 10/10) — chưa đủ mẫu để nói "vững qua nhiều phiên". n vẫn nhỏ (hai lượt, một dự-án) — bạn tự đo phía bạn.
- **Lượt thứ nhất (run-1) được owner chấm cao — nhưng phạm-vi lời khen nằm ở CƠ-CHẾ, không phải ở fidelity-sau-nối-lại.** Owner ghi nguyên văn lý-do (dịch sát): *"đúng hoàn toàn các config của tao: session folder có context nén lúc start, để khi start xong tắt máy vẫn có thể đọc lại đc, có end, 3 lần pause-end đầy đủ và có nén context cập nhật, 5 snapshot đủ. Khi end chạy đủ các tầng audit dữ liệu."* — tức là khen **thư-mục + context nén + chốt-kết + ba lần tạm-dừng + năm chụp-nhanh + các tầng audit chạy đủ**. Đó là *cơ-chế đứng đúng chỗ*, chưa phải bằng-chứng *trí-nhớ khôi-phục đúng sau nối-lại*.
- **Lượt thứ hai (run-2) đã đóng sạch** — một phiên-logic ba cửa sổ, đủ điều-kiện hai-lượt-sạch; owner chấm "rất tốt".
- **Fidelity-sau-tạm-dừng/nối-lại: đã có phép đo chính-thức đầu tiên, đạt.** Ngay sau một cặp tạm-dừng/nối-lại, phía hub chạy bài kiểm khôi-phục trí-nhớ từ bản-đồ context + chụp-nhanh, đối-chiếu mạch việc — đạt. Đây là lần chạy **chính-thức đầu tiên** của phép đo này (trước đó lời khen mới ở phạm-vi cơ-chế đầu phiên); một điểm dữ-liệu, chưa phải chuỗi. Owner chấm cả hai lượt 10/10.
- Kit này là function-floor: tên lệnh, tên khoá trần, key-schema, chỗ đặt dòng nhịp-nợ = form, dự án tự quyết.

— ai_infra (hub), 2026-07-17

<!-- envelope-footer: from=ai_infra · to=all-fit · type=new · status=SẴN-PHÁT 2026-07-18 (gate hai-lượt-sạch ĐẠT + owner GO) · content_sha256 stamp SAU cổng review · sister tự adapt form theo hướng-dẫn-adap -->
