Hợp đồng I/O .board/ — tra cứu đầy đủ

Đây là toàn bộ giao diện giữa AgentJira và agent CLI. Hiểu nó là hiểu tại sao hệ thống tất định.

Server ghi vào worktree (trước khi agent chạy)

File	Nội dung
.board/task.json	Tiêu đề, mô tả, acceptance criteria, non-goals, verification rules, schema của result.json
.board/wiki/INDEX.md	Mục lục tri thức đã bơm từ Space — No wiki pages available nếu Space chưa link hoặc Arkon vắng
.board/wiki/*.md	Nội dung từng trang Wiki liên quan (tối đa 5 trang, song song)
.board/history.md	Ghi chú rework (người) + repair loop (Repair Attempt 1/2, tối đa 2 vòng)
.board/plan-research.md	(chỉ ở task spike của Planner) Báo cáo nghiên cứu codebase
.mcp.json	MCP token của persona — thuộc K5 đã hoãn, chưa ghi

.board/ và .mcp.json được thêm vào .git/info/exclude — chúng không bao giờ lọt vào diff hay commit.

Agent ghi ra (sau khi làm việc)

.board/result.json — bắt buộc. Schema:

{
  "success": true,
  "summary": "Mô tả ngắn việc đã làm",
  "filesChanged": ["src/a.ts", "src/a.test.ts"],
  "notes": "Ghi chú thêm",
  "followUpSuggestions": ["Cần thêm rate limit"],
  "wikiProposals": [
    { "contentMd": "# ADR-014…", "note": "…" }
  ]
}

• success (boolean) và summary (string không rỗng): bắt buộc.
• filesChanged, notes, followUpSuggestions: tuỳ chọn.
• wikiProposals[]: tuỳ chọn, nhưng mỗi phần tử bắt buộc contentMd không rỗng.
• Sai schema → repair loop (tối đa 2 vòng) → nếu vẫn sai, suy biến mềm về trích xuất regex.

Reviewer Agent ghi ra

.board/review-verdict.json:

{
  "score": 95,
  "verdict": "approved",
  "summary": "…",
  "findings": [
    { "file": "src/x.ts", "severity": "minor", "message": "…" }
  ]
}

• score: 0–100. verdict ∈ approved | changes_requested | rejected.
• severity ∈ critical | major | minor | info.

Bốn cơ chế đã nối — kill-switch và suy biến

Cơ chế	Hàm	Khi nào chạy	Suy biến	Kill-switch
Bơm tri thức vào worktree	syncBoardWikiContext	Trước session.execute(), song song với createSession() (deadline 8s)	INDEX.md rỗng + event Space wiki context unavailable	AGENTBOARD_WIKI_CONTEXT=0
Nhận đề xuất Wiki	ingestWikiProposals	Sau terminateOnce (đã ở review/peer-review)	Event nêu reason, đề xuất ở lại result.json	AGENTBOARD_WIKI_CONTEXT=0
Repair loop result.json	writeRepairHistory + formatRepairPrompt	Ngay sau readBoardResult() nếu !valid (tối đa 2 vòng, deadline 5m/vòng)	history.md + fallback extractTaskSummary	AGENTBOARD_BOARD_REPAIR=0
Reviewer Agent	ReviewerAgentService	Sau afterCompletion, chỉ khi reviewState==='peer-review'	Ở lại peer-review, event Peer review unavailable	AGENTBOARD_REVIEWER_AGENT=off (auto mặc định)

Reviewer cần LLM thật

AGENTBOARD_REVIEWER_AGENT=auto (mặc định) chỉ chạy khi AGENTBOARD_LLM_MODE ∈ record và có AGENTBOARD_LLM_API_KEY/OPENAI_API_KEY và AGENTBOARD_LLM_MODEL. Nếu không, nó tự tắt thay vì tạo bản ghi audit giả (score 95 approved) — đây là hành vi có chủ ý. heuristic là opt-in cho E2E (prefix [heuristic]).

.mcp.json vẫn chưa ghi — K5 đã hoãn có chủ ý

5 MCP token vẫn nằm trong DB, decryptToken chỉ có call site khi K5 xong. Vì vậy Wiki hai chiều hiện hoạt động qua file (.board/wiki/** và wikiProposals), chưa qua MCP trực tiếp.

Sự kiện realtime & phòng WebSocket theo Space

Tab Comments đọc qua WebSocket (/ws, room theo spaceId):

Sự kiện	Payload	Client làm gì
activity_created	activity comment đầy đủ (+ metadata.spawnedSubtasks / skippedMentions)	Thêm dòng comment + chip subtask nếu cùng taskId (trùng id thì bỏ qua)
activity_deleted	{ id, taskId }	Gỡ dòng comment khỏi thread
subscribed / unsubscribed	{ spaceId }	Đánh dấu phòng đã vào / đã rời
error + code: IDENTITY_PENDING	{ spaceId }	Danh tính chưa giải xong — client tự retry tối đa 4 lần (backoff tới 4s)
error + code: FORBIDDEN	{ spaceId }	Subscribe chéo Space bị từ chối — không retry, badge hiện No updates

Mất nối → client nối lại và tải lại state (không phát lại event lỡ).

Tự kiểm chứng (không tin UI — đi tìm file và dòng DB)

# 1. Wiki đã vào worktree
WT=$(curl -s "$API/api/tasks?projectId=$PID" | jq -r '.[0].worktreePath')
docker exec agentjira_dev_server sh -c "cat $WT/.board/wiki/INDEX.md"
# → liệt kê trang, không phải "No wiki pages available"

# 2. result.json → summary API khớp nhau
docker exec agentjira_dev_server sh -c "cat $WT/.board/result.json" | jq .summary
curl -s "$API/api/tasks/$ID" | jq .summary

# 3. Reviewer verdict
docker exec agentjira_dev_server sh -c "cat $WT/.board/review-verdict.json" | jq .
curl -s "$API/api/tasks/$ID/reviews" | jq .

# 4. Đề xuất Wiki → draft Arkon
curl -s "http://localhost:5055/api/wiki/drafts?department_id=$DEPT" -H "Authorization: Bearer $TOKEN" | jq .

# 5. Repair loop
docker exec agentjira_dev_server sh -c "cat $WT/.board/history.md" | grep "Repair Attempt"

# 6. .board/ không lọt git
docker exec agentjira_dev_server sh -c "cd $WT && git add -A && git diff --cached --name-only | grep -q .board && echo FAIL || echo OK"

Ratchet chống tái phát: tests/wiring-liveness.test.ts quét src/**/*.ts và assert mỗi hàm trên có call site ngoài file định nghĩa, pin ở agent-manager.ts. Xóa call site là CI đỏ.