# Công ty, sản phẩm, mục tiêu, việc

Phần cố định (Soot, đội, sản phẩm) và phần mềm dẻo (mục tiêu, việc, lịch); đổi hoạt động của đội bằng cách đổi mục tiêu.

Một công ty chạy bằng Soot cần hai thứ khác nhau. Thứ nhất ít đổi: ai làm (Soot, đội), làm cho sản phẩm nào, chạy ở máy chủ nào. Thứ hai đổi hằng tuần: tuần này đẩy chỉ số nào, làm việc gì. Nếu trộn hai thứ, muốn đổi hướng đi thì người phải sửa system prompt của Soot hoặc ontology của workspace. Soot tách chúng ra: phần cố định là config, phần mềm dẻo là dữ liệu (mục tiêu, việc) mà host tự đưa vào lượt chạy kế tiếp. Người đổi hoạt động của đội bằng cách đổi mục tiêu.

## Mô hình

```text
CỐ ĐỊNH (config trong deployment.json, đổi ít, qua settings action)
  Công ty ─ Sản phẩm (workspace.projects[]) ─ Đội (group)  ─ ontology.json: thực thể, quan hệ, quy trình giữa các đội ─ Soot
            máy chủ chứa Soot và đội

MỀM DẺO (dữ liệu trong workspace store, đổi bất cứ lúc nào)
  Hướng sản phẩm        level=direction   một mục tiêu đang chạy cho mỗi sản phẩm
   └ Mục tiêu chu kỳ    level=cycle       chỉ số + rào chắn, cỡ 6 tuần
      └ Mục tiêu đội    level=team        đội đề xuất, nối vào một mục tiêu chu kỳ
         └ Việc         task.goal         gắn một mục tiêu, hoặc để trống = vận hành
            └ Việc lặp lại   task có repeat   chính là "lịch chạy"
               └ Kết quả   outcome          đơn vị việc xong, ghi kèm chi phí
```

Ba ý chính:

- Ít tầng. Mục tiêu đo bằng con số, không bằng số việc xong. Việc phục vụ mục tiêu.
- Căn chỉnh, không chia nhỏ. Người (hoặc Lead) đặt mục tiêu sản phẩm. Đầu mối mỗi đội đề xuất mục tiêu đội của mình và chỉ ra nó nối vào mục tiêu chu kỳ nào.
- Soot không biết một mục tiêu đo cái gì. `metric.ref` là chuỗi tự do mà pack hoặc skill hiểu (ví dụ `company-loop:first_payers`).

## Khái niệm

### Sản phẩm là nhãn, không phải máy chủ

`workspace.projects[]` là `{id, name, logo?}`; `id` là slug bất biến. Một máy chủ chứa nhiều đội, một sản phẩm gom nhiều đội, một đội làm cho nhiều sản phẩm (`groups.<id>.projects[]` rỗng nghĩa là mọi sản phẩm). Sản phẩm của một Soot được suy ra theo thứ tự: sản phẩm duy nhất mà các đội của nó khai, nhãn `project` của host, tên thư mục workspace. Task, goal và outcome đều mang nhãn này, nên báo cáo và Nest lọc theo sản phẩm mà không cần tách hạ tầng. Hợp đồng ở contracts/projects.md.

### Mục tiêu

| Cấp | Ai đặt | Ý nghĩa |
|---|---|---|
| `direction` (dài hạn) | Người | Một cho mỗi sản phẩm: chỉ số chính và câu "thắng là gì". Đổi rất hiếm |
| `cycle` (ngắn hạn) | Người, Lead đề xuất | Một chu kỳ, mặc định 6 tuần. Bắt buộc có ít nhất một rào chắn |
| `team` | Đầu mối đề xuất | Chỉ số đầu vào đội tự đẩy được; `parent` là mục tiêu chu kỳ cùng sản phẩm |

`project` rỗng nghĩa là cả công ty. Trạng thái: `draft`, `active`, `done`, `dropped`. Mỗi mục tiêu có `metric` (điểm đầu, đích, hướng tốt), `guardrails` và các lần check-in (`value`, `confidence` 0..10, `note`). Rào chắn là chỉ số không được xấu đi: chỉ số nào bị nhắm vào cũng có thể bị lách, với agent còn dễ hơn với người. Giá trị hiện tại không lưu trong mục tiêu; nó là check-in cuối do ai giữ chỉ số đọc rồi ghi.

`workspace.goals` đặt hạn mức (số mục tiêu đang chạy mỗi sản phẩm, mỗi đội, để một đội không ôm mười ưu tiên), ai duyệt mục tiêu đội (`approve_team_goals`: người hoặc Lead), ai kích hoạt việc lặp lại có thể đánh thức model (`approve_waking_repeats`) và danh sách `cadence`. Xem `soot schema deployment`. Hợp đồng ở contracts/goals.md.

### Việc

Task là bản ghi chung của người và Soot: trạng thái (`todo`, `doing`, `blocked`, `review`, `done`, `canceled`), người nhận (Soot, đội, người), việc cha và con, hạn, bình luận, nhật ký append-only. Tạo việc (`create`) không tự bắt đầu việc: `start` là một lần chạy tường minh, và chỉ Soot hoặc người đánh dấu `done`. Gửi việc (`send`, mục dưới) là tạo và bắt đầu trong một bước. Hai trường nối task vào công ty:

- `goal`: mục tiêu mà việc phục vụ. Để trống nghĩa là việc vận hành (trả lời khách, sửa lỗi, đo số, giữ rào chắn). Quá nhiều việc đang mở không gắn mục tiêu thì Nest cảnh báo.
- `project`: sản phẩm của việc. Trống thì lượt chạy lấy sản phẩm của mục tiêu, hoặc sản phẩm duy nhất của đội.

### Gửi việc: việc là tin nhắn

`send` ghi một việc kèm một thư rồi bắt đầu nó ngay, không tốn lượt model nào để chuyển tiếp. Có ở op `send` của công cụ `task` (lượt do workspace khởi động: Nest, lịch, sự kiện, việc; không có ở widget, SDK, live chat, eval hay dry run), ở `POST /v1/workspace/tasks` với `deliver: true`, và ở `soot tasks send --to team:<id> "tiêu đề"`.

- `to: team:<id>`: host chọn người chạy, là Đầu mối của đội. `to: soot:<id>` chỉ dùng trong cùng đội; Soot ở đội khác phải gửi cho đội (`mail_address_team`). Việc không bao giờ tới Lead (`mail_for_lead`). Việc cho một thành viên chạy bằng chính thành viên đó, trong đội, với ngân sách của đội và của nó ([agents.md](https://trysoot.com/vi/docs/agents/index.md)).
- Việc của người (Nest, CLI, Lead) chỉ bị chặn vòng lặp. Việc từ Soot hay runtime khác còn qua hai hạn mức: quá `mail.daily_per_sender` (mặc định 20) việc một ngày từ một đội sang một đội thì việc nằm `todo` với `mail_rate_limited`; đội có `inbox: "hold"` thì việc chờ người bắt đầu (`inbox_hold`). Việc sinh trong lượt đang phục vụ việc khác mang `hops + 1`; quá `mail.max_hops` (mặc định 4) thì được ghi mà không chạy, kèm thẻ `mail_loop`. Đội chưa có Đầu mối: `team_needs_coordinator`, tự chạy khi có.
- `budget_tokens` là trần token của lượt nhận, cộng với trần riêng của Soot nhận. Hết trần hay hết ngân sách đội thì `reply` là `blocked` kèm lý do.
- Xong lượt, host gửi `reply` về nơi gửi: trạng thái (`done`, `failed`, `blocked`, `needs_person`), tóm tắt tối đa `mail.reply_bytes` (4 KiB), tệp kết quả, số token. Người đọc nó trên nhật ký việc (`mail_reply`); Lead nhận một ghi chú host trong thread mà không tốn lượt; Soot gửi với `wait: true` được đúng một lượt tiếp có `reply` làm đầu vào.
- Soot nhận thư mở câu trả lời bằng dòng `outcome: <code>` và task thư đi theo dòng đó, không cần gọi `op update`: `done` → `done`, `partial` → `review`, `needs_input`/`failed` → `blocked`, `declined` → `canceled`. Đó vẫn là Soot nói việc xong, qua câu trả lời. Trạng thái Soot hay người đã đặt trong lượt thì giữ; câu trả lời không có dòng outcome thì task để nguyên.
- `request_id` làm lần gửi lại thành cùng một việc; cùng id khác nội dung bị từ chối. `dry_run` trả nơi việc tới và ai chạy, không ghi gì.
- Đội ở máy chủ khác (nhóm `remote`) gửi được như đội ở đây: việc ở đây là bản gương, đội bên kia chạy, trạng thái và `reply` về theo nhịp đọc. Máy chủ bên kia tắt thì việc chờ `delivery: pending` và không bao giờ chạy thay ở đây; quá 30 phút có thẻ `mail_undelivered`. Hợp đồng: contracts/team-mail.md.

- Việc chuyển tiếp (đội A gửi một phần sang đội B với `wait: true`) được trả lời từ cuối chuỗi: lượt mà câu trả lời của B đánh thức mới trả lời thư của A. Trong lúc chờ, ai đang chờ đầu chuỗi (khách qua intake, Soot đã gửi) được báo một lần cho mỗi nguyên nhân: việc chờ một người duyệt ở bất kỳ đâu trong chuỗi (kể cả ở máy chủ khác), việc quá `due`, và việc mở quá `mail.progress_after_seconds` (mặc định 300 giây; báo lại ở 4, 16, 64… lần mốc đó). Việc bị huỷ hay được người đánh dấu xong trước khi lượt của nó trả lời vẫn trả lời người gửi (`task_canceled`, hoặc `done` với ghi chú), nên không ai chờ mãi.

Cấu hình: `mail {max_hops, daily_per_sender, reply_bytes, progress_after_seconds}` ở gốc deployment và `groups.<id>.inbox` (`auto` hoặc `hold`). `project` trên `send` là nhãn sản phẩm của việc.

Báo cáo của khách tới đội đi qua intake (`intakes.<id>`, contracts/intake.md), không qua dòng hợp đồng: dòng hợp đồng không tới được công cụ nào, và Soot nhận báo cáo có thể đứng riêng, không thuộc đội có hợp đồng. Việc từ intake vẫn là thư như trên, với cùng hạn mức.

### Cấp dòng hợp đồng khi cần

Khi workspace có ontology (một thực thể hoặc một quan hệ), Soot đội A đọc bảng hay ghi vào hàng đợi của đội B mà ontology chưa có quan hệ hay cột đó thì bị từ chối kèm mã (`contract_not_consumed`, `queue_not_requested`, `contract_field_unknown`). Lỗi trả về kèm luôn cách xin: gọi `report_blocker` với `grant {kind: "contract", team, item, level: "read"|"write", fields}` rồi dừng. Nếu workspace chưa có ontology thì lỗi quyền vẫn như cũ và không có gợi ý xin. Host kiểm tra yêu cầu trước khi cho lượt dừng: đội phải ở runtime này, bảng phải có trong pack của đội B, và quan hệ đó chưa được cấp. Đội ở runtime khác thì bị từ chối với `contract_grant_remote_unsupported`, kèm tên runtime.

- Mọi lượt đang chờ cùng một dòng (cùng đội xin, đội chủ, bảng, cột, đọc hay ghi) gộp thành **một** mục Cần bạn `contract-grant:<id>`. Id là băm của dòng, nên hỏi lại lần nữa chỉ thêm lượt vào mục cũ.
- Người duyệt bằng `POST /v1/settings/contract-grants/{id}` `{decision: "grant"}` hoặc `soot teams grant <id>`. Host sửa `ontology.json` trong một revision cài đặt (action `contract.grant`). Nếu đội B chưa khai thực thể thì nó được thêm (cho mọi tenant, không bao giờ kèm cột principal), hoặc được nới cột nếu đã có. Đội A được thêm một quan hệ `read`, hoặc `request` nếu là ghi. Đội khác đang đọc mọi cột của thực thể bị nới thì được giữ đúng các cột cũ. `dry_run: true` (`--dry-run`) trả diff (trước/sau) của từng đội mà không ghi gì.
- Runtime chạy ontology mới (sau lần khởi động lại do kích hoạt cài đặt) mới nhắn các lượt đang chờ thử lại. Quyết định được lưu ở `contract-grants.json` trong thư mục dữ liệu, nên vẫn còn sau khi khởi động lại.
- Từ chối (`{decision: "decline", reason}`, `soot teams decline <id> --reason …`): mọi lượt chờ nhận lý do và làm tiếp phần còn làm được. Dòng bị validation từ chối (ví dụ `contract_principal_column`) trả `422` kèm mã đó; ontology giữ nguyên, các lượt chờ cũng được báo và chạy tiếp, không lượt nào bị treo.
- Mỗi yêu cầu chỉ có một quyết định: gửi lại đúng quyết định đó là phát lại (`replay`), gửi quyết định khác bị `409 contract_grant_decided`. Id không có lượt nào chờ thì `404 contract_grant_not_found`. Chỉ người làm được việc này; token có scope bị chặn.

Thẻ Cấp quyền trong thread của Nest là pha P5b, chưa làm.

### Theo dõi quy trình

Quy trình trong ontology (`within` của lần chuyển, `deadline`) được host canh, không cần model: mỗi 5 phút, với thực thể mà runtime này giữ bảng, bản thể đứng ở trạng thái chưa kết thúc quá hạn thì **một** thư việc gửi cho `team:<đội giữ lần chuyển kế tiếp>` (tên quy trình, id bản thể, trạng thái, bao lâu, việc kế tiếp), mỗi bản thể mỗi trạng thái một lần. Trạng thái có `gates` với `person` thì thành thẻ Cần bạn thay vì thư. Mỗi đội tối đa 10 thư mỗi ngày; phần vượt chỉ còn một dòng trong Cần bạn. Runtime không có quy trình thì không làm gì. `GET /v1/processes` (chỉ người vận hành) cho số bản thể theo trạng thái và các bản thể kẹt. Hợp đồng: contracts/process-watch.md.

### Việc lặp lại là lịch chạy

Một lịch không còn là mục cấu hình riêng. Nó là một task có `repeat`, gồm:

- Nhịp: `every`, `cron` hoặc `at`, kèm `timezone`.
- Trạng thái: `draft` (chờ duyệt), `active`, `paused`.
- Cách chạy, một trong hai: một lượt model với `text`, hoặc một chuỗi tool (`tool`, `then`) chỉ đánh thức model khi `wake_when` thấy có chuyện. Chuỗi tool rẻ: một lịch hỏi "có bài nào tới hạn không" mỗi 10 phút gần như không tốn token, chỉ lúc có bài mới gọi model.
- Người nhận: `team:<id>` chạy như Đầu mối của đội; `soot:<id>` chạy như Soot đó. Đội chưa có Đầu mối, hoặc lịch rơi vào Lead, thì lịch bị giữ (`held`: `needs_coordinator`, `lead_not_scheduled`) và hiện trong danh sách, không làm hỏng việc nạp cấu hình. Lead không chạy lịch của đội.

Mỗi lần chạy là một lượt của việc, không phải một việc mới (hàng trăm lượt mỗi ngày sẽ làm ngập bảng việc):

| Lần chạy | Ghi lại thế nào |
|---|---|
| Yên lặng: tool chạy xong, không có gì để đánh thức, hoặc bị bỏ qua | Chỉ tăng bộ đếm `repeat.stats` |
| Chỉ có tool | Một job đã xong, dọn sau thời hạn lưu (`events.job_retention_days`, mặc định 14 ngày) |
| Đánh thức model, hoặc lỗi | Một task con: `parent` là việc lặp lại, `goal` thừa kế, tiêu đề `<title> · dd/mm HH:MM`. Lỗi trước khi run bắt đầu để task con `blocked` kèm lý do |

Hết ngân sách thì lịch không chạy tool. Một lần chạy có thể đánh thức model (có `wake_when`, có `then`, hoặc là lượt model thuần) được kiểm ngân sách trước khi chạy tool: Soot sẽ được đánh thức đã hết `daily_tokens` ngày, hoặc đội đã hết ngân sách hợp đồng trong ngày, thì lần chạy bị bỏ qua (`skip_reason.kind` là `budget_exhausted`, `key` là `soot_daily` hoặc `team_daily`, `budget_stop` cùng giá trị). Tool không chạy (nên không "nhận" bài rồi bỏ đó), không có task con và không có thẻ Cần bạn riêng; thẻ ngân sách của Soot hoặc đội là thẻ duy nhất. Lịch chỉ có tool, không bao giờ đánh thức model, không bị chặn. Sang ngày mới hoặc khi người dùng tăng ngân sách, lần chạy kế tiếp đi bình thường và việc đã dừng vẫn tự làm tiếp. Các task con của cùng một việc lặp lại bị lỗi chỉ hiện một thẻ `task_waiting` (task con mới nhất); task con bị chặn vì ngân sách không có thẻ riêng.

Thẻ `token_budget_exhausted` và `team_budget_exhausted` khuyên "Chờ" khi việc bị dừng chỉ là lịch chạy lại (lần sau sẽ tới). Nếu việc bị dừng gồm việc quan trọng (người gửi hoặc bắt đầu, việc của Lead thay người, hạn trong 24 giờ, hoặc gắn một mục tiêu), thẻ khuyên "Tăng ngân sách", nêu việc đó trong `why` và đưa danh sách vào `payload.important` (`task`, `title`, `reason`). Runtime không tự tăng ngân sách: chi tiền vẫn do người quyết.

`repeat.stats` tính khi đọc: lần tới, lần trước, số lần chạy, đánh thức và lỗi trong 7 ngày, trạng thái lần cuối (`ok`, `failed`, `skipped`, `held`), lỗi, lý do bỏ qua (thiếu credential không phải lỗi), lần đánh thức gần nhất và chi phí 7 ngày. Chi phí cộng từ trace của cuộc hội thoại lần chạy gần nhất và không đoán giá lượt chưa có giá, nên số này thấp hơn thực tế khi Soot rất bận. Nếu ngân sách token của Soot hoặc đội cắt lượt model, `budget_stop` nói rõ: lịch đó không làm xong việc nên không được hiện là khỏe. Lượt model của lịch cũ chưa xong bị lượt mới thay thế (superseded), và thẻ cần người trả lời của lượt cũ không còn tính là đang chờ. Chạy ngay một việc lặp lại (`soot tasks start <id>`) chạy đúng lần chạy theo lịch, kể cả chuỗi tool và job, không phải một lượt model thường. Một lịch lỗi liên tục không chất đống mãi: đến `RepeatFailStreak` (3) lần chạy lỗi liền nhau — lỗi trước khi run, hoặc run đánh thức kết thúc `failed` — lịch tự chuyển `paused`, ghi sự kiện `fire_streak` trên việc lặp lại, và người bấm Tiếp tục khi đã sửa. Lần chạy xong (`completed`) đặt lại chuỗi về 0; lần yên lặng không đếm (không chứng minh được nguyên nhân đã hết) và lần `skipped` không tính là lỗi. Người đóng cả đống task con blocked bằng một cú bấm: `POST /v1/workspace/tasks/{id}/dismiss` gỡ task con lỗi đó và mọi task con blocked cũ hơn của cùng lịch (`dismissed` đếm được); trên Nest là nút "Đóng các lần chạy lỗi trước" trên phiếu của một task con blocked.

`origin` cho biết ai sinh ra việc lặp lại:

| `origin` | Từ đâu |
|---|---|
| `host` | Người hoặc Soot tạo qua HTTP, CLI, Nest |
| `source:<id>` | Source khai lịch trong repo của nó |
| `template:<team>` | Template đội (`group.create`); xóa nhóm xóa chúng |
| `cadence:<id>` | Host giữ theo mục tiêu đội (xem dưới) |
| `nest` | Bản tin sáng đầu tiên của Lead, chỉ đọc |

Việc không phải `host` là chỉ đọc, trừ `state` và `goal`; nội dung theo nơi sinh ra nó. Trường `schedules` cũ trong `deployment.json` chỉ còn là đầu vào chuyển đổi: runtime đọc, cảnh báo, và phản chiếu mỗi mục thành một việc lặp lại (`soot migrate schedules` xóa trường sau khi mọi id đã có task). Các đường cũ (`schedule.save`, `GET /v1/settings/ schedules`, `soot schedules`) trả lời rõ là đã bỏ, không âm thầm làm gì.

Quyền tạo đi theo tiền, vì một việc lặp lại đánh thức model là chi tiêu đều đặn:

| Người tạo | Kết quả |
|---|---|
| Người | Đang chạy (trừ khi xin bản nháp) |
| Lead hoặc Đầu mối, chỉ chạy tool | Đang chạy (Đầu mối chỉ cho đội mình) |
| Việc có thể đánh thức model | Bản nháp. Lead tạo thì tự kích hoạt khi `approve_waking_repeats = lead_within_budget` và chi phí lần trước nằm trong ngân sách đội |
| Soot khác | Luôn là bản nháp |

### Kết quả

Pack khai báo thế nào là một đơn vị việc xong (`pack.json` `outcomes`: `id`, `label`, `unit`, cửa sổ hủy `void_window`). Soot ghi bằng tool `outcome` (hoặc `soot outcomes record`). Host sao nhãn sản phẩm vào dòng ghi, cộng chi phí của job đi kèm, và cho hủy trong cửa sổ. Báo cáo cho số `gross`, `voided`, `net` và chi phí theo Soot và sản phẩm. Hợp đồng ở contracts/outcomes.md.

Outcome và mục tiêu nối với nhau qua con số, không qua khóa ngoại. Outcome là cái đã làm xong và tốn bao nhiêu; chỉ số của mục tiêu là cái đã thay đổi. Pack (như company-loop) đọc số liệu của mình, rồi đội ghi check-in. Core không tự cộng outcome vào mục tiêu.

## Luồng chính

### Từ mục tiêu đến việc

```text
Đầu chu kỳ   người + Lead: đặt mục tiêu chu kỳ cho từng sản phẩm
             Đầu mối mỗi đội: propose mục tiêu đội (draft), nối vào mục tiêu chu kỳ
             người duyệt (hoặc Lead, nếu approve_team_goals = lead) → active
             mục tiêu đội active → host giữ việc lặp lại theo cadence cho đội đó
Trong chu kỳ Đầu mối + thành viên: tạo việc gắn goal, chạy, ghi outcome, check-in
Khi đổi      người sửa mục tiêu → host tạm dừng việc lặp lại liên quan và báo;
             lượt chạy kế tiếp thấy mục tiêu mới
```

Đội đề xuất, không bị giao xuống. Mục tiêu đội ở `draft` không tạo nhịp việc nào cho đến khi có người duyệt, nên host đưa một thẻ `goal_drafts` vào Cần bạn cho mỗi sản phẩm còn mục tiêu nháp. Thẻ tự hết khi bản nháp cuối được duyệt hoặc bỏ.

Cadence là mẫu `{id, title, cron, timezone, text}` trong `workspace.goals.cadence`. Với mỗi đội có mục tiêu đội đang chạy, host giữ một việc lặp lại cho mỗi mẫu (nhịp đầu tuần cam kết, cuối tuần check-in, nếu người cấu hình như vậy), giao cho `team:<id>`. Việc đó chạy khi mục tiêu chạy, tạm dừng sau đó, và giữ nguyên nếu người đã tạm dừng tay.

### Ai được làm gì

Công cụ `goal` kiểm tra quyền trong host, không dựa vào prompt:

| Người thực hiện | Được |
|---|---|
| Người (HTTP, CLI, Nest) | Mọi thứ: tạo (có thể `active` ngay), sửa, duyệt, check-in |
| Lead | `list`, `get`, `propose`, `update`, `checkin`. `approve` chỉ mục tiêu đội, và chỉ khi `approve_team_goals` là `lead`. Direction và cycle là của người |
| Đầu mối của đội | `propose` bản nháp cho đội mình, `update` bản nháp của mình, `checkin` mục tiêu của đội |
| Soot khác | `list`, `get` |

Với việc: Lead `start` được mọi task; Đầu mối `start` được task giao cho đội mình hoặc một thành viên, vẫn trong ngân sách của đội. Mọi Soot `send` được tới một đội, kể cả đội ở máy chủ khác, trong các hạn mức ở trên. Không gì tự nhặt việc về chạy: một task chỉ chạy khi có người hoặc Đầu mối bắt đầu nó, hoặc khi nó là việc lặp lại đến giờ. `workspace.goals.save` (hạn mức, cách duyệt, cadence) là cài đặt của người; Lead chỉ đề xuất, đề xuất chờ ở Cần bạn.

### Soot nạp gì khi chạy

Host dựng một khối ngữ cảnh nhỏ (cỡ 2 KiB) và đưa vào lượt chạy dưới dạng tin nhắn hệ thống đặt sau transcript, mở đầu bằng `[Workspace: host context, current as of this message]`. Nó không nằm trong system prompt, để thay đổi của việc không làm hỏng phần đầu prompt đã cache.

Khối gồm: hướng sản phẩm, mục tiêu chu kỳ đang chạy kèm check-in cuối và rào chắn, mục tiêu đang chạy của đội, vài việc đang mở (mỗi việc kèm mục tiêu), quy tắc "không gắn mục tiêu là vận hành", tóm tắt (từ ontology) những gì đội cung cấp, quyết và báo người, cùng brief của đội. Một việc chạy riêng thêm dòng "serves: <mục tiêu>". Khi vượt cỡ, khối bỏ việc, rồi lý do, rồi brief; mục tiêu và rào chắn không bao giờ bị cắt. Cuối khối là mục `## Tables`: các bảng tool data của lượt chạy với tới (`level: table — mô tả`, tối đa 20), vì thứ việc trước đã lưu vào bảng không nằm trong file hay transcript nào; dòng không ghi số hàng nên thêm hàng không làm khối đổi.

Khối không có đồng hồ hay bộ đếm nên giữ nguyên từng byte đến khi mục tiêu, việc hoặc ontology đổi, và chỉ gửi lại khi transcript chưa kết thúc bằng đúng khối đó. Chạy lần đầu, chu kỳ lịch mới và thành viên được ủy quyền luôn nhận khối. Chat công khai, SDK client, eval và dry run không nhận. Công ty chưa có mục tiêu thì không có khối.

Người sửa mục tiêu xong thì lượt chạy kế tiếp của mọi Soot liên quan đã thấy mục tiêu mới. Không cần sửa soul hay mission, không cần khởi động lại. Mục tiêu không cấp thêm quyền nào: `decides`/`escalates` (trong `ontology.json`), ngân sách token (`groups.<đội>.limits.daily_tokens`) và chuyện tiền bạc vẫn như cũ.

### Khi mục tiêu đổi

Đổi `status`, đích hoặc ngày kết thúc là thay đổi quan trọng. Host tạm dừng mọi việc lặp lại gắn với mục tiêu đã `done` hoặc `dropped` (ghi lý do lên task, đảo lại được), tạo một thẻ `goal_changed` trong Cần bạn nêu mục tiêu và các việc đang mở của nó, và khối ngữ cảnh ở lượt kế tiếp phản ánh mục tiêu mới.

### Bản tin sáng đầu tiên

Lần chạy đầu, `AdoptFirstRun` chọn model vừa trả lời thật làm model của Lead và tạo bản tin sáng như một việc lặp lại `nest`, chỉ đọc, do Lead chạy. `workspace create` và `workspace adopt` ghi đội từ template, kèm việc lặp lại `template:<team>` của nó.

## Ontology của workspace

Một tệp, `ontology.json`, cạnh `deployment.json` (tìm theo quy ước như `soots/<id>/soot.json`). Nó gom mọi thứ nằm giữa các đội: thực thể đội giữ, đội nào đọc hay xin ghi thực thể nào, quy trình đưa một thực thể qua các trạng thái, và phần chữ cho Soot hiểu (công ty là gì, mỗi đội nhận việc gì, thuật ngữ). Đội không mang theo quan hệ nào: cách đội làm việc bên trong là memory, mission và adapter của đội. Không có tệp thì workspace chạy như cũ. Schema: `soot schema ontology`. Phiên bản `ontology/v1`; khoá lạ bị từ chối.

```jsonc
{
  "version": "ontology/v1",
  "about": "công ty là gì, làm gì",                         // tối đa 2 KiB
  "terms": [ { "term": "chương", "aliases": ["chapter"], "means": "…", "owner": "<đội>" } ],
  "teams": { "<đội>": {
      "does": "đội nhận việc gì", "not": "không nhận gì", "ask": "viết yêu cầu thế nào", // 600 byte mỗi chữ
      "owns": ["khái niệm đội sở hữu"],                      // tối đa 20 mục, 80 byte mỗi mục
      "decides": { "self": ["…"], "with_person": ["…"] },    // việc đội tự quyết / cần người
      "escalates": [ { "when": "chữ cho người", "on": "queue_waiting", "after": "24h" } ],
      "emits": ["outcome_id"] } },
  "entities": { "<id>": {
      "description": "…", "owner": "<đội>",                  // đội giữ bảng
      "store": { "pack": "<pack>", "table": "<bảng>" },      // đội ở runtime khác có thể bỏ
      "fields": ["cột đội khác được thấy"],                  // bỏ trống: mọi cột khai báo (không principal)
      "tenant": "all", "queue": false,                       // queue: đội khác xin ghi được
      "state": "stage", "states": ["new", "done"], "terminal": ["done"],
      "labels": { "new": "Mới nhận", "done": "Đã giao" },   // chữ người đọc cho từng trạng thái, tối đa 80 byte
      "title": "headline" } },                               // cột đặt tên một mục; bỏ trống: hiện id dòng
  "relations": [ { "team": "<đội>", "entity": "<id>", "can": ["read", "request"],
                   "fields": ["thu hẹp phần đọc"], "why": "…", "optional": false } ],
  "processes": { "<id>": {
      "description": "…", "entity": "<id>", "deadline": "72h",
      "starts": [ { "via": "chat|app|admin|schedule", "team": "<đội>" } ],
      "moves": [ { "from": "new", "to": "done", "by": "<đội>", "within": "2h" } ],
      "gates": [ { "at": "new", "with": "person", "why": "…" } ] } }
}
```

**Thực thể** nằm ở một bảng của pack; cột lấy từ định nghĩa bảng, không khai lại. `queue: true` là hàng đợi chỉ thêm: đội khác có quan hệ `request` được ghi vào, các cột `fields` là cột được đặt. **Quan hệ** là thứ duy nhất ở đây cấp quyền: `read` cho đội đọc thực thể (tối đa các `fields` của quan hệ, trong những cột thực thể cho thấy), `request` cho ghi vào hàng đợi. Mọi luật cũ giữ nguyên: mã lỗi, chiếu cột, tenant do host đóng, nhật ký `contract_read`, đội ở runtime khác, cấp quyền khi cần. Tên có hậu tố sản phẩm (`posts@lohi`) vẫn dùng được. **Quy trình** là các lần chuyển trạng thái của một thực thể, mỗi lần một đội chịu trách nhiệm (không có bước bên trong đội); hiện chỉ được kiểm lúc nạp và xem qua tool `workspace`, chưa có bộ theo dõi hạn (`within`, `deadline`) hay cổng người (`gates`).

Kiểm lúc nạp: `owner`, `team` của quan hệ và `by` của lần chuyển phải là nhóm trong `groups`; bảng và pack của `store` phải có khi pack đã cài; `fields` và `state` phải là cột; `states` chứa `terminal`; khoá của `labels` phải nằm trong `states`, `title` phải là cột; trạng thái của lần chuyển và cổng phải nằm trong `states`; thực thể của quy trình phải có; thời hạn phải là duration; hạn cỡ như trước (2 KiB `about`, 600 byte mỗi chữ, 300 thuật ngữ, 128 thực thể, 512 quan hệ, 64 quy trình, 256 KiB cả tệp, không ký tự điều khiển). Chữ của một đội đã gỡ (khoá `teams`, `owner` của thuật ngữ) bị bỏ qua chứ không làm hỏng cấu hình; một thực thể, quan hệ hay lần chuyển trỏ vào đội không còn thì là lỗi.

**Chuyển từ cách cũ.** `groups.<đội>.contract` và `workspace.ontology` bị gỡ và nạp sẽ báo `retired_field` kèm "moved to ontology.json"; không có lệnh chuyển tự động. Ánh xạ: `provides.tables` thành `entities`; `provides.queues` thành `entities` với `queue: true`; `provides.events` thành `teams.<đội>.emits`; `consumes` thành quan hệ `read`; `requests` thành quan hệ `request`; `decides` và `escalates` sang `teams.<đội>`; `budget.daily_tokens` sang `groups.<đội>.limits.daily_tokens`.

**Ai sửa.** Người, trong tệp hoặc bằng action `ontology.save` (thay `workspace.ontology.save`). Lead tự lưu ontology; chỉ việc gỡ một cổng (`gates`) là của người và chờ ở Cần bạn. Cấp quyền khi cần ghi quan hệ vào cùng tệp. Nest vẫn sửa phần "hợp đồng" của một đội; host ghi nó về `ontology.json`. `GET /v1/ontology` (và khoá `ontology` của `GET /v1/workspace/summary`) trả tệp đã nạp, chỉ cho operator (token có phạm vi và khoá thành viên không đọc được). Peer đọc hợp đồng của đội qua `GET /v1/teams/{id}/contract`, vẫn dạng `team-contract/v1` nhưng giờ suy ra từ ontology.

**Ba lớp công cụ.** Work mail là kỹ năng mặc định của mọi Soot: tool `task` op `send` kèm cách gửi cho đúng (lấy địa chỉ từ tool, mỗi thư một việc, ghi đủ để bên nhận khỏi phải hỏi lại, không gửi lại chỉ để hỏi tiến độ). Soot ở trong một đội có thêm tool `team`. Đội đó thuộc một công ty (deployment có khối `workspace`, hoặc có ontology) thì Soot có thêm tool `workspace`. Lead không ở đội nào nhưng vẫn có `workspace`. Cả hai tool chỉ đọc và chỉ có ở lượt chạy trong không gian của chủ, không có ở khách, widget, SDK hay chat công khai.

| Tool `team`, op | Trả về |
|---|---|
| `members` | Thành viên trong đội của Soot, Đầu mối đứng đầu: `address` (`soot:<id>`, địa chỉ để gửi thư cho một đồng đội), `name`, `does` (mô tả của Soot), `coordinator`; kèm `you` |
| `about` | `address`, `name`, `description`, `projects`, `coordinator`, `inbox`, và `provides` / `consumes` / `decides` / `escalates` suy từ ontology |

Việc giao cho cả đội thì gửi `team:<id>`, Đầu mối chọn người làm. Thành viên đội khác thì không gửi thẳng được, phải qua `team:<id>` của đội đó.

Tool `workspace`:

| op | Trả về |
|---|---|
| `teams` | Mọi đội, theo id: `address` (`team:<id>`), `name`, `server` (`here` hoặc tên máy chủ của đội `remote`), `description`, `projects`, `does`, `not`, `ask`, `owns`, `provides` (thực thể đội giữ); đội của chính Soot có `yours: true` |
| `team` + `id` | Một đội, thêm `decides` và `escalates` |
| `terms` + `query` | Tối đa 20 thuật ngữ khớp tên, bí danh hoặc nghĩa, không phân biệt hoa thường và dấu; có `owner: "team:<id>"`. Không `query` thì liệt kê hết, chia trang bằng `limit`/`offset` |
| `about` | `about` và các sản phẩm của công ty |
| `entities` (+ `id`) | Thực thể: chủ, mô tả, hàng đợi, vòng đời; một thực thể thêm các đội có quan hệ với nó |
| `processes` (+ `id`) | Quy trình: thực thể, hạn, các lần chuyển (đội nào chịu), nơi bắt đầu, cổng người |

Mỗi lần gọi trả tối đa 16 KiB và báo `more: true` (kèm `next_offset`) khi bị cắt. Ontology không nằm trong system prompt hay khối mục tiêu: Soot kéo nó khi cần, nên không tốn token ở mỗi lượt. Khi địa chỉ gửi việc sai, lời từ chối liệt kê các đội, mỗi đội kèm `does` (không có thì `description`) rồi nhắc `workspace op teams` để xem đầy đủ (chỉ khi có công ty).

**Chữ không cấp quyền.** `about`, `terms`, `does`, `not`, `ask`, `owns` chỉ là chữ để hiểu: viết "đội A nhận mọi việc" không làm đội A nhận được gì. Ai được gửi việc cho đội nào, ngân sách và hộp thư vẫn do host kiểm theo `groups`. Chỉ quan hệ mới cho đội đọc hoặc xin ghi dữ liệu của đội khác, và chỉ qua tool dữ liệu có sẵn.

Mã chẩn đoán (pointer trong `ontology.json`):

| Mã | Khi nào |
|---|---|
| `ontology_team_unknown` | khoá `teams` hoặc `owner` của thuật ngữ không phải nhóm: chỉ lúc lưu (`ontology.save`); lúc nạp bị bỏ qua. Chủ thực thể, đội của quan hệ, `by` của lần chuyển không phải nhóm: lỗi cả lúc nạp |
| `ontology_term_duplicate` | thuật ngữ hoặc bí danh trùng nhau (không phân biệt hoa thường, dấu) |
| `ontology_too_large` | vượt hạn (xem trên) |
| `ontology_invalid` | ký tự điều khiển hoặc đổi chiều chữ, mục rỗng, hoặc thực thể, quan hệ, quy trình sai luật |

## Nest

| Màn hình | Làm gì | Code |
|---|---|---|
| Mục tiêu và việc (`nest://goals`) | Cây mục tiêu theo sản phẩm, bảng việc lọc theo mục tiêu hoặc "vận hành", tạo, sửa, duyệt, bỏ mục tiêu, duyệt việc lặp lại nháp, nhờ Lead soạn mục tiêu khi còn trống | `desktop/src/modules/goals/` |
| Việc › Lặp lại | Xem, tạm dừng, sửa, chạy ngay việc lặp lại, kèm `repeat.stats` | `desktop/src/modules/tasks/` |
| Công ty | Sản phẩm, đội, cái mỗi đội cung cấp, ai dựa vào ai; lớp sản phẩm chỉ hiện khi có hơn một sản phẩm | `desktop/src/modules/team/team-workspace.tsx` |
| Kết quả | Báo cáo outcome theo sản phẩm, xuất CSV | `desktop/src/modules/outcomes/` |
| Cần bạn | `goal_drafts`, `goal_changed`, lịch lỗi, đề xuất của Lead | `desktop/src/modules/needs/` |

Nest nói chuyện với nhiều máy chủ; màn hình mục tiêu gộp các máy chủ đã hỗ trợ và nói rõ máy nào chưa cập nhật. Nest không giữ mục tiêu riêng.

## Ai sở hữu gì

| Bên | Sở hữu |
|---|---|
| Core | Việc, việc lặp lại, kiểm tra quyền, báo cáo outcome, danh sách dự án `GET /v1/projects` và các hook để tính năng cắm vào |
| Tính năng workspace (`internal/feature/workspace`) | Mô hình mục tiêu, check-in, bản nháp, công cụ `goal`, khối ngữ cảnh, cadence, thẻ `goal_drafts` và `goal_changed`, route mục tiêu, config `workspace.goals`; khai sản phẩm làm dự án cho `GET /v1/projects` |
| Pack | Ý nghĩa của `metric.ref` và `guardrails[].ref`, outcome id, skill tính con số (company-loop giữ `metrics` và cược) |
| Cấu hình (người) | Sản phẩm, đội, hạn mức, cách duyệt, cadence |
| Lead | Đề xuất mục tiêu và cấu hình; không duyệt direction/cycle |
| Đầu mối | Đề xuất mục tiêu đội, chọn và bắt đầu việc trong đội, check-in |
| Nest | Hiện và gửi lệnh; không tự quyết |

Cố tình không làm: core không hiểu chỉ số cụ thể (để pack mở rộng, xem [extensions.md](https://trysoot.com/vi/docs/extensions/index.md)); mục tiêu không cấp quyền; không có hàng đợi tự nhặt việc; giá, hạn mức và quyền lợi là dữ liệu của sản phẩm, không nằm trong mục tiêu.

## Chưa có

- Chấm điểm cuối chu kỳ tự động: trường `score` (0..1) có, nhưng người hoặc đội điền.
- Core tự đọc chỉ số thật: giá trị hiện tại đến từ check-in.
- Digest "thắng tuần" do core sinh: nhịp tuần chỉ là mẫu `cadence` do người cấu hình.
- Ràng buộc đội–sản phẩm–bộ phận theo bảng `parts` của company-loop: core chỉ kiểm tra đội tồn tại, mục tiêu cha và hạn mức.
