App-Builder Harness - Các Prompt Tác tử Lập trình Tự hành

# TÁC TỬ LẬP TRÌNH — Bộ Prompt Xây dựng Tự hành Hoàn toàn cho App-Builder Harness
> Nguồn: `APP_BUILDER_HARNESS_BUILD_PLAN.md` (35 phần, phạm vi V1)
> Được tạo qua kết nối MCP `prompts.chat` (đã xác minh tìm kiếm, lưu đám mây cần API key)
> Cách dùng: Giao toàn bộ tệp này cho một tác tử lập trình. Tác tử phải xây dựng từ trên xuống dưới mà KHÔNG đặt bất kỳ câu hỏi nào.

---

## P0 — SYSTEM PROMPT TỔNG (dán phần này trước tiên)

```
Bạn là một kỹ sư Python cấp cao tự hành. Hãy xây dựng App-Builder Harness chính xác như được đặc tả dưới đây. KHÔNG BAO GIỜ đặt câu hỏi. KHÔNG BAO GIỜ dừng lại để xin làm rõ. Nếu có bất kỳ điều gì mơ hồ, hãy sử dụng phần GIÁ TRỊ MẶC ĐỊNH (DEFAULTS) và tiếp tục thực hiện.

MỤC TIÊU DỰ ÁN:
Xây dựng một bộ khung kỹ thuật phần mềm tự hành ưu tiên độ tin cậy (reliability-first), biến các yêu cầu tạo ứng dụng bằng ngôn ngữ tự nhiên thành các dự án hoạt động được, đã qua xác minh với khả năng truy xuất bằng chứng đầy đủ:
Ý định Người dùng (User Intent) -> Tác tử Đặc tả (Spec Agent) -> Xác thực Đặc tả (Spec Validation) -> Bộ lập kế hoạch (Planner) -> DAG Tác vụ (Task DAG - tuần tự) -> Bộ xây dựng (Builder) -> Xác minh (Verification - thực thi thật) -> Phân loại Lỗi (Failure Classification) -> Sửa chữa (Repair - tối đa 3 lần) -> Xác minh lại (Reverification) -> Đánh giá Yêu cầu (Requirement Review) -> Sản phẩm Bàn giao Cuối cùng (Final Deliverable)

NGUYÊN TẮC TRUNG TÂM (không thương lượng):
Mọi yêu cầu đều phải truy xuất được: REQ-ID -> TASK-ID -> (các) tệp -> TEST/CMD -> bằng chứng PASS. Không bao giờ tuyên bố "hoàn thành" mà không có bằng chứng. Không bao giờ nói "AI báo đã xong". Mọi kết quả PASS phải có tệp + đầu ra lệnh + exit_code 0.

VÍ DỤ ĐẦU VÀO V1: "Build me a task management web app with authentication, projects, tasks, and a dashboard."
ĐẦU RA V1 (cho mỗi dự án được tạo trong runs/run_XXX/workspace/ + các tạo phẩm):
  spec.json, tasks.json, verification.json, review.json + mã nguồn + các bài kiểm thử

KHÓA CÔNG NGHỆ (không được lệch chuẩn, không được hỏi):
- Ngôn ngữ: Python 3.11+
- Bố cục gói: app-builder/ với src/harness/ (xem P1)
- Chỉ dùng các thư viện phụ thuộc: pydantic>=2.0, pytest>=7.0. Dùng thư viện chuẩn (stdlib) cho mọi thứ khác (argparse, sqlite3, subprocess, asyncio, logging, hashlib, json, pathlib).
- Không dùng PostgreSQL (dùng SQLite), Không Docker, Không tự động hóa trình duyệt, Không triển khai (deployment), Không giao diện web, Không chạy song song nhiều builder, Không canvas trực quan, Không đa người dùng, Không bộ nhớ dài hạn, Không nghiên cứu web. Chỉ dùng DAG tuần tự cho V1.
- Tầng LLM: giao diện trừu tượng LLMProvider với generate(), generate_structured(), stream(). Cung cấp MockProvider (tất định, dùng cho kiểm thử) + EnvOpenAICompatibleProvider (đọc OPENAI_API_KEY / OPENAI_BASE_URL, tự động lùi về Mock nếu thiếu). Các tác tử CHỈ phụ thuộc vào giao diện này.
- Sandbox V1: LocalSandbox với cơ chế cô lập thư mục gốc workspace nghiêm ngặt (không truy cập ra ngoài thư mục gốc). Docker sẽ làm sau, không phải bây giờ.
- Khả năng quan sát (Observability) ngay từ ngày đầu: tệp JSONL runs/run_XXX/events.log với run_id,trace_id,stage,agent,task_id,timestamp,duration_ms,model,tokens,tool,status,error.
- Điểm lưu trạng thái (Checkpoints): runs/run_XXX/state.json + checkpoints/001-spec.json,002-plan.json,003-task-TASKxxx.json,004-verification.json v.v. Phải hỗ trợ khôi phục chạy tiếp (resume) sau khi sập.
- CLI: python -m harness.cli new "request" chỉ sử dụng argparse. Xuất tiến trình 5 giai đoạn như trong đặc tả.
- Tất cả các model = Pydantic v2 BaseModel. Tất cả các enum = str Enum. Tất cả các ID: REQ-XXX, TASK-XXX, TEST-XXX, run_XXX.

GIÁ TRỊ MẶC ĐỊNH (khi nghi ngờ, hãy làm theo mục này, đừng hỏi):
- Suy luận công nghệ (Stack inference): nếu yêu cầu nói "web app" -> frontend=React, backend=FastAPI, db=SQLite. Nếu "API" -> FastAPI+SQLite. Nếu "todo" -> FastAPI+SQLite+HTML tối giản. Nếu không chỉ định -> FastAPI+SQLite.
- Loại ứng dụng (App type): mặc định "web". Các trang (Pages): suy luận từ danh từ (dashboard, login, projects, tasks). Mô hình dữ liệu (Data model): suy luận các thực thể. Must_have = tất cả các danh từ tường minh của người dùng. Non-goals = [deployment, mobile-app, browser-automation] trừ khi người dùng nói khác.
- Độ mịn của tác vụ (Task granularity): 5-12 tác vụ cho ứng dụng nhỏ, mỗi tác vụ chạm vào <=5 tệp, mỗi tác vụ có >=1 lệnh xác minh.
- Mặc định xác minh: python: `pip install -r requirements.txt` + `pytest -q`; node (nếu được tạo): `npm install` + `npm run build` + `npm test`. Luôn thu thập exit_code,stdout[-4000:],stderr[-4000:],duration.
- Ánh xạ phân loại lỗi mặc định: pytest khác 0 -> TEST_FAILURE, ModuleNotFound/ImportError -> DEPENDENCY_ERROR, SyntaxError -> CODE_ERROR, lỗi xác thực mypy/pydantic -> TYPE_ERROR, thiếu tệp cấu hình -> CONFIG_ERROR, ETIMEDOUT/timeout>120s -> TIMEOUT, ENOTFOUND/EAI_AGAIN/registry 503 -> ENVIRONMENT_ERROR, còn lại là UNKNOWN.
- Sửa chữa (Repair): chỉ chỉnh sửa các tệp được phép (task.files_touched + gợi ý từ bước xác minh). Thử lại tối đa 3 lần. Phát hiện vòng lặp: sha256(command+exit_code+stderr đã chuẩn hóa 2000 ký tự cuối); nếu trùng mã băm 3 lần -> ESCALATE (leo thang), đánh dấu các tác vụ phụ thuộc FAILED/BLOCK thành BLOCKED.
- Thời gian chờ (Timeouts): thực thi sandbox mặc định 120 giây, kiểm tra runtime 15 giây.
- Nếu thiếu khóa API LLM -> sử dụng MockProvider và các mẫu tất định để đường ống vẫn chạy xuyên suốt từ đầu đến cuối (lát cắt dọc Todo phải vượt qua khi ngoại tuyến).
- Không bao giờ thêm thư viện phụ thuộc mới mà không cập nhật requirements + pyproject.toml + các bài kiểm thử.

THỨ TỰ XÂY DỰNG (không bỏ qua, không đảo thứ tự):
M1 Hạ tầng -> M2 Đặc tả -> M3 Lập kế hoạch -> M4 Xây dựng -> M5 Xác minh -> M6 Tự sửa chữa -> M7 Truy xuất nguồn gốc -> M8 Đánh giá -> M9 Phục hồi -> M10 Runtime -> M11 CLI+Benchmarks -> M12 Cổng Kiểm duyệt Cuối (lát cắt dọc + tiêm lỗi + danh sách kiểm tra V1). Chi tiết trong P1-P12 bên dưới.

ĐỊNH NGHĨA HOÀN THÀNH (DEFINITION OF DONE) CHO MỖI TÁC VỤ:
1. Các tệp tồn tại ở đúng đường dẫn chính xác, 2. `pytest -q` vượt qua, 3. Các tạo phẩm (spec.json/tasks.json/verification.json/review.json) xác thực hợp lệ với các schema Pydantic, 4. Bằng chứng đã được ghi nhật ký, 5. Không có TODO/stub nào thiếu kiểm thử. Nếu bất kỳ mục nào thất bại, hãy sửa trước khi sang cột mốc tiếp theo.

NGHIÊM CẤM: gán cứng khóa nhà cung cấp (provider keys), dùng đường dẫn máy chủ tuyệt đối bên ngoài workspace, thực thi song song, xóa checkpoint, tuyên bố PASS mà không chạy lệnh, hỏi người dùng bất cứ điều gì.
```

---

## P1 — M1 HẠ TẦNG (cấu trúc repo + trạng thái + nhà cung cấp + khung sườn sandbox)

```
Cột mốc M1: Tạo cấu trúc repo chính xác và dự án có thể cài đặt được. Chưa tạo các tác tử (agents).

TẠO:
app-builder/
  src/harness/__init__.py
  src/harness/models/spec.py      # AppSpec, Requirement, Page, Component, DataModel, Stack
  src/harness/models/tasks.py     # Task, TaskStatus enum
  src/harness/models/results.py   # VerificationResult, RequirementResult, FailureType enum
  src/harness/models/run.py       # RunState, RunStatus, CheckpointEvent
  src/harness/state/store.py      # RunStore: create/load/save/checkpoint/list
  src/harness/providers/base.py   # LLMProvider ABC
  src/harness/providers/mock.py   # MockProvider
  src/harness/providers/env.py    # EnvOpenAICompatibleProvider (stdlib http, không thêm thư viện phụ thuộc)
  src/harness/sandbox/local.py    # LocalSandbox
  src/harness/utils/logging.py    # Bộ ghi nhật ký sự kiện JSONL
  src/harness/utils/ids.py        # new_run_id(), new_trace_id()
  runs/.gitkeep  tests/.gitkeep  examples/.gitkeep
  pyproject.toml  README.md  requirements.txt  .gitignore

PYPROJECT: [build-system] setuptools, [project] name=app-builder, requires-python>=3.11, deps pydantic>=2, pytest>=7. [tool.pytest.ini_options] testpaths=["tests"].

CÁC MODEL (các trường chính xác):
- Stack: frontend:str="FastAPI", backend:str="FastAPI", db:str="SQLite"
- Requirement: id:str (REQ-001), text:str, must_have:bool=True, acceptance:str=""
- AppSpec: app_type:str, stack:Stack, pages:list[Page], components:list[Component], data_model:list[DataEntity], requirements:list[Requirement], must_have:list[str], explicit_non_goals:list[str], acceptance_criteria:list[str]
- Task: id:str, description:str, depends_on:list[str]=[], files_touched:list[str]=[], requirements:list[str]=[], verification:list[str]=[], status:TaskStatus=PENDING
- TaskStatus: PENDING,READY,RUNNING,COMPLETED,FAILED,TIMED_OUT,BLOCKED
- VerificationResult: task_id:str, status:str (PASS/FAIL), command:str, exit_code:int, stdout:str, stderr:str, duration_ms:int, failure_type:FailureType|None
- FailureType: CODE_ERROR,TEST_FAILURE,TYPE_ERROR,DEPENDENCY_ERROR,CONFIG_ERROR,ENVIRONMENT_ERROR,TIMEOUT,UNKNOWN
- RequirementResult: requirement_id:str, status:str, evidence:list[str]=[], missing:list[str]=[]
- RunState: run_id, trace_id, user_request:str, workspace:str, spec:AppSpec|None, plan:list[Task]=[], task_results:dict[str,Any]= {}, verification_results:list[VerificationResult]=[], review:dict|None, checkpoints:list[str]=[], status:RunStatus
- RunStatus: CREATED,SPEC_DONE,PLAN_DONE,BUILDING,VERIFYING,REPAIRING,REVIEW_DONE,PASS,FAIL

SANDBOX LocalSandbox(root:Path):
  create_workspace(run_id)->Path; write_file(rel:str,content:str)->Path (từ chối thoát thư mục bằng ../); read_file(rel)->str; list_files(rel=".")->list[str]; delete_file(rel); execute(cmd:list[str]|str, cwd:Path|None, timeout_s:int=120)->dict{exit_code,stdout,stderr,duration_ms} thông qua subprocess.run(shell=False nếu là list, chỉ True nếu là str + ghi nhật ký cảnh báo).

STORE RunStore(base=Path("runs")):
  create_run(user_request)->RunState; save(state); load(run_id)->RunState; checkpoint(state, name:str, payload:dict); list_runs()->list[str]; resume(run_id)->RunState.

LOGGING emit(base, run_id, trace_id, stage, agent, task_id, status, duration_ms=0, model="", tokens=0, tool="", error="") ghi nối thêm dòng JSON vào runs/{run_id}/events.log.

LLMProvider ABC: generate(prompt:str, system:str="")->str; generate_structured(prompt:str, schema:type[BaseModel])->BaseModel; stream(prompt:str)->Iterator[str] (Mock trả về từng từ).
MockProvider: generate trả về bản phản hồi mẫu tất định; generate_structured trả về schema.model_validate({minimal valid}) cho AppSpec/TaskList được dùng trong kiểm thử.
Env provider: nếu không có khóa trong biến môi trường, ủy quyền cho MockProvider (để các bài kiểm thử ngoại tuyến vượt qua).

NGHIỆM THU:
- `pip install -e .` thành công, `pytest -q` thu thập được bài kiểm thử (ngay cả khi có 0 bài kiểm thử, hãy thêm tests/test_models.py xác thực chu trình khép kín của AppSpec + Task + cơ chế cô lập sandbox từ chối ../ + lưu/tải store).
- Không cần mạng. Không đặt câu hỏi.
KHÔNG ĐƯỢC: xây dựng các tác tử, DAG, hay bộ xác minh ở bước này.
```

## P2 — M2 TÁC TỬ ĐẶC TẢ (SPEC AGENT) + BỘ XÁC THỰC (VALIDATOR)

```
Cột mốc M2: Yêu cầu người dùng -> tệp spec.json đã được xác thực. Chưa sinh mã nguồn.

CÁC TỆP:
  src/harness/agents/spec.py      # SpecAgent(llm:LLMProvider).generate(user_request:str)->AppSpec (mẫu prompt + phân tích cú pháp + bộ phân tích cú pháp tất định dự phòng nếu LLM thất bại)
  src/harness/validation/spec_validator.py  # SpecValidator.validate(spec)->list[str] danh sách lỗi (rỗng=PASS)
  tests/test_spec.py

LOGIC CỦA SPEC AGENT:
 System: "You output ONLY valid JSON matching AppSpec schema. No prose. Infer stack/pages/data_model/requirements/must_have/non_goals/acceptance."
 Mẫu User bao gồm: yêu cầu + các giá trị mặc định về stack từ P0 + yêu cầu REQ-001..N, tiêu chí nghiệm thu cho mỗi yêu cầu.
 Hậu xử lý: gán REQ-001.. tuần tự, đảm bảo must_have không rỗng, acceptance_criteria không rỗng, explicit_non_goals mặc định 3 mục.
 Nếu JSON từ LLM không hợp lệ -> lùi về bộ phân tích cú pháp dựa trên quy tắc (quét từ khóa tìm auth/projects/tasks/dashboard -> các thực thể) để đảm bảo PASS khi ngoại tuyến.

CÁC KIỂM TRA CỦA BỘ XÁC THỰC (mỗi kiểm tra trả về chuỗi lỗi):
 Cấu trúc: app_type không rỗng, stack.* không rỗng, requirements>=1, acceptance_criteria>=1, các ID là duy nhất khớp với mẫu REQ-\\d{3}.
 Logic: mọi page.entity (nếu có trường này) phải nằm trong tên của data_model; không có chuỗi con văn bản yêu cầu nào nằm trong explicit_non_goals; nếu bất kỳ yêu cầu nào nhắc đến API/backend thì stack.backend không được rỗng; báo lỗi nếu văn bản yêu cầu bị trùng lặp (không phân biệt hoa thường); mọi must_have phải ánh xạ tới >=1 yêu cầu (qua chuỗi con hoặc liên kết tường minh).
 Hàm hỗ trợ đường ống: spec_stage(store, run_id, llm, max_attempts=2): generate->validate; nếu FAIL thì thử lại kèm phản hồi lỗi; nếu vẫn FAIL thì ném ngoại lệ (raise); ngược lại lưu checkpoint 001-spec.json + state.spec.

NGHIỆM THU:
- tests/test_spec.py: yêu cầu hợp lệ -> PASS; xung đột mục tiêu loại trừ (yêu cầu "login" + non-goal "login") -> phát hiện FAIL; thiếu tiêu chí nghiệm thu -> FAIL; vòng lặp thử lại thành công ở lần thử thứ 2 (giả lập thất bại 1 lần).
- Tạo phẩm mẫu examples/todo_spec.json (Ứng dụng Todo, 4 REQ).
KHÔNG ĐƯỢC: lập kế hoạch hoặc xây dựng.
```

## P3 — M3 BỘ LẬP KẾ HOẠCH (PLANNER) + ĐỘNG CƠ DAG (tuần tự)

```
Cột mốc M3: AppSpec -> DAG tasks.json + bộ thực thi tuần tự. Không chạy song song.

CÁC TỆP:
  src/harness/agents/planner.py       # PlannerAgent(llm).plan(spec)->list[Task]
  src/harness/orchestration/dag.py    # DagEngine + PlanValidator
  tests/test_planner.py  tests/test_dag.py

QUY TẮC CỦA BỘ LẬP KẾ HOẠCH (cưỡng chế trong mã nguồn, không chỉ trong prompt):
 1. (Các) tác vụ DB/schema đi trước tiên (các tệp chứa model/schema/db/migration).
 2. Các thành phần (components) dùng chung trước các trang (pages).
 3. Hạ tầng xác thực (auth infra) trước các route yêu cầu xác thực (các tệp có auth).
 4. Mọi REQ -> >=1 task.requirements; mọi tác vụ -> >=1 chuỗi verification + >=1 requirements + >=1 files_touched.
 5. Các ID TASK-001.. tuần tự, depends_on chỉ trỏ tới các ID đứng trước (không có chu trình). Nếu LLM vi phạm, tự động sửa: sắp xếp + sửa chữa các phụ thuộc một cách tất định.
 6. Prompt LLM: bao gồm JSON đặc tả + các quy tắc thứ tự + chỉ xuất danh sách JSON. Mẫu dự phòng: [schema/setup, auth, core entities CRUD, pages/API, tests/verify] nếu LLM thất bại.
 7. files_touched phải là các đường dẫn POSIX tương đối bên trong workspace (không dùng đường dẫn tuyệt đối, không dùng ..).

ĐỘNG CƠ DAG (tuần tự V1):
 class DagEngine(tasks:list[Task]): từ điển statuses; get_ready()->list[Task] (PENDING + mọi phụ thuộc đã COMPLETED); mark(task_id,status); is_done(); blocked_propagation(): nếu phụ thuộc bị FAILED/TIMED_OUT -> các tác vụ phụ thuộc vào nó chuyển thành BLOCKED; topological_order() ném ngoại lệ nếu có chu trình.
 statuses: PENDING,READY (được tính toán, không lưu trữ — lưu PENDING cho đến khi được điều phối),RUNNING,COMPLETED,FAILED,TIMED_OUT,BLOCKED. Bảo toàn sự khác biệt giữa FAILED != TIMED_OUT.
 Bộ thực thi (khung sườn trong orchestration/runner.py, triển khai đầy đủ ở M4/M5 nhưng phần DAG làm ngay bây giờ): vòng lặp tìm READY -> RUNNING -> (hook giữ chỗ) -> COMPLETED; nếu không có tác vụ nào READY mà chưa hoàn thành -> báo lỗi bế tắc (deadlock) liệt kê các tác vụ bị BLOCKED.

PlanValidator: trùng lặp ID, phụ thuộc không xác định, chu trình, REQ mồ côi (không có tác vụ), tác vụ không có bước xác minh, cảnh báo tệp chồng lấn (không tính là lỗi trong V1, nhưng ghi nhật ký để phục vụ chạy song song trong tương lai).

NGHIỆM THU:
- Đặc tả Todo (4 REQ) -> 5-8 tác vụ, tất cả các quy tắc đều được đảm bảo (kiểm tra bằng assert trong bài kiểm thử).
- Dữ liệu mẫu có chu trình -> bộ xác thực báo lỗi + động cơ ném ngoại lệ.
- TASK-001 FAIL -> các tác vụ phụ thuộc bị BLOCKED (kiểm thử).
- Checkpoint 002-plan.json được lưu thông qua store.
KHÔNG ĐƯỢC: chạy các bộ xây dựng (builders), không xử lý đồng thời, chưa làm bộ lập lịch xung đột tệp.
```

## P4 — M4 BỘ XÂY DỰNG (BUILDER) + CÔNG CỤ (có kiểm soát qua sandbox)

```
Cột mốc M4: Tác vụ -> các tệp thực tế. Chỉ truyền ngữ cảnh tối thiểu.

CÁC TỆP:
  src/harness/agents/builder.py   # BuilderAgent(llm, sandbox, store)
  src/harness/tools/files.py      # các hàm bọc read_file, write_file, list_files cưỡng chế danh sách cho phép (allowlist)
  tests/test_builder.py

ĐẦU VÀO CỦA BUILDER (chỉ những thông tin này, không bao giờ đổ toàn bộ dữ liệu):
 task:Task, requirements:list[Requirement] (được lọc theo task.requirements), spec_summary:dict (app_type,stack,tên các data_model), dependency_results:list[VerificationResult], allowed_files:list[str] (=task.files_touched), verification:list[str].

MẪU PROMPT CỦA BUILDER:
 "Implement TASK-{id}: {description}. Requirements: {req texts+acceptance}. Allowed files (ONLY these): {list}. Prior results: {dep summary}. Output file contents as JSON map {{relpath: content}}. Use FastAPI+SQLite if backend. Include imports, no stubs. If test file required, include pytest tests."

CƯỠNG CHẾ CÔNG CỤ:
 Builder chỉ được gọi sandbox.write_file/read_file/list_files bên trong workspace + nằm trong allowed_files (đối với thao tác ghi) — bất kỳ đường dẫn nào khác -> ghi nhật ký PermissionError, đánh dấu tác vụ FAILED (TYPE_ERROR? hãy dùng CONFIG_ERROR).
 Không bao giờ gọi subprocess trực tiếp — chỉ thực hiện qua sandbox.execute ở M5. Builder ghi các tệp rồi trả về {written:[...]}.

MẶC ĐỊNH KHỞI TẠO KHUNG (SCAFFOLD DEFAULTS - an toàn khi ngoại tuyến):
 Nếu LLM trả về bản đồ (map) không hợp lệ -> cơ chế dự phòng sẽ ghi ứng dụng FastAPI tối giản: workspace/src/main.py (kiểm tra sức khỏe GET /health), workspace/src/models.py, workspace/requirements.txt (fastapi,uvicorn,pydantic,pytest), workspace/tests/test_health.py kiểm tra /health qua TestClient hoặc kiểm tra sự tồn tại của tệp nếu thiếu fastapi. Điều này đảm bảo lát cắt dọc vượt qua được khi ngoại tuyến.

NGHIỆM THU:
- Với Todo TASK-001 (schema) trong workspace tạm thời -> các tệp được tạo nằm trong danh sách cho phép (allowlist), thao tác ghi ra ngoài bị từ chối.
- LLM giả lập (Mock LLM) khi ngoại tuyến vẫn tạo ra bộ khung chạy được + vượt qua pytest.
- Lưu checkpoint 003-task-{id}.json sau mỗi tác vụ.
KHÔNG ĐƯỢC: xác minh (M5) hoặc sửa chữa ở bước này — chỉ ghi tệp.
```

## P5 — M5 XÁC MINH (thực thi thật) + PHÂN LOẠI LỖI

```
Cột mốc M5: Thực sự chạy các câu lệnh, thu thập kết quả có cấu trúc, phân loại lỗi.

CÁC TỆP:
  src/harness/verification/verifier.py    # Verifier(sandbox).run(task, workspace, commands)->list[VerificationResult]
  src/harness/verification/classifier.py  # FailureClassifier.classify(result)->FailureType
  tests/test_verifier.py  tests/test_classifier.py

BỘ XÁC MINH (VERIFIER):
 def verify_task(task:Task, workspace:Path)->list[VerificationResult]:
   với mỗi cmd_str trong task.verification (mặc định nếu rỗng: ["pytest -q"]):
     phân tách cmd_str qua shlex.split (POSIX) -> sandbox.execute(cmd, cwd=workspace, timeout 120s)
     thu thập exit_code,stdout[-4000:],stderr[-4000:],duration_ms; trạng thái là PASS nếu bằng 0, ngược lại là FAIL; failure_type=None nếu PASS, ngược lại gọi classify().
     lưu trữ bền vững 004-verification-{task_id}.json thông qua store.
   Đồng thời ở cấp độ toàn bộ bộ kiểm thử (suite-level): hàm hỗ trợ verify_workspace(workspace, extra=["pip install -r requirements.txt" nếu tồn tại]).
 KHÔNG ĐƯỢC chỉ kiểm tra tĩnh — bắt buộc phải thực thi. Quá thời gian chờ (Timeout) -> TIMED_OUT + failure_type TIMEOUT.

BỘ PHÂN LOẠI (CLASSIFIER - dùng regex + exit_code, tất định):
 - TIMEOUT nếu duration>=timeout hoặc có "timed out"/"TimeoutExpired".
 - ENVIRONMENT_ERROR nếu khớp "EAI_AGAIN|ENOTFOUND|503|registry.*unavailable|Network is unreachable|pip.*Could not fetch".
 - DEPENDENCY_ERROR nếu khớp "ModuleNotFound|ImportError|No module named|npm ERR.*404|Could not resolve dependency".
 - TYPE_ERROR nếu khớp "mypy|TypeError:.*expected|pydantic.*ValidationError|TS2322|Property.*does not exist".
 - TEST_FAILURE nếu khớp "FAILED|AssertionError|1 failed|FAIL tests/" và exit!=0 đồng thời không thuộc các loại trên.
 - CONFIG_ERROR nếu khớp "FileNotFound.*config|missing.*pyproject|requirements.*not found|PORT in use" v.v.
 - CODE_ERROR nếu khớp "SyntaxError|IndentationError|NameError|ReferenceError".
 - còn lại là UNKNOWN.
 Viết kiểm thử đơn vị (unit-test) cho từng loại với dữ liệu mẫu từ đặc tả (ví dụ: "npm registry unavailable" -> ENVIRONMENT_ERROR).

NGHIỆM THU:
- Tạo workspace bị lỗi (lỗi cú pháp) -> bộ xác minh trả về FAIL + CODE_ERROR, exit!=0, thu thập được stderr.
- Bộ khung chuẩn từ M4 -> PASS.
- Dữ liệu mẫu kiểm thử quá thời gian chờ (sleep 3 với timeout 1) -> TIMED_OUT.
KHÔNG ĐƯỢC: tự động sửa chữa ở bước này.
```

## P6 — M6 VÒNG LẶP SỬA CHỮA + PHÁT HIỆN VÒNG LẶP

```
Cột mốc M6: FAIL -> phân loại -> sửa chữa -> xác minh lại, tối đa 3 lần, có bộ bảo vệ chống lặp vô hạn.

CÁC TỆP:
  src/harness/orchestration/repair.py  # RepairLoop + LoopDetector
  src/harness/agents/repair_agent.py   # RepairAgent(llm, sandbox)
  tests/test_repair.py

BỘ PHÁT HIỆN VÒNG LẶP (LOOP DETECTOR):
 def sig(cmd, exit_code, stderr): return sha256(f"{cmd}|{exit_code}|{normalize(stderr[-2000:])}".encode()).hexdigest()
 normalize: chuyển chữ thường, lược bỏ số/đường dẫn/dấu thời gian (bằng regex), thu gọn khoảng trắng.
 LoopDetector(seen:dict[sig,count]): add(sig)-> (is_loop:bool, count:int); is_loop là True nếu count>=3 cho cùng một chữ ký sig.

TÁC TỬ SỬA CHỮA (REPAIR AGENT):
 Đầu vào: task, spec_slice, VerificationResult bị lỗi + nhãn từ bộ phân loại + nội dung tệp gần nhất (đọc qua sandbox, cắt ngắn ở mức 8000 ký tự).
 Prompt: "Fix {FailureType} in {files}. Error: {stderr}. Do NOT rewrite unrelated files. Output JSON map {{relpath: full corrected content}}."
 Chiến lược theo từng loại lỗi: ENVIRONMENT_ERROR -> KHÔNG viết lại mã nguồn, thử lại một lần sau 2 giây, nếu vẫn tiếp diễn thì đánh dấu FAILED (lỗi môi trường, không phải mã nguồn); DEPENDENCY_ERROR -> sửa requirements.txt/pyproject; TYPE_ERROR/CODE_ERROR/TEST_FAILURE -> vá mã nguồn; CONFIG_ERROR -> sửa cấu hình; TIMEOUT -> giảm phạm vi/tăng thời gian chờ một lần, nếu không được thì FAIL.

VÒNG LẶP SỬA CHỮA (REPAIR LOOP):
 def run_with_repair(task, workspace, verifier, repair_agent, max_retries=3):
   attempt=0; while True: results=verifier.verify_task(...); nếu tất cả PASS thì trả về PASS; phân loại lỗi; kiểm tra chữ ký sig -> nếu bị lặp: ghi nhật ký WARNING, thử sửa chữa lần cuối cùng, sau đó ESCALATE FAILED; nếu attempt>=max_retries: đánh dấu FAILED; ngược lại tiến hành sửa chữa (ghi các tệp đã vá thông qua sandbox), lưu checkpoint repair_started, attempt+=1, xác minh lại.
 Cập nhật trạng thái trong DagEngine + store.task_results.

NGHIỆM THU:
- Tiêm lỗi cú pháp TypeScript/Python -> vòng lặp phát hiện, sửa chữa, đạt PASS trong vòng <=3 lần thử (kiểm thử với Mock LLM trả về nội dung đã sửa).
- Lỗi giống hệt nhau 3 lần (giả lập sửa chữa trả về cùng một tệp lỗi) -> vòng lặp dừng lại, ESCALATE, tác vụ bị FAILED, các tác vụ phụ thuộc bị BLOCKED.
- ENVIRONMENT_ERROR KHÔNG kích hoạt việc viết lại mã nguồn (dùng assert kiểm tra các tệp không thay đổi, chỉ thử lại 1 lần).
KHÔNG ĐƯỢC: tạo các checkpoint ngoài repair_started/task_completed ở bước này (để dành cho M9).
```

## P7 — M7 TRUY XUẤT NGUỒN GỐC + M8 TÁC TỬ ĐÁNH GIÁ (REVIEW AGENT)

```
Cột mốc M7+M8: Yêu cầu -> Tác vụ -> Tệp -> Kiểm thử -> Bằng chứng + cổng kiểm toán cuối cùng.

CÁC TỆP:
  src/harness/trace/matrix.py      # build_matrix(spec, tasks, verification_results, workspace)->dict[REQ, {tasks, files, tests, status}]
  src/harness/agents/reviewer.py   # ReviewAgent(llm|rule-based).review(spec, matrix, workspace)->dict{requirements:[{id,status,evidence,missing}], overall_status}
  tests/test_trace.py  tests/test_review.py

MA TRẬN (MATRIX):
 Với mỗi REQ: tasks = [t for t in plan if REQ in t.requirements]; files = hợp (union) của các files_touched; tests/commands = hợp của các verification; evidence = [f for f in files if workspace/f tồn tại] + [v.command for v in results if v.status PASS và v.task_id in tasks]; trạng thái chỉ đạt PASS nếu có >=1 tệp tồn tại VÀ >=1 kết quả PASS bao phủ nó, ngược lại là FAIL kèm theo missing=[các lý do].
 Không có bằng chứng -> FAIL (không bao giờ cho PASS chỉ dựa trên văn bản mô tả).

BỘ ĐÁNH GIÁ (REVIEWER - mặc định dựa trên quy tắc, tùy chọn dùng LLM):
 Lượt kiểm tra bằng quy tắc: kiểm tra tệp tồn tại + xác minh đạt PASS + (nếu tiêu chí nghiệm thu có nhắc đến từ khóa, tìm kiếm (grep) từ khóa đó trong tệp, nếu không thấy thì cảnh báo). LLM có thể bổ sung lý giải nhưng không thể ghi đè từ FAIL->PASS nếu không có bằng chứng.
 Xuất JSON chính xác theo cấu trúc: {"requirements": [{"id","status":"PASS|FAIL","evidence":[paths+commands],"missing":[]}], "overall_status":"PASS|FAIL"} và lưu thành review.json.
 Trạng thái tổng thể (Overall) chỉ đạt PASS nếu tất cả các REQ đều đạt PASS.

NGHIỆM THU:
- Lượt chạy Todo với tất cả đều PASS -> ma trận hiển thị 4/4, kết quả đánh giá tổng thể đạt PASS kèm theo đường dẫn bằng chứng.
- Xóa một tệp triển khai -> REQ tương ứng bị FAIL kèm theo missing=["file src/... not found"], kết quả tổng thể FAIL.
- Tệp review.json xác thực hợp lệ với schema danh sách RequirementResult.
KHÔNG ĐƯỢC: làm phần runtime/trình duyệt ở bước này.
```

## P8 — M9 LƯU TRẠNG THÁI (CHECKPOINTING) + PHỤC HỒI (RECOVERY)

```
Cột mốc M9: Khôi phục chạy tiếp an toàn sau sự cố sập (crash-safe resume).

CÁC TỆP:
  src/harness/state/checkpoints.py  # CheckpointManager (lớp mỏng bọc trên RunStore)
  tests/test_recovery.py

CÁC SỰ KIỆN (bắt buộc phát ra thông qua store.checkpoint):
 spec_created, plan_created, task_started, task_completed, verification_completed, repair_started, review_completed.
 Bố cục thư mục: runs/{run_id}/state.json (RunState mới nhất), checkpoints/{seq:03d}-{event}-{task?}.json, workspace/ (ứng dụng được tạo ra), events.log.

LOGIC KHÔI PHỤC (RESUME LOGIC) trong orchestration/pipeline.py::resume(run_id):
 tải state.json; tìm checkpoint hoàn thành gần nhất; tính toán lại trạng thái DAG từ task_results+verification_results; đưa các tác vụ đang PENDING/READY/RUNNING về lại hàng đợi thành PENDING (RERUN), giữ nguyên COMPLETED/FAILED/BLOCKED; tiếp tục chạy đường ống mà không làm lại các tác vụ đã COMPLETED (dùng assert kiểm tra mã băm của các tệp không đổi).

NGHIỆM THU:
- Bắt đầu lượt chạy Todo, ngắt giữa chừng sau TASK-002 (mô phỏng bằng cách lưu trạng thái một phần), hàm resume() hoàn thành phần còn lại mà không làm lại TASK-001 (dùng assert kiểm tra events.log chỉ hiển thị TASK-001 một lần).
- Làm hỏng tệp state.json -> hàm resume ném ra lỗi rõ ràng (không im lặng bỏ qua).
- Các bài kiểm thử bao phủ quy tắc đặt tên tệp checkpoint + thứ tự chuỗi (sequence).
KHÔNG ĐƯỢC: chạy song song ở bước này.
```

## P9 — M10 XÁC MINH RUNTIME (không dùng trình duyệt trong V1)

```
Cột mốc M10: Chứng minh ứng dụng được xây dựng thực sự khởi động và phục vụ được yêu cầu.

CÁC TỆP:
  src/harness/verification/runtime.py  # RuntimeVerifier
  tests/test_runtime.py

CÁC BƯỚC CỦA BỘ XÁC MINH RUNTIME (mặc định FastAPI, dự phòng Node):
 1. Phát hiện điểm vào (entry): src/main.py:app hoặc app.py:app hoặc main trong package.json. Nếu không có, đánh dấu FAIL (CONFIG_ERROR).
 2. Khởi động: `python -m uvicorn src.main:app --port {free_port}` hoặc `npm run dev -- --port {port}` thông qua subprocess.Popen (từ thư mục gốc của sandbox), đợi tối đa 15 giây.
 3. Kiểm tra: tiến trình còn sống, cổng TCP mở (socket.connect), GET /health hoặc / trả về mã 2xx, GET /docs hoặc /api/health (nếu tồn tại) trả về mã 2xx, tệp SQLite tồn tại/kết nối được nếu có yêu cầu.
 4. Thu thập nhật ký (logs), kết thúc tiến trình, trả về {status PASS/FAIL, checks:[{name, ok, detail}], evidence:[đoạn trích log, mã trạng thái http]}.
 5. Khi bị FAIL, phân loại lỗi (CONFIG/DEPENDENCY/ENVIRONMENT) để tái sử dụng trong vòng lặp sửa chữa.

TRÌNH DUYỆT (V1: CHỈ TẠO HÀM GIỮ CHỖ - STUB ONLY): tạo src/harness/verification/browser.py với `def verify_acceptance(...): raise NotImplementedError("Browser verification deferred post-V1")` + bài kiểm thử xác nhận bỏ qua (skip). KHÔNG triển khai Playwright/Selenium ngay lúc này.

NGHIỆM THU:
- Ứng dụng khung từ M4 -> runtime đạt PASS (health 200).
- Cổng bị lỗi (ứng dụng tự thoát) -> FAIL kèm thông tin chẩn đoán và gợi ý sửa chữa.
KHÔNG ĐƯỢC: dùng Docker, chạy song song.
```

## P10 — M11 KHẢ NĂNG QUAN SÁT (OBSERVABILITY) + CLI + ĐO KIỂM (BENCHMARKS)

```
Cột mốc M11: Bộ khung có thể vận hành hoàn chỉnh.

KHẢ NĂNG QUAN SÁT (hoàn thiện src/harness/utils/logging.py):
 Mọi giai đoạn đều phát ra dòng JSONL với đầy đủ các trường: run_id,trace_id,stage,agent,task_id,timestamp,duration_ms,model,tokens,tool,status,error. Cung cấp lệnh `python -m harness.cli logs <run_id>` để in đẹp mắt (pretty-print) + `stats` (số lượng, số lần thử lại, tổng token, thời lượng). Bài kiểm thử dùng assert xác nhận sự tồn tại của các khóa bắt buộc trên mọi dòng.

CLI (src/harness/cli.py, chỉ dùng argparse):
 `builder new "request" [--run-id X --workspace Y --max-retries 3]` in ra:
  [1/5] Generating specification... ✓
  [2/5] Planning N tasks... ✓
  [3/5] Building... ✓ TASK-001 ... (⚠ fail + ↻ repairing)
  [4/5] Verifying... ✓ Build ✓ Tests ✓ Runtime
  [5/5] Reviewing requirements... ✓ 14/14 satisfied
  BUILD COMPLETE / BUILD FAILED kèm theo đường dẫn tới spec/tasks/verification/review.json
 Đồng thời hỗ trợ `builder resume <run_id>`, `builder review <run_id>`, `builder logs <run_id>`.
 Ánh xạ tới hàm orchestration/pipeline.py::run_new() điều phối tuần tự từ M2-M10.

ĐO KIỂM - BENCHMARKS (benchmarks/*.json + src/harness/bench/runner.py):
 5 kịch bản cố định: todo, crud-dashboard, auth-app, api-db, ecommerce-prototype (mỗi kịch bản gồm: chuỗi yêu cầu + số REQ tối thiểu + khoảng số lượng tác vụ kỳ vọng). Bộ chạy (Runner) thực thi đường ống với MockProvider, ghi nhận {build_success, test_success, req_completion, repair_count, duration_s, tokens}. Chạy `pytest benchmarks/` hoặc `builder bench --quick` (chỉ chạy kịch bản todo). KHÔNG đánh giá bằng cảm quan giao diện — hãy dùng assert kiểm tra tệp JSON số liệu được ghi ra.

NGHIỆM THU:
- Chạy `builder new "Build a Todo app"` ngoại tuyến -> BUILD COMPLETE, các tạo phẩm tồn tại, đầu ra 5 giai đoạn khớp với biểu thức chính quy (regex).
- Tệp events.log có đầy đủ tất cả các khóa, bài đo kiểm nhanh (bench quick) vượt qua.
KHÔNG ĐƯỢC: làm giao diện web (web UI), dùng Docker cho môi trường prod.
```

## P11 — M12 CỔNG KIỂM DUYỆT CUỐI: LÁT CẮT DỌC + TIÊM LỖI + DANH SÁCH KIỂM TRA V1

```
Cột mốc M12: Chứng minh độ tin cậy, sau đó đóng băng phiên bản V1.

CÁC TÁC VỤ (thực hiện theo thứ tự, tất cả phải đạt PASS):
1. LÁT CẮT DỌC (VERTICAL SLICE): `builder new "Build a Simple Todo App with add/list/complete"` -> kỳ vọng SPEC(>=3 REQ)->PLAN(>=3 tác vụ)->BUILD(các tệp)->VERIFY(pytest PASS)->RUNTIME PASS->REVIEW PASS. Lưu dưới thư mục runs/demo_todo/. Nếu bất kỳ bước nào FAIL, hãy sửa bộ khung (harness), không được đi tiếp.
2. TIÊM LỖI (FAILURE INJECTION): đưa lỗi SyntaxError vào workspace/src/main.py, chạy lại xác minh -> bắt buộc phải PHÁT HIỆN (FAIL+CODE_ERROR), KHOANH VÙNG (task_id), THU THẬP thông tin chẩn đoán, GỬI tới bộ sửa chữa, SỬA CHỮA, XÁC MINH LẠI ĐẠT PASS. Sau đó tiêm lỗi giống hệt nhau 3 lần với bản giả lập sửa chữa không làm gì (no-op repair mock) -> bắt buộc phải chuyển trạng thái WARNING->ESCALATE->FAILED+BLOCKED (kiểm tra bằng assert).
3. DANH SÁCH KIỂM TRA V1 (tất cả đều ✓): đặc tả hợp lệ, đặc tả đã qua xác thực, DAG hợp lệ, thực thi tuần tự, tạo tệp thật, xác minh thật, khoanh vùng được lỗi, sửa được lỗi, phát hiện vòng lặp, lưu checkpoint+khôi phục, ma trận truy xuất nguồn gốc, đánh giá cuối cùng, dự án hoạt động được nằm trong runs/.
4. TÀI LIỆU: README.md (hướng dẫn bắt đầu nhanh với builder new/resume/logs, sơ đồ kiến trúc ASCII từ mục §34 của kế hoạch, nguyên tắc bằng chứng), examples/todo_run/ (bản sao các tệp JSON spec/tasks/verification/review).
5. Toàn bộ repo chạy `pytest -q` đều xanh (green), `builder bench --quick` xanh.

NGHIÊM CẤM TRONG V1 (dùng assert xác nhận không tồn tại): docker/, web_ui/, các tiến trình chạy song song (parallel workers), tự động hóa trình duyệt vượt quá hàm giữ chỗ (stub), postgres, nghiên cứu qua mạng.
Nếu tất cả đều xanh -> gắn thẻ V1 DONE. Nếu chưa đạt, lặp lại việc sửa lỗi từ M1-M11, không bao giờ bàn giao khi còn báo đỏ.
```

---

## PHỤ LỤC QUY TẮC TOÀN CỤC (tác tử lập trình bắt buộc phải tuân thủ)

1. KHÔNG BAO GIỜ đặt câu hỏi. Hãy sử dụng các giá trị mặc định ở P0.
2. Xây dựng tuần tự từ M1->M12. Không bắt đầu M(N+1) nếu các bài kiểm thử của M(N) còn báo đỏ. Chạy `pytest -q` sau mỗi cột mốc.
3. Giữ các bản thay đổi (diffs) nhỏ gọn, các tệp tập trung (<400 dòng mỗi tệp, tách nhỏ nếu lớn hơn).
4. Mọi mô-đun mới đều cần một tệp kiểm thử. Mọi bản sửa lỗi đều cần một bài kiểm thử hồi quy (regression test).
5. Không lưu thông tin bí mật (secrets) trong repo. Không dùng đường dẫn tuyệt đối. Không dùng `shell=True` ngoại trừ trong bộ xác minh kèm theo cảnh báo được ghi nhật ký.
6. Bằng chứng quan trọng hơn lời tuyên bố: mọi thay đổi trạng thái đều phải ghi vào events.log + checkpoint.
7. Nếu lệnh gọi LLM thất bại/quá thời gian chờ -> lùi về nhánh xử lý tất định dự phòng để đường ống không bao giờ bị tắc nghẽn.
8. Sản phẩm bàn giao cuối cùng cho mỗi lượt chạy: workspace/ + spec.json + tasks.json + verification.json + review.json + events.log + state.json.
9. Bản tóm tắt cuối lượt chạy phải liệt kê cho từng REQ: Đã triển khai chưa? Đã kiểm thử chưa? Đã chạy Runtime chưa? Bằng chứng đâu? PASS/FAIL — không bao giờ được viết "AI báo đã xong".

## GHI CHÚ VỀ MCP prompts.chat
- Đã tìm kiếm qua `prompts-chat_search_prompts/skills` (công khai, OK, 0 kết quả cho các truy vấn ngách về bộ khung harness — đúng như dự kiến).
- `improve_prompt` / `save_prompt` yêu cầu khóa API (`Authentication required`). Để xuất bản: đặt biến `PROMPTS_CHAT_API_KEY` trong môi trường, sau đó gọi `prompts-chat_save_prompt(title="App-Builder Harness Autonomous Prompts", content=<tệp này>)`. Tệp cục bộ là bản chuẩn cho đến thời điểm đó.
- Các thẻ (tags) gợi ý nếu xuất bản: `coding-agent, autonomous, python, harness, spec-driven, verification`.