aisef 0.1.0__tar.gz

aisef-0.1.0/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: aisef
+Version: 0.1.0
+Summary: Khung SDLC cho agent: đầu vào là docs/requirements.md, đầu ra là code đã qua cổng kiểm
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# AI-SDLC
+
+Khung phát triển phần mềm bằng agent. Đầu vào của mỗi dự án là **một file**
+`docs/requirements.md`; đầu ra là một ứng dụng chạy được, kèm bằng chứng
+cho từng bước.
+
+Nguyên tắc nền, xuyên suốt mọi quyết định trong kho này:
+
+> **Cần phán đoán thì giao cho model. Cần đảm bảo thì viết code.**
+
+Viết PRD, thiết kế kiến trúc, dựng mockup, viết code — đều cần phán đoán,
+đều giao cho model. Còn "mọi yêu cầu phải có story phủ", "không được ghi
+ra ngoài phạm vi", "test phải xanh sau lần sửa cuối" — đều có đáp án đúng,
+nên đều là code. Hệ quả: **không bao giờ giao cho model việc giám sát
+chính nó.**
+
+## Cài
+
+```bash
+pip install aisef
+```
+
+Hoặc chạy từ bản sao kho nguồn:
+
+```bash
+git clone <repo> ai-sdlc && cd ai-sdlc && pip install -e .
+python3 -m unittest discover -s tests -q   # vài phút, không mở container (tests/__init__.py)
+AISDLC_TEST_DOCKER=1 python3 -m unittest tests.test_sandbox tests.test_tools -q   # thêm test Docker thật
+```
+
+Kho skill tham chiếu **không cần clone tay**: `aisdlc setup` tự lấy về
+`~/.cache/ai-sdlc/references` đúng commit mà `aisdlc/kit/catalog.json`
+ghim (khoảng 93 MB, một lần cho mọi dự án). Máy ngoại tuyến hoặc CI trỏ
+sang chỗ khác bằng `AISDLC_REFERENCES=/duong/dan`, hoặc dùng
+`aisdlc setup --no-fetch` để chỉ xài những gì đã có trên đĩa.
+
+Không có phụ thuộc Python nào ngoài thư viện chuẩn. Tuỳ chọn:
+`docker` (cách ly khi chạy test), `playwright` (trích hợp đồng thị giác
+từ mockup) — thiếu thì framework **nói thẳng là thiếu** chứ không giả vờ
+vẫn kiểm được.
+
+## Sáu bước
+
+```bash
+cd /duong/dan/du-an-cua-ban
+
+aisdlc doctor                       # môi trường có đủ chưa
+aisdlc setup                        # dò stack, nạp skill, sinh CLAUDE.md + AGENTS.md
+aisdlc compile                      # nối guard vào client (hook / plugin)
+
+aisdlc plan                         # PRD → kiến trúc → UX → epic → story
+aisdlc gates                        # xem cổng nào đang chờ người
+aisdlc review prd                   # đọc artifact
+aisdlc approve prd                  # duyệt
+
+aisdlc mockup                       # mỗi màn hình một HTML + hợp đồng thị giác
+aisdlc approve mockups
+aisdlc approve readiness
+
+aisdlc run                          # hiện thực: epic tuần tự, story song song
+aisdlc run --verify-only --story STORY-01-07   # kiểm lại ứng viên đã đóng băng, không mở phiên developer
+aisdlc qa                           # bộ kiểm định
+aisdlc devsecops                    # CI + Dockerfile + triển khai + runbook
+aisdlc pre-deploy                   # cổng cuối
+aisdlc report                       # báo cáo nghiệm thu + sổ hành vi + INDEX.md
+aisdlc evidence STORY-01-04         # lịch sử một story hay một hành vi (AC-…, FR-…, qa:e2e)
+aisdlc issues --format csv          # bảng gap/hồi quy từ sổ hành vi → _bmad-output/ISSUES.csv
+```
+
+Chạy nhanh không cần người duyệt: `aisdlc plan --auto-approve all`. Phê duyệt
+tự động **luôn** được ghi dấu `auto` để về sau truy được tài liệu nào chưa
+từng có người thật xem.
+
+## Sau khi có code
+
+```bash
+aisdlc doc vitest --topic coverage --story STORY-01-02
+```
+
+Tra tài liệu thật của thư viện (context7, có cache) thay vì đoán tên API; có
+`--story` thì lần tra vào bằng chứng. Khi yêu cầu đổi sau phát hành:
+
+```bash
+aisdlc change FR-3 "Slug phải giữ dấu gạch dưới"
+```
+
+Ghi vào `docs/requirements.md`, đánh dấu PRD (cổng `prd` và các cổng sau
+thành stale), sinh story delta `STORY-CH-01` với `covers=[FR-3]` — story cũ
+giữ nguyên `DONE`.
+
+```bash
+aisdlc improve --epic EPIC-01 --max-loops 3      # [--auto] không dừng ở cổng người
+```
+
+Vòng cải tiến theo bằng chứng (ADR-004 R3): QA → sổ hành vi → **một** story
+sửa cho một hành vi GAP/REOPENED (`STORY-RP-01` trong `EPIC-RP-01`, sinh bằng
+code) → `run` như story thường → QA → mốc `loops[]` + `LOOP-REPORT-<n>.md`.
+Dừng bằng code: hết gap, đủ `improve.max_loops`, cải thiện biên ≤ 0
+`improve.flat_loops` vòng liền, vượt `improve.cost_cap_usd`, hay story sửa bế
+tắc kế hoạch (trả người kèm lời reviewer). Trước mỗi vòng ≥ 2 cần
+`aisdlc approve improve` trừ `--auto`.
+
+```bash
+aisdlc run --verify-only --story STORY-01-07
+```
+
+Story trượt chỉ vì môi trường đo (e2e nhạy tải máy) thì không cần trả tiền
+cho một phiên developer để dựng lại mã đã có (ADR-004 R13): lượt kiểm-lại
+lấy ứng viên ở HEAD nhánh story, chạy lại đúng phép kiểm ✗/thiếu ở SHA ấy,
+giữ rà soát và bảo mật đã có ở cùng SHA, chấm đủ cổng; đạt thì merge như lượt
+thường, trượt thì `failed` và không ăn vào `run.max_retries`.
+
+## Cổng
+
+Tám cổng, mỗi cổng hai lớp. **Cổng máy** chạy trước — nó bắt được thứ máy
+bắt tốt hơn người (chu trình phụ thuộc, yêu cầu không kiểm chứng được,
+story không khai phạm vi ghi). **Cổng người** chạy sau, trên thứ đã sạch.
+
+Phê duyệt là **trạng thái trên đĩa**, không phải câu hỏi trong phiên chat:
+người duyệt có thể là người khác, lúc khác, trên máy khác. Bản ghi phê
+duyệt gắn với **băm nội dung** artifact — sửa tài liệu sau khi duyệt thì
+phê duyệt hết hiệu lực, và sửa tầng trên làm mọi tầng dưới thành `stale`.
+
+## Guard
+
+Tám guard, mỗi guard là một lệnh trả mã thoát, nối vào ba mốc vòng đời:
+
+| Mốc | Guard |
+|---|---|
+| trước mỗi tool | `write-scope` · `destructive` · `secret` · `git-stage` · `injection` · `process-ref` (luật 6: không mã story/epic trong nguồn) |
+| sau mỗi tool | `diff-scope` |
+| khi agent định dừng | `completion` |
+
+Guard nằm ở phía framework, không ở phía client — client không được tin.
+Cả Claude Code và OpenCode đều đã **chứng minh bằng phép thử trên agent
+thật** rằng guard chặn *trước* khi tool chạy, chứ không phải phát hiện
+sau. Client nào không gắn được guard tiền kiểm thì `aisdlc verify` chạy
+lại toàn bộ trên diff, và `aisdlc compile` ghi rõ mức bảo đảm thấp hơn
+vào báo cáo thay vì im lặng — năng lực là thứ được **khai và kiểm**, mặc
+định là "chưa chứng minh", không phải "chắc là được". Trong V1, OpenCode
+là client **hạng hai** theo quyết định V1: guard chặn được (hợp quy 7/7), và từ 2026-09-05 `--format json` cho luồng máy đọc được (tool, token, cost theo nhà cung cấp) — chưa lên hạng nhất vì chưa đủ số lần hợp quy hook ổn định; chi phí trước đó không đo
+được từ harness; nó không chặn phát hành.
+
+## Lỗi thật đã gặp
+
+Hai mươi lăm lỗi tìm bằng đo trên agent thật, xếp theo mười một lớp nguyên nhân kèm phép hồi quy: `docs/FAILURE-TAXONOMY.md`. Lỗi mới thì thêm một dòng vào đó cùng commit với test. Thay đổi theo phiên bản, kèm việc phải làm khi nâng cấp: `CHANGELOG.md`.
+
+## Hợp quy client
+
+Hook và plugin là tạo tác **biên dịch ra** — đúng cú pháp không có nghĩa là
+client chạy chúng. Bốn lỗi thật (31, 39, 40, 41) đều thuộc lớp này, và unit
+test không bắt được theo định nghĩa. Bộ hợp quy chạy bảy phép thử trên
+client thật, worktree thật, guard thật, `.claude/` không commit:
+
+```bash
+AISDLC_CONFORMANCE=1 python3 -m unittest tests.conformance -v
+```
+
+Kết quả ghép vào `docs/CONFORMANCE.md` — mỗi ô là một phiên agent, đọc từ
+đĩa (tệp còn/mất), từ luồng `tool_use` và bằng chứng guard tự ghi, không từ
+lời agent. Dự án thử và log thô từng phép giữ ở `.conformance/<client>/`
+(đổi bằng `AISDLC_CONFORMANCE_DIR`) để tra lại một ô ✗ mà không phải đoán.
+Bộ chạy **không** thừa hưởng biến `CLAUDE_*` của phiên gọi nó — chạy hợp
+quy từ bên trong một phiên Claude là chuyện có thật, và phiên con thừa hưởng
+cờ của phiên cha thì đo sai. Cổng
+phát hành của chính kho này đọc bảng đó bằng code
+(`AISDLC_RELEASE=1 python3 -m unittest tests.test_release_gate`): cột
+`claude` phải đủ năm ô ✅ và bảng không cũ hơn 14 ngày. OpenCode là hạng
+hai trong V1 — có cột, không chặn. CI: `.github/workflows/conformance.yml`
+chạy tuần.
+
+## Phát hành
+
+Gói phân phối tên **`aisef`** trên PyPI (module Python và lệnh vẫn là `aisdlc`), phát hành khi hoàn tất đợt 4 (quyết định 2026-09-05).
+Điều kiện đọc bằng lệnh, không bằng cảm giác:
+
+```bash
+python3 -m unittest discover -s tests -q && AISDLC_RELEASE=1 AISDLC_ACCEPTANCE=<dự án nghiệm thu> python3 -m unittest tests.test_release_gate -q
+```
+
+`AISDLC_ACCEPTANCE` trỏ vào dự án dogfood đã nghiệm thu (v0.1.0: `e9`, phạm vi
+EPIC-01): cổng đọc `pre-deploy-report.json` (đạt, có phạm vi, miễn có lý do)
+và phê duyệt `pre-deploy` trên đúng bản ấy. Không đặt thì bỏ qua có nêu tên —
+không tính là đạt.
+
+```bash
+uv build && uvx twine check dist/*
+```
+
+`.github/workflows/release.yml` publish bằng *trusted publishing* khi đẩy tag
+`v*` — không có token nào trong kho. Việc làm **một lần bằng tay**, bằng tài
+khoản tổ chức: tạo project `aisef` trên PyPI và khai trusted publisher
+(kho này · workflow `release.yml` · environment `pypi`). Sau đó:
+
+```bash
+git tag v0.1.0 && git push --tags
+```
+
+Kho hồi quy dogfood (`tests/dogfood/`, bật bằng `AISDLC_DOGFOOD=1`) dựng lại
+dự án thử `par` từ đầu vào trong kho và so với mốc đã đo — chạy trước mỗi tag.
+
+### Giới hạn đã biết của v0.1.0
+
+Khai ở đây vì mọi claim phải có bằng chứng; thứ chưa chứng minh gọi là chưa
+chứng minh (quyết định chủ đầu tư 2026-09-06, `docs/RELEASE-PLAN-v0.1.0.md` §0):
+
+- **Phạm vi nghiệm thu dogfood là EPIC-01 của `e9`** (7 story, `aisdlc
+  pre-deploy --epic EPIC-01`). EPIC-02..05 (16 story) chưa chạy — báo cáo ghi
+  "ngoài phạm vi", không phải "xong". `e9` chưa phải sản phẩm được nghiệm thu
+  hoàn chỉnh; nó là corpus nghiệm thu của framework.
+- **OpenCode là client hạng hai**: hợp quy 9/10 (C9 model từ chối, không kết
+  luận), không có đầu ra máy đọc ổn định; claim phát hành dựa trên Claude Code.
+- **Agent trong container chưa có cách ly credential** (S1 blocked): V1 chạy
+  agent trên host, chỉ kiểm định trong container; `doctor`/`pre-deploy` nêu
+  tên bảo đảm thiếu, không im lặng.
+- **`mutation` ở môi trường nghiệm thu là KHÔNG CHẠY ĐƯỢC** (công cụ chưa cài);
+  được miễn có lý do ở `verify.waiver_reason`, hiện ◇, không bao giờ thành ✅.
+  `image-scan` cùng loại (docker scout đòi đăng nhập, trivy/grype vắng).
+- **`skills.offer`/`skills.inline` tắt** (A/B không thấy gain), **`repo_map`
+  tắt** (`context.max_repo_map_chars = 0`, A/B hoãn sau v0.1.0).
+- **`coverage`**: harness đọc số từ runner (`--coverage`/`--cov`); dự án chưa
+  bật thì mục cổng là ○ chưa cấu hình, không phải đạt.
+
+## Khi cổng chặn
+
+Cổng chặn là framework đang làm việc, không phải framework hỏng. Ba ca hay
+gặp và cách xử đúng:
+
+| Cổng báo | Nghĩa là | Làm gì |
+|---|---|---|
+| `mockup còn N chỗ chưa chốt` | mockup gặp câu hỏi chưa ai trả lời và **đánh dấu** thay vì tự quyết | trả lời câu hỏi (thường nằm ở `open_questions` của PRD/UX), sửa tài liệu, dựng lại mockup |
+| `story đụng vào yêu cầu đang bị câu hỏi mở chặn` | epic gán một FR mà PRD ghi là chưa quyết được | trả lời câu hỏi, hoặc bỏ FR đó khỏi story |
+| `merge đụng …` | hai story cùng sửa một file | `write_scope` khai sai — sửa ở story, **không** gỡ conflict cho xong |
+
+`--force` có ở `approve` và `run` cho trường hợp cố ý bỏ qua. Dùng nó là
+một quyết định, và nó được ghi lại: bản ghi phê duyệt giữ ghi chú, báo cáo
+nghiệm thu hiện đúng trạng thái từng cổng.
+
+## Chạy song song
+
+Epic chạy tuần tự. Trong một epic, hai story chỉ được cùng đợt khi **hết
+phụ thuộc** *và* **phạm vi ghi rời nhau** — thiếu điều kiện thứ hai thì hai
+story cùng sửa một file và người thua là người merge sau. Mỗi story chạy
+trong worktree git riêng; merge tuần tự cuối đợt. Conflict lúc merge không
+được tự gỡ: nó là **bằng chứng `write_scope` khai sai**.
+
+## Cấu trúc
+
+```
+aisdlc/
+  cli/              bộ lệnh chia theo pha, mọi lệnh gọi-một-lần, không daemon
+  config.py         ngưỡng và cấu hình, có kiểu, có kiểm
+  clients/          Claude Code · OpenCode; năng lực được **khai**, không giả định
+  control/          cổng, phê duyệt, xếp lịch, worktree, chuẩn hoá tài liệu BMAD
+  harness/          prompt · tool · sandbox · guard · quan sát · map mockup
+  kit/              catalog skill, lọc bảo mật hai tầng, hiến pháp, prompt, skill riêng
+  phases/           plan · mockup · implement · run · qa · deploy · report
+docs/
+  SOLUTION.md              giải pháp tổng thể và vì sao chọn như vậy
+  EXECUTION-PLAN.md        kế hoạch thực thi, trạng thái từng hạng mục
+  REQUIREMENTS-EVIDENCE.md R1–R14 → test chạy được
+  SPIKE-REPORT.md          kết quả 7 spike kiểm chứng khả thi
+```
+
+## Bằng chứng, không tự khai
+
+Mọi cổng đọc `_bmad-output/evidence/{story}.jsonl` — lần chạy test, lần
+sửa file, lần gọi model kèm chi phí và độ trễ, lần đối chiếu mockup. Câu
+"đã hoàn thành" của agent không được tính là gì cả.
+
+Cụ thể, một story chỉ xong khi: test xanh **và** xanh sau lần sửa cuối ·
+lint sạch · thay đổi nằm trong phạm vi khai báo · màn hình thật dựng đủ
+component mockup đã hứa · rà soát độc lập (phiên khác, cấm sửa code) không
+còn mục chặn · không có test nào rỗng khẳng định.

aisef-0.1.0/README.md

@@ -0,0 +1,274 @@
+# AI-SDLC
+
+Khung phát triển phần mềm bằng agent. Đầu vào của mỗi dự án là **một file**
+`docs/requirements.md`; đầu ra là một ứng dụng chạy được, kèm bằng chứng
+cho từng bước.
+
+Nguyên tắc nền, xuyên suốt mọi quyết định trong kho này:
+
+> **Cần phán đoán thì giao cho model. Cần đảm bảo thì viết code.**
+
+Viết PRD, thiết kế kiến trúc, dựng mockup, viết code — đều cần phán đoán,
+đều giao cho model. Còn "mọi yêu cầu phải có story phủ", "không được ghi
+ra ngoài phạm vi", "test phải xanh sau lần sửa cuối" — đều có đáp án đúng,
+nên đều là code. Hệ quả: **không bao giờ giao cho model việc giám sát
+chính nó.**
+
+## Cài
+
+```bash
+pip install aisef
+```
+
+Hoặc chạy từ bản sao kho nguồn:
+
+```bash
+git clone <repo> ai-sdlc && cd ai-sdlc && pip install -e .
+python3 -m unittest discover -s tests -q   # vài phút, không mở container (tests/__init__.py)
+AISDLC_TEST_DOCKER=1 python3 -m unittest tests.test_sandbox tests.test_tools -q   # thêm test Docker thật
+```
+
+Kho skill tham chiếu **không cần clone tay**: `aisdlc setup` tự lấy về
+`~/.cache/ai-sdlc/references` đúng commit mà `aisdlc/kit/catalog.json`
+ghim (khoảng 93 MB, một lần cho mọi dự án). Máy ngoại tuyến hoặc CI trỏ
+sang chỗ khác bằng `AISDLC_REFERENCES=/duong/dan`, hoặc dùng
+`aisdlc setup --no-fetch` để chỉ xài những gì đã có trên đĩa.
+
+Không có phụ thuộc Python nào ngoài thư viện chuẩn. Tuỳ chọn:
+`docker` (cách ly khi chạy test), `playwright` (trích hợp đồng thị giác
+từ mockup) — thiếu thì framework **nói thẳng là thiếu** chứ không giả vờ
+vẫn kiểm được.
+
+## Sáu bước
+
+```bash
+cd /duong/dan/du-an-cua-ban
+
+aisdlc doctor                       # môi trường có đủ chưa
+aisdlc setup                        # dò stack, nạp skill, sinh CLAUDE.md + AGENTS.md
+aisdlc compile                      # nối guard vào client (hook / plugin)
+
+aisdlc plan                         # PRD → kiến trúc → UX → epic → story
+aisdlc gates                        # xem cổng nào đang chờ người
+aisdlc review prd                   # đọc artifact
+aisdlc approve prd                  # duyệt
+
+aisdlc mockup                       # mỗi màn hình một HTML + hợp đồng thị giác
+aisdlc approve mockups
+aisdlc approve readiness
+
+aisdlc run                          # hiện thực: epic tuần tự, story song song
+aisdlc run --verify-only --story STORY-01-07   # kiểm lại ứng viên đã đóng băng, không mở phiên developer
+aisdlc qa                           # bộ kiểm định
+aisdlc devsecops                    # CI + Dockerfile + triển khai + runbook
+aisdlc pre-deploy                   # cổng cuối
+aisdlc report                       # báo cáo nghiệm thu + sổ hành vi + INDEX.md
+aisdlc evidence STORY-01-04         # lịch sử một story hay một hành vi (AC-…, FR-…, qa:e2e)
+aisdlc issues --format csv          # bảng gap/hồi quy từ sổ hành vi → _bmad-output/ISSUES.csv
+```
+
+Chạy nhanh không cần người duyệt: `aisdlc plan --auto-approve all`. Phê duyệt
+tự động **luôn** được ghi dấu `auto` để về sau truy được tài liệu nào chưa
+từng có người thật xem.
+
+## Sau khi có code
+
+```bash
+aisdlc doc vitest --topic coverage --story STORY-01-02
+```
+
+Tra tài liệu thật của thư viện (context7, có cache) thay vì đoán tên API; có
+`--story` thì lần tra vào bằng chứng. Khi yêu cầu đổi sau phát hành:
+
+```bash
+aisdlc change FR-3 "Slug phải giữ dấu gạch dưới"
+```
+
+Ghi vào `docs/requirements.md`, đánh dấu PRD (cổng `prd` và các cổng sau
+thành stale), sinh story delta `STORY-CH-01` với `covers=[FR-3]` — story cũ
+giữ nguyên `DONE`.
+
+```bash
+aisdlc improve --epic EPIC-01 --max-loops 3      # [--auto] không dừng ở cổng người
+```
+
+Vòng cải tiến theo bằng chứng (ADR-004 R3): QA → sổ hành vi → **một** story
+sửa cho một hành vi GAP/REOPENED (`STORY-RP-01` trong `EPIC-RP-01`, sinh bằng
+code) → `run` như story thường → QA → mốc `loops[]` + `LOOP-REPORT-<n>.md`.
+Dừng bằng code: hết gap, đủ `improve.max_loops`, cải thiện biên ≤ 0
+`improve.flat_loops` vòng liền, vượt `improve.cost_cap_usd`, hay story sửa bế
+tắc kế hoạch (trả người kèm lời reviewer). Trước mỗi vòng ≥ 2 cần
+`aisdlc approve improve` trừ `--auto`.
+
+```bash
+aisdlc run --verify-only --story STORY-01-07
+```
+
+Story trượt chỉ vì môi trường đo (e2e nhạy tải máy) thì không cần trả tiền
+cho một phiên developer để dựng lại mã đã có (ADR-004 R13): lượt kiểm-lại
+lấy ứng viên ở HEAD nhánh story, chạy lại đúng phép kiểm ✗/thiếu ở SHA ấy,
+giữ rà soát và bảo mật đã có ở cùng SHA, chấm đủ cổng; đạt thì merge như lượt
+thường, trượt thì `failed` và không ăn vào `run.max_retries`.
+
+## Cổng
+
+Tám cổng, mỗi cổng hai lớp. **Cổng máy** chạy trước — nó bắt được thứ máy
+bắt tốt hơn người (chu trình phụ thuộc, yêu cầu không kiểm chứng được,
+story không khai phạm vi ghi). **Cổng người** chạy sau, trên thứ đã sạch.
+
+Phê duyệt là **trạng thái trên đĩa**, không phải câu hỏi trong phiên chat:
+người duyệt có thể là người khác, lúc khác, trên máy khác. Bản ghi phê
+duyệt gắn với **băm nội dung** artifact — sửa tài liệu sau khi duyệt thì
+phê duyệt hết hiệu lực, và sửa tầng trên làm mọi tầng dưới thành `stale`.
+
+## Guard
+
+Tám guard, mỗi guard là một lệnh trả mã thoát, nối vào ba mốc vòng đời:
+
+| Mốc | Guard |
+|---|---|
+| trước mỗi tool | `write-scope` · `destructive` · `secret` · `git-stage` · `injection` · `process-ref` (luật 6: không mã story/epic trong nguồn) |
+| sau mỗi tool | `diff-scope` |
+| khi agent định dừng | `completion` |
+
+Guard nằm ở phía framework, không ở phía client — client không được tin.
+Cả Claude Code và OpenCode đều đã **chứng minh bằng phép thử trên agent
+thật** rằng guard chặn *trước* khi tool chạy, chứ không phải phát hiện
+sau. Client nào không gắn được guard tiền kiểm thì `aisdlc verify` chạy
+lại toàn bộ trên diff, và `aisdlc compile` ghi rõ mức bảo đảm thấp hơn
+vào báo cáo thay vì im lặng — năng lực là thứ được **khai và kiểm**, mặc
+định là "chưa chứng minh", không phải "chắc là được". Trong V1, OpenCode
+là client **hạng hai** theo quyết định V1: guard chặn được (hợp quy 7/7), và từ 2026-09-05 `--format json` cho luồng máy đọc được (tool, token, cost theo nhà cung cấp) — chưa lên hạng nhất vì chưa đủ số lần hợp quy hook ổn định; chi phí trước đó không đo
+được từ harness; nó không chặn phát hành.
+
+## Lỗi thật đã gặp
+
+Hai mươi lăm lỗi tìm bằng đo trên agent thật, xếp theo mười một lớp nguyên nhân kèm phép hồi quy: `docs/FAILURE-TAXONOMY.md`. Lỗi mới thì thêm một dòng vào đó cùng commit với test. Thay đổi theo phiên bản, kèm việc phải làm khi nâng cấp: `CHANGELOG.md`.
+
+## Hợp quy client
+
+Hook và plugin là tạo tác **biên dịch ra** — đúng cú pháp không có nghĩa là
+client chạy chúng. Bốn lỗi thật (31, 39, 40, 41) đều thuộc lớp này, và unit
+test không bắt được theo định nghĩa. Bộ hợp quy chạy bảy phép thử trên
+client thật, worktree thật, guard thật, `.claude/` không commit:
+
+```bash
+AISDLC_CONFORMANCE=1 python3 -m unittest tests.conformance -v
+```
+
+Kết quả ghép vào `docs/CONFORMANCE.md` — mỗi ô là một phiên agent, đọc từ
+đĩa (tệp còn/mất), từ luồng `tool_use` và bằng chứng guard tự ghi, không từ
+lời agent. Dự án thử và log thô từng phép giữ ở `.conformance/<client>/`
+(đổi bằng `AISDLC_CONFORMANCE_DIR`) để tra lại một ô ✗ mà không phải đoán.
+Bộ chạy **không** thừa hưởng biến `CLAUDE_*` của phiên gọi nó — chạy hợp
+quy từ bên trong một phiên Claude là chuyện có thật, và phiên con thừa hưởng
+cờ của phiên cha thì đo sai. Cổng
+phát hành của chính kho này đọc bảng đó bằng code
+(`AISDLC_RELEASE=1 python3 -m unittest tests.test_release_gate`): cột
+`claude` phải đủ năm ô ✅ và bảng không cũ hơn 14 ngày. OpenCode là hạng
+hai trong V1 — có cột, không chặn. CI: `.github/workflows/conformance.yml`
+chạy tuần.
+
+## Phát hành
+
+Gói phân phối tên **`aisef`** trên PyPI (module Python và lệnh vẫn là `aisdlc`), phát hành khi hoàn tất đợt 4 (quyết định 2026-09-05).
+Điều kiện đọc bằng lệnh, không bằng cảm giác:
+
+```bash
+python3 -m unittest discover -s tests -q && AISDLC_RELEASE=1 AISDLC_ACCEPTANCE=<dự án nghiệm thu> python3 -m unittest tests.test_release_gate -q
+```
+
+`AISDLC_ACCEPTANCE` trỏ vào dự án dogfood đã nghiệm thu (v0.1.0: `e9`, phạm vi
+EPIC-01): cổng đọc `pre-deploy-report.json` (đạt, có phạm vi, miễn có lý do)
+và phê duyệt `pre-deploy` trên đúng bản ấy. Không đặt thì bỏ qua có nêu tên —
+không tính là đạt.
+
+```bash
+uv build && uvx twine check dist/*
+```
+
+`.github/workflows/release.yml` publish bằng *trusted publishing* khi đẩy tag
+`v*` — không có token nào trong kho. Việc làm **một lần bằng tay**, bằng tài
+khoản tổ chức: tạo project `aisef` trên PyPI và khai trusted publisher
+(kho này · workflow `release.yml` · environment `pypi`). Sau đó:
+
+```bash
+git tag v0.1.0 && git push --tags
+```
+
+Kho hồi quy dogfood (`tests/dogfood/`, bật bằng `AISDLC_DOGFOOD=1`) dựng lại
+dự án thử `par` từ đầu vào trong kho và so với mốc đã đo — chạy trước mỗi tag.
+
+### Giới hạn đã biết của v0.1.0
+
+Khai ở đây vì mọi claim phải có bằng chứng; thứ chưa chứng minh gọi là chưa
+chứng minh (quyết định chủ đầu tư 2026-09-06, `docs/RELEASE-PLAN-v0.1.0.md` §0):
+
+- **Phạm vi nghiệm thu dogfood là EPIC-01 của `e9`** (7 story, `aisdlc
+  pre-deploy --epic EPIC-01`). EPIC-02..05 (16 story) chưa chạy — báo cáo ghi
+  "ngoài phạm vi", không phải "xong". `e9` chưa phải sản phẩm được nghiệm thu
+  hoàn chỉnh; nó là corpus nghiệm thu của framework.
+- **OpenCode là client hạng hai**: hợp quy 9/10 (C9 model từ chối, không kết
+  luận), không có đầu ra máy đọc ổn định; claim phát hành dựa trên Claude Code.
+- **Agent trong container chưa có cách ly credential** (S1 blocked): V1 chạy
+  agent trên host, chỉ kiểm định trong container; `doctor`/`pre-deploy` nêu
+  tên bảo đảm thiếu, không im lặng.
+- **`mutation` ở môi trường nghiệm thu là KHÔNG CHẠY ĐƯỢC** (công cụ chưa cài);
+  được miễn có lý do ở `verify.waiver_reason`, hiện ◇, không bao giờ thành ✅.
+  `image-scan` cùng loại (docker scout đòi đăng nhập, trivy/grype vắng).
+- **`skills.offer`/`skills.inline` tắt** (A/B không thấy gain), **`repo_map`
+  tắt** (`context.max_repo_map_chars = 0`, A/B hoãn sau v0.1.0).
+- **`coverage`**: harness đọc số từ runner (`--coverage`/`--cov`); dự án chưa
+  bật thì mục cổng là ○ chưa cấu hình, không phải đạt.
+
+## Khi cổng chặn
+
+Cổng chặn là framework đang làm việc, không phải framework hỏng. Ba ca hay
+gặp và cách xử đúng:
+
+| Cổng báo | Nghĩa là | Làm gì |
+|---|---|---|
+| `mockup còn N chỗ chưa chốt` | mockup gặp câu hỏi chưa ai trả lời và **đánh dấu** thay vì tự quyết | trả lời câu hỏi (thường nằm ở `open_questions` của PRD/UX), sửa tài liệu, dựng lại mockup |
+| `story đụng vào yêu cầu đang bị câu hỏi mở chặn` | epic gán một FR mà PRD ghi là chưa quyết được | trả lời câu hỏi, hoặc bỏ FR đó khỏi story |
+| `merge đụng …` | hai story cùng sửa một file | `write_scope` khai sai — sửa ở story, **không** gỡ conflict cho xong |
+
+`--force` có ở `approve` và `run` cho trường hợp cố ý bỏ qua. Dùng nó là
+một quyết định, và nó được ghi lại: bản ghi phê duyệt giữ ghi chú, báo cáo
+nghiệm thu hiện đúng trạng thái từng cổng.
+
+## Chạy song song
+
+Epic chạy tuần tự. Trong một epic, hai story chỉ được cùng đợt khi **hết
+phụ thuộc** *và* **phạm vi ghi rời nhau** — thiếu điều kiện thứ hai thì hai
+story cùng sửa một file và người thua là người merge sau. Mỗi story chạy
+trong worktree git riêng; merge tuần tự cuối đợt. Conflict lúc merge không
+được tự gỡ: nó là **bằng chứng `write_scope` khai sai**.
+
+## Cấu trúc
+
+```
+aisdlc/
+  cli/              bộ lệnh chia theo pha, mọi lệnh gọi-một-lần, không daemon
+  config.py         ngưỡng và cấu hình, có kiểu, có kiểm
+  clients/          Claude Code · OpenCode; năng lực được **khai**, không giả định
+  control/          cổng, phê duyệt, xếp lịch, worktree, chuẩn hoá tài liệu BMAD
+  harness/          prompt · tool · sandbox · guard · quan sát · map mockup
+  kit/              catalog skill, lọc bảo mật hai tầng, hiến pháp, prompt, skill riêng
+  phases/           plan · mockup · implement · run · qa · deploy · report
+docs/
+  SOLUTION.md              giải pháp tổng thể và vì sao chọn như vậy
+  EXECUTION-PLAN.md        kế hoạch thực thi, trạng thái từng hạng mục
+  REQUIREMENTS-EVIDENCE.md R1–R14 → test chạy được
+  SPIKE-REPORT.md          kết quả 7 spike kiểm chứng khả thi
+```
+
+## Bằng chứng, không tự khai
+
+Mọi cổng đọc `_bmad-output/evidence/{story}.jsonl` — lần chạy test, lần
+sửa file, lần gọi model kèm chi phí và độ trễ, lần đối chiếu mockup. Câu
+"đã hoàn thành" của agent không được tính là gì cả.
+
+Cụ thể, một story chỉ xong khi: test xanh **và** xanh sau lần sửa cuối ·
+lint sạch · thay đổi nằm trong phạm vi khai báo · màn hình thật dựng đủ
+component mockup đã hứa · rà soát độc lập (phiên khác, cấm sửa code) không
+còn mục chặn · không có test nào rỗng khẳng định.

aisef-0.1.0/aisdlc/cli/__init__.py

@@ -0,0 +1,101 @@
+"""Giao diện dòng lệnh.
+
+Mọi lệnh đều **gọi-một-lần**: đọc trạng thái trên đĩa, làm việc, ghi lại,
+rồi thoát. Không lệnh nào giả định mình là tiến trình chính, không lệnh
+nào chạy nền. Đó là điều kiện để cùng bộ lệnh này dùng được ở hai chế độ
+(quyết định Đ2):
+
+* **driver-led** — script hoặc CI gọi ``aisdlc run``;
+* **agent-led** — chính agent gọi ``aisdlc next`` / ``verify`` / ``complete``
+  qua Bash, ngay trong phiên chat của Claude Desktop hay OpenCode.
+
+Quy ước mã thoát: ``0`` thành công · ``1`` lỗi dùng sai · ``2`` trạng thái
+chưa đạt (cổng chưa duyệt, doctor không đạt) — để CI phân biệt được
+"hỏng" với "chưa xong".
+
+Bố cục gói (chia theo pha, không đổi hành vi):
+
+* :mod:`._common` — mã thoát, gốc artifact, kho duyệt/trạng thái, adapter;
+* :mod:`.doctor` — lệnh ``doctor``;
+* :mod:`.plan` — cổng người + pha lập kế hoạch;
+* :mod:`.implement` — pha hiện thực và nghiệm thu;
+* :mod:`.harness` — dựng và vận hành harness;
+* :mod:`.parser` — bộ phân tích tham số và ``main``.
+
+Mọi tên module-level cũ được xuất lại ở đây, nên ``from aisdlc.cli import
+main`` và bạn bè vẫn chạy y như khi còn là một file.
+"""
+
+from __future__ import annotations
+
+from ._common import (
+    ARTIFACT_ROOT,
+    _GATE_MARK,
+    EXIT_NOT_READY,
+    EXIT_OK,
+    EXIT_USAGE,
+    _approvals,
+    _artifact_root,
+    _client,
+    _gate_arg,
+    _state,
+)
+from .doctor import _hook_paths_elsewhere, cmd_doctor
+from .harness import cmd_compile, cmd_doc, cmd_guard, cmd_init, cmd_setup, cmd_skill
+from .implement import (
+    _project_has_ui,
+    cmd_devsecops,
+    cmd_evidence,
+    cmd_predeploy,
+    cmd_qa,
+    cmd_report,
+    cmd_run,
+    cmd_status,
+    cmd_tool,
+    cmd_verify,
+)
+from .parser import build_parser, main
+from .plan import (
+    _preflight_lines,
+    cmd_approve,
+    cmd_auto_approve,
+    cmd_change,
+    cmd_gates,
+    cmd_mockup,
+    cmd_plan,
+    cmd_reject,
+    cmd_review,
+)
+
+__all__ = [
+    "ARTIFACT_ROOT",
+    "EXIT_NOT_READY",
+    "EXIT_OK",
+    "EXIT_USAGE",
+    "build_parser",
+    "cmd_approve",
+    "cmd_auto_approve",
+    "cmd_change",
+    "cmd_compile",
+    "cmd_devsecops",
+    "cmd_doc",
+    "cmd_doctor",
+    "cmd_evidence",
+    "cmd_gates",
+    "cmd_guard",
+    "cmd_init",
+    "cmd_mockup",
+    "cmd_plan",
+    "cmd_predeploy",
+    "cmd_qa",
+    "cmd_reject",
+    "cmd_report",
+    "cmd_review",
+    "cmd_run",
+    "cmd_setup",
+    "cmd_skill",
+    "cmd_status",
+    "cmd_tool",
+    "cmd_verify",
+    "main",
+]

aisef-0.1.0/aisdlc/cli/__main__.py

@@ -0,0 +1,9 @@
+"""Giữ nguyên `python -m aisdlc.cli` — trước khi tách, `cli.py` có khối
+``if __name__ == "__main__"`` làm đúng việc này."""
+
+import sys
+
+from . import main
+
+if __name__ == "__main__":
+    sys.exit(main())