council

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: council

Skill：council

🧭 Chọn backend cho mỗi seat (model rẻ vs Claude), chạy nhiều seat song song (1 worktree/seat — KHÔNG nhiều opencode/1 folder) → xem orca-dispatch-reference (nguồn chân lý duy nhất).

A deterministic harness around Andrej Karpathy's

llm-council

(https://github.com/karpathy/llm-council) three stages — Stage 1 "First Opinions", Stage 2 "Review" (anonymized peer-rank), Stage 3 "Final Response" (chairman) — wired onto orca orchestration.

🧭 为每个 seat 选择 backend（廉价 model 与 Claude），并行运行多个 seat（每个 seat 使用一个 worktree——不要在同一个文件夹中运行多个 opencode）→ 参见 orca-dispatch-reference（唯一事实来源）。

围绕 Andrej Karpathy 的

llm-council

(https://github.com/karpathy/llm-council) 三阶段设计的 deterministic harness： Stage 1「First Opinions」、Stage 2「Review」（匿名化 peer-rank）、 Stage 3「Final Response」（chairman），并接入 orca orchestration。

WHAT

Purpose và context

Purpose 与 context

Purpose: chạy một hội đồng LLM kiểu Karpathy 3 stage trên orca orchestration — N seat trả lời độc lập, chấm chéo MÙ (ẩn danh), chairman tổng hợp — kèm transcript tất định và report HTML bắt buộc (Stage 4).
Trigger (when to use): Hard questions where one model's answer is risky and you want a panel + an audit trail of who-ranked-what, with the favour-your-own bias removed by blinding. For a single quick answer, just ask one model. Lời gọi: "run a council", "llm-council", "panel of models", "blind peer-rank these answers", "ensemble + chairman", hoặc
```
/council
```
.
Non-goals: không dùng cho câu hỏi nhanh một đáp án;
```
council.py
```
không gọi model; không chọn model cho seat (việc của adapter
```
harness/council.config.yaml
```
); report không thêm phán xét mới ngoài transcript.

Purpose： 在 orca orchestration 上运行 3 阶段 Karpathy 风格 LLM council——N 个 seat 独立作答、进行 BLIND 交叉评审、由 chairman 综合——同时生成 deterministic transcript 和强制 HTML 报告（Stage 4）。
Trigger（何时使用）： 面对单个 model 的回答可能存在风险的困难问题，希望使用 panel，并保留 who-ranked-what 审计轨迹，同时通过 blinding 消除偏袒自身答案的倾向。如果只需要快速回答，直接询问一个 model 即可。调用方式：「run a council」「llm-council」「panel of models」「blind peer-rank these answers」「ensemble + chairman」或
```
/council
```
。
Non-goals： 不用于需要快速单答的问题；
```
council.py
```
不调用 model；不负责为 seat 选择 model（这是 adapter
```
harness/council.config.yaml
```
的职责）；report 不会添加 transcript 之外的新评判。

Mental model

Split of labour:

harness/scripts/council.py
owns the DETERMINISTIC protocol and never calls a model: anonymize (strip author → A/B/C by stable sha256 order), mean-rank aggregation, dissent surfacing, the anchor guard (seed-driven, per-judge presentation order — no
```
Math.random
```
), and the json+md transcript.
The orca orchestration owns the MODEL GENERATIONS: each seat's answer, each judge's ranking, the chairman's synthesis. It dispatches them exactly like any other multi-agent wave (see
```
orca-workflow
```
,
```
orchestration
```
).
harness/council.config.yaml
is the ONE adapter (
```
verified: false
```
): which model fills each seat, the judge models, the chairman. Every value is an
```
# ASSUMPTION (not verified)
```
. The engine never branches on these — it only stamps them into the transcript. Finalize the council by editing this one file.

question → Stage 1 answers.json → Stage 2a blind packet (A/B/C + presentation order) → Stage 2b judges.json → Stage 2c transcript (mean-rank, dissent, chairman_brief) → Stage 3 chairman_synthesis → Stage 4 HTML report versioned

职责划分：

harness/scripts/council.py
负责 DETERMINISTIC protocol，且绝不调用 model：匿名化（去除 author → 按稳定 sha256 顺序映射为 A/B/C）、mean-rank 聚合、暴露 dissent、anchor guard（由 seed 驱动、按 judge 设定 presentation order——不使用
```
Math.random
```
），以及生成 json+md transcript。
orca orchestration 负责 MODEL GENERATIONS：每个 seat 的回答、每个 judge 的排名、chairman 的综合。它与其他任何 multi-agent wave 完全相同地进行 dispatch（参见
```
orca-workflow
```
、
```
orchestration
```
）。
harness/council.config.yaml
是唯一的 adapter（
```
verified: false
```
）：指定每个 seat 使用的 model、judge models 和 chairman。每个值都是
```
# ASSUMPTION (not verified)
```
。engine 从不根据这些值分支，只会将它们写入 transcript。通过编辑这一个文件完成 council 的最终配置。

question → Stage 1 answers.json → Stage 2a blind packet（A/B/C + presentation order）→ Stage 2b judges.json → Stage 2c transcript（mean-rank、dissent、chairman_brief）→ Stage 3 chairman_synthesis → Stage 4 版本化 HTML report

。

Input và output contract

Input 与 output contract

	Field	Required?	Ý nghĩa
In	câu hỏi	có	cùng một câu cho mọi seat; `--question` để hiện trên report
In	`harness/council.config.yaml`	có	seats / judges / chairman ( `verified: false` )
In	roster persona ( `--case` / `--profile` / `--personas` )	không	lens góc nhìn thêm vào prompt Stage-1
In	`--seed N`	không	seed anchor guard, ghi đè `anchor_seed`
Out	`answers.json` · `judges.json`	có	`[{"id","author","text"}]` · `[{"judge","ranking":[...]}]`
Out	`scratchpad/council-<slug>/council.packet.{json,md}` + `council.transcript.{json,md}`	có	blind packet; consensus, winner, dissent, `chairman_brief` , `chairman_synthesis`
Out	`llmwiki/html/council/council-report-NNN-seed<seed>.html`	có (bắt buộc)	report versioned, không ghi đè; `latest.html` con trỏ

	字段	是否必填	含义
In	question	是	传给所有 seat 的同一个问题； `--question` 用于在 report 中显示
In	`harness/council.config.yaml`	是	seats / judges / chairman（ `verified: false` ）
In	roster persona（ `--case` / `--profile` / `--personas` ）	否	为 Stage-1 prompt 增加额外的 lens 视角
In	`--seed N`	否	anchor guard 的 seed，覆盖 `anchor_seed`
Out	`answers.json` · `judges.json`	是	`[{"id","author","text"}]` · `[{"judge","ranking":[...]}]`
Out	`scratchpad/council-<slug>/council.packet.{json,md}` + `council.transcript.{json,md}`	是	blind packet；consensus、winner、dissent、 `chairman_brief` 、 `chairman_synthesis`
Out	`llmwiki/html/council/council-report-NNN-seed<seed>.html`	是（强制）	版本化 report，不覆盖已有文件； `latest.html` 为便捷指针

Rules và capabilities

Rules 与 capabilities

RULE-01 (MUST): NGÔN NGỮ (bắt buộc): mọi seat/judge/chairman PHẢI trả lời bằng tiếng Việt CÓ DẤU đầy đủ; chèn câu này vào MỌI prompt Stage-1/Stage-2/Stage-3.
RULE-02 (MUST): Output run luôn dưới
```
scratchpad/council-<slug>/
```
— never bare
```
run/
```
or a repo-root folder.
RULE-03 (MUST): Blindness, not exclusion, is the guard — judge chỉ thấy nhãn A/B/C, theo presentation order của mình.
RULE-04 (MUST): Roster luôn cài ≥1 cặp đối-trọng; size lẻ (3/5) để mean-rank không hoà.
RULE-05 (MUST): Stage-4 HTML luôn render; lỗi renderer chỉ WARN, KHÔNG bao giờ giết lệnh
```
rank
```
hay
```
transcript.{json,md}
```
.
RULE-06 (MUST):
```
council.py
```
never calls a model; engine never branches on config values — chỉ stamp vào transcript.
Capabilities: dispatch model generation qua lớp orchestration (seat/judge/chairman); tính toán protocol tất định cục bộ; ghi file transcript + HTML; không mạng/CDN cho report.

RULE-01 (MUST)：语言（强制）： 所有 seat/judge/chairman 必须使用带完整变音符号的越南语回答；必须将此句插入 Stage-1/Stage-2/Stage-3 的每个 prompt。
RULE-02 (MUST)：每次运行的输出始终位于
```
scratchpad/council-<slug>/
```
——绝不使用裸露的
```
run/
```
或 repo 根目录下的文件夹。
RULE-03 (MUST)：保障机制是 Blindness（匿名化），而不是排除——judge 只能看到 A/B/C 标签，并按照自己的 presentation order 查看答案。
RULE-04 (MUST)：roster 始终包含 ≥1 对观点相反的 persona；size 使用奇数（3/5），以避免 mean-rank 出现平局。
RULE-05 (MUST)：Stage-4 HTML 必须始终完成渲染；renderer 报错时只能输出 WARN，绝不能中断
```
rank
```
或
```
transcript.{json,md}
```
。
RULE-06 (MUST)：
```
council.py
```
绝不调用 model；engine 绝不根据 config 值分支——只将其写入 transcript。
Capabilities：通过 orchestration 层 dispatch model generation（seat/judge/chairman）；在本地执行 deterministic protocol 运算；写入 transcript + HTML；report 不依赖网络或 CDN。

Failure boundaries

```
council.py selftest
```
không exit 0, hoặc
```
orca status --json
```
không có runtime chạy → blocked, không chạy council.
Seat trả lời không dấu → report cũng mất dấu (render trung thực) → nhắc lại RULE-01 và chạy lại seat đó.
Thiếu judges →
```
rank
```
chỉ phát blind packet rồi dừng (partial, chờ Stage 2b).
Renderer HTML lỗi → WARN, transcript vẫn có (partial cho Stage 4, chạy lại
```
render
```
).
Roster thiếu cặp đối-trọng → cảnh báo stderr; gõ sai case/persona → gợi ý gần nhất, không fail trơ.

```
council.py selftest
```
未以 0 退出，或
```
orca status --json
```
显示没有运行中的 runtime → blocked，不得运行 council。
seat 的回答不含变音符号 → report 同样不会显示变音符号（如实渲染）→ 提醒 RULE-01，并重新运行该 seat。
缺少 judges →
```
rank
```
只生成 blind packet，然后停止（partial，等待 Stage 2b）。
HTML renderer 报错 → 输出 WARN，transcript 仍然存在（Stage 4 为 partial，重新运行
```
render
```
）。
roster 缺少观点相反的 persona 对 → 向 stderr 输出警告；case/persona 拼写错误 → 给出最接近的建议，不发生无声失败。

HOW

Main workflow

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	repo, runtime	Preconditions: `council.py selftest` , `orca status --json` , config có seats/judges/chairman	đủ điều kiện	thiếu → blocked
W02	effect	câu hỏi (+ lens)	Stage 1 — dispatch một worker mỗi seat, gom `answers.json`	`answers.json`	seat lỗi/không dấu → chạy lại seat
W03	deterministic	`answers.json`	Stage 2a — `council.py prepare`	blind packet	—
W04	effect	packet	Stage 2b — dispatch judge với câu trả lời mù theo presentation order, gom `judges.json`	`judges.json`	—
W05	deterministic	answers + judges	Stage 2c — `council.py rank` (tự ghi Stage-4 HTML)	transcript + report	render lỗi → WARN, B02
W06	effect	`chairman_brief`	Stage 3 — dispatch chairman, dán `chairman_synthesis` vào transcript	transcript đủ	—
W07	deterministic	transcript	Stage 4 — `council.py render <transcript.json>` để report có synthesis	report versioned mới	lỗi → WARN, transcript giữ nguyên

Chi tiết từng bước (nguồn chân lý cho W01–W07):

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	repo、runtime	前置条件： `council.py selftest` 、 `orca status --json` ，且 config 中已设置 seats/judges/chairman	条件齐备	缺失 → blocked
W02	effect	question（+ lens）	Stage 1——为每个 seat dispatch 一个 worker，汇总 `answers.json`	`answers.json`	seat 失败或缺少变音符号 → 重新运行 seat
W03	deterministic	`answers.json`	Stage 2a—— `council.py prepare`	blind packet	—
W04	effect	packet	Stage 2b——按 presentation order 向 judge dispatch 盲化答案，汇总 `judges.json`	`judges.json`	—
W05	deterministic	answers + judges	Stage 2c—— `council.py rank` （自动写入 Stage-4 HTML）	transcript + report	render 失败 → WARN、B02
W06	effect	`chairman_brief`	Stage 3——dispatch chairman，将 `chairman_synthesis` 写入 transcript	完整 transcript	—
W07	deterministic	transcript	Stage 4—— `council.py render <transcript.json>` ，使 report 包含 synthesis	新版本化 report	失败 → WARN，transcript 保持不变

各步骤详情（W01–W07 的唯一事实来源）：

Preconditions

python3 harness/scripts/council.py selftest

exits 0 (engine is healthy).

```
orca status --json
```
shows a running runtime; orchestration enabled.
Seats/judges/chairman set in
```
harness/council.config.yaml
```
.

python3 harness/scripts/council.py selftest

以 0 退出（engine 健康）。

```
orca status --json
```
显示 runtime 正在运行；orchestration 已启用。
```
harness/council.config.yaml
```
中已设置 seats/judges/chairman。

Protocol (maps each stage to an orca dispatch)

Protocol（每个 stage 对应一次 orca dispatch）

Stage 1 — First Opinions (orchestration generates)

Stage 1 — First Opinions（由 orchestration 生成）

Dispatch one worker per seat in

council.config.yaml

, same question to each.

NGÔN NGỮ (bắt buộc): mọi seat/judge/chairman PHẢI trả lời bằng tiếng Việt CÓ DẤU đầy đủ (đúng chính tả, đủ dấu thanh + dấu mũ). TUYỆT ĐỐI không viết tiếng Việt không dấu (ASCII).
council.py
render trung thực text đầu vào (
ensure_ascii=False
, không normalize) — nếu seat trả lời mất dấu thì report cũng mất dấu. Chèn câu này vào MỌI prompt Stage-1/Stage-2/Stage-3.

bash

orca orchestration task-create --spec "Answer: <question>" --json
orca orchestration dispatch --task <task_id> --to <seat_handle> --inject --json
orca orchestration check --wait --types worker_done --timeout-ms 300000 --json

Collect the replies into

answers.json

—

[{"id","author","text"}, ...]

, where

author

is the seat id (the real identity; it gets stripped next).

按照

council.config.yaml

为每个 seat dispatch 一个 worker，并向所有 worker 提供同一个问题。

语言（强制）： 所有 seat/judge/chairman 必须使用带完整变音符号的越南语回答（拼写正确，完整包含声调符号和元音符号）。绝对不要写不带变音符号的越南语（ASCII）。
council.py
会如实渲染输入文本（
ensure_ascii=False
，不做 normalize）——如果 seat 的回答丢失变音符号，report 也会丢失。必须将此句插入 Stage-1/Stage-2/Stage-3 的每个 prompt。

bash

orca orchestration task-create --spec "Answer: <question>" --json
orca orchestration dispatch --task <task_id> --to <seat_handle> --inject --json
orca orchestration check --wait --types worker_done --timeout-ms 300000 --json

将回复汇总到

answers.json

——

[{"id","author","text"}, ...]

，其中

author

是 seat id（真实身份，下一步会被去除）。

Stage 2a — blind packet (council.py is deterministic)

Stage 2a — blind packet（由 council.py deterministic 处理）

bash

python3 harness/scripts/council.py prepare answers.json --config harness/council.config.yaml --out scratchpad/council-<slug>/

<slug>

= short name for this run (e.g.

release-gate

). Always under

scratchpad/

(gitignored, per-repo convention) — never bare

run/

or a repo-root folder; those leak as untracked clutter that never gets cleaned up (lesson 170726, 6 stray

run-council*/

dirs found at repo root from past sessions copying this example literally). Writes

scratchpad/council-<slug>/council.packet.{json,md}

: the answers relabelled A/B/C with authors removed, plus each judge's presentation order from the anchor guard. Show each judge its answers in its row's order to cancel position bias.

bash

python3 harness/scripts/council.py prepare answers.json --config harness/council.config.yaml --out scratchpad/council-<slug>/

<slug>

是本次运行的短名称（例如

release-gate

）。始终位于

scratchpad/

下（遵循 repo 约定并被 gitignore）——绝不使用裸露的

run/

或 repo 根目录下的文件夹；这些会成为永不会清理的 untracked 杂物（lesson 170726，过去的 session 照搬此示例，在 repo 根目录发现了 6 个多余的

run-council*/

目录）。该命令会写入

scratchpad/council-<slug>/council.packet.{json,md}

：答案被重新标记为 A/B/C 并移除 author，同时附上 anchor guard 为每个 judge 确定的 presentation order。让每个 judge 按其所在行的顺序查看答案，以消除位置偏差。

Stage 2b — Review (orchestration generates)

Stage 2b — Review（由 orchestration 生成）

Dispatch each judge in

council.config.yaml

the BLIND answers, in that judge's presentation order. Ask each to return a ranking of the labels (best first). Collect into

judges.json

—

[{"judge","ranking":["B","A","C"]}, ...]

Blindness, not exclusion, is the guard: a judge may be a seat, but it cannot recognise its own answer, so it cannot play favourites.

按照每个 judge 自己的 presentation order，向其 dispatch

council.config.yaml

中的 BLIND 答案。要求每个 judge 返回标签的排名（最佳答案排在最前）。

将结果汇总到

judges.json

——

[{"judge","ranking":["B","A","C"]}, ...]

。

保障机制是 Blindness，而不是排除：judge 可以同时也是一个 seat，但无法识别自己的答案，因此不能偏袒自己。

Stage 2c — aggregate (council.py is deterministic)

Stage 2c — aggregate（由 council.py deterministic 处理）

bash

python3 harness/scripts/council.py rank answers.json --judges judges.json --config harness/council.config.yaml --out scratchpad/council-<slug>/

Writes

scratchpad/council-<slug>/council.transcript.{json,md}

: mean-rank consensus, the winner, the dissent table (most-contested answer), and a

chairman_brief

bash

python3 harness/scripts/council.py rank answers.json --judges judges.json --config harness/council.config.yaml --out scratchpad/council-<slug>/

写入

scratchpad/council-<slug>/council.transcript.{json,md}

：mean-rank consensus、winner、dissent table（争议最大的答案）以及

chairman_brief

。

Stage 3 — Final Response (orchestration generates)

Stage 3 — Final Response（由 orchestration 生成）

Dispatch the chairman the

chairman_brief

from the transcript (consensus order + the dissent points it must resolve). Its synthesis is the final answer; paste it back under

chairman_synthesis

in the transcript for the record, then

council.py render <transcript.json>

to regenerate the Stage-4 HTML with the synthesis shown (the report auto-written during

rank

has an empty synthesis because

rank

rebuilds from answers+judges only).

将 transcript 中的

chairman_brief

dispatch 给 chairman（共识顺序 + chairman 必须解决的 dissent 点）。其 synthesis 是最终答案；将其粘贴回 transcript 的

chairman_synthesis

中留档，然后运行

council.py render <transcript.json>

，重新生成包含 synthesis 的 Stage-4 HTML（rank 期间自动写入的 report 中 synthesis 为空，因为 rank 仅根据 answers+judges 重建）。

Stage 4 — HTML report (MANDATORY, tự render trong council.py, offline)

Stage 4 — HTML report（强制，由 council.py 内部离线渲染）

Luôn render — không cần cờ, không phụ thuộc skill ngoài. Mỗi lần

rank

thành công,

render_report_html(t, personas)

(nằm ngay trong

council.py

) ghi một
.html
versioned —

llmwiki/html/council/council-report-NNN-seed<seed>.html

(NNN tăng dần, KHÔNG ghi đè → mỗi run một bản ghi bất biến) +

latest.html

là con trỏ tiện dụng (gitignore, tránh diff-churn). Không CDN (system font + inline SVG favicon/grain) → offline; không coupling

docs-site-macos

. Feed thuần từ transcript vừa build (

) → không bịa gì mới, mọi chuỗi seat

html.escape

tại chỗ (chống HTML-injection). Toàn khối render bọc try/except: lỗi renderer chỉ WARN, KHÔNG bao giờ giết lệnh

rank

hay

transcript.{json,md}

(Taleb blast-radius guard). Tên+lăng kính ủy viên lấy từ

council.personas.yaml

; câu hỏi hiển thị khi truyền

--question

(bỏ trống → report ẩn dòng question thay vì in placeholder).

Trang có đúng ba section, theo thứ tự:

Ý kiến hội đồng. Mỗi seat một card (viền màu =
```
sha256(author)
```
, xếp theo consensus rank + huy chương), answer tự format
```
(1)(2)(3)
```
thành list. Nguồn:
```
t["answers"]
```
+
```
t["aggregate"]
```
.
Bỏ phiếu KÍN (blind vote). Bảng phiếu dùng NHÃN A/B/C ẩn danh: mỗi judge một hàng, ranking theo nhãn + presentation-order của anchor guard. Reveal map A/B/C → author chỉ ở cuối section. Nguồn:
```
t["judge_rankings"]
```
+
```
t["anchor_guard"]
```
.
Dashboard cuối. KPI (winner / most-contested / đồng thuận) + bảng mean-rank consensus, và
```
chairman_synthesis
```
hiển thị nổi bật KHI đã được dán vào transcript (rank build lại từ answers+judges nên field này rỗng cho tới khi chairman fill — lúc đó khối synth tự ẩn). Nguồn:
```
t["winner"]
```
/
```
t["most_contested"]
```
/
```
t["aggregate"]
```
.

Vì mọi số liệu lấy từ transcript đã deterministic, report chỉ là lớp trình bày — không thêm phán xét mới. Same transcript → cùng HTML.

始终渲染——不需要 flag，也不依赖外部 skill。 每次

rank

成功后，

render_report_html(t, personas)

（直接位于

council.py

中）会写入一个版本化的
.html
文件——

llmwiki/html/council/council-report-NNN-seed<seed>.html

（NNN 递增，绝不覆盖 → 每次运行都保留一份不可变记录）+

latest.html

作为便捷指针（加入 gitignore，避免 diff churn）。不使用 CDN（system font + inline SVG favicon/grain）→ 完全离线；不与

docs-site-macos

耦合。数据仅来自刚构建的 transcript（

）→ 不会编造任何新内容；所有 seat 字符串都在写入时通过

html.escape

处理（防止 HTML-injection）。整个 render 块都包裹在 try/except 中：renderer 出错时只输出 WARN，绝不会中断

rank

或

transcript.{json,md}

（Taleb blast-radius guard）。委员的名称和 lens 来自

council.personas.yaml

；传入

--question

时显示问题（留空 → report 隐藏 question 行，而不是打印 placeholder）。

页面严格包含以下三个 section，并按此顺序排列：

委员会意见。 每个 seat 对应一张 card（边框颜色 =
```
sha256(author)
```
，按 consensus rank + 奖章排序），answer 中的
```
(1)(2)(3)
```
会自动格式化为列表。 来源：
```
t["answers"]
```
+
```
t["aggregate"]
```
。
匿名投票（blind vote）。 投票表使用匿名的 A/B/C 标签：每个 judge 占一行，ranking 按标签和 anchor guard 的 presentation order 排列。仅在 section 末尾揭示 A/B/C → author 的映射。 来源：
```
t["judge_rankings"]
```
+
```
t["anchor_guard"]
```
。
最终 Dashboard。 包含 KPI（winner / most-contested / consensus）、mean-rank consensus 表，并在
```
chairman_synthesis
```
已写入 transcript 时突出显示（rank build 仅根据 answers+judges 重建，因此该字段在 chairman fill 前为空；填入后 synth 区块自动显示）。 来源：
```
t["winner"]
```
/
```
t["most_contested"]
```
/
```
t["aggregate"]
```
。

由于所有数字都来自 deterministic transcript，report 只是展示层——不会增加新的评判。相同 transcript → 相同 HTML。

Branches

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	user_optional	muốn đa dạng GÓC NHÌN (ít provider)	bốc roster persona (mục Persona lenses dưới), chèn lens vào prompt Stage-1 (động) hoặc field `persona:` trong config (cố định); roster + lý do ghi vào transcript	không bốc → seat = model thuần	W02
B02	recovery	report HTML lỗi hoặc cần hiện `chairman_synthesis`	chạy lại `council.py render <transcript.json>` → versioned file mới	renderer vẫn lỗi → WARN, transcript là nguồn	kết thúc
B03	conditional_required	chạy `rank` không có `--judges`	chỉ phát blind packet rồi dừng	—	W04

ID	Kind	Guard	Behaviour	Skip / failure	Rejoin
B01	user_optional	需要多样化视角（provider 较少）	抽取 roster persona（见下方 Persona lenses），将 lens 动态插入 Stage-1 prompt，或在 config 中固定设置 `persona:` 字段；将 roster + 抽取原因写入 transcript	不抽取 → seat = 纯 model	W02
B02	recovery	report HTML 出错，或需要显示 `chairman_synthesis`	重新运行 `council.py render <transcript.json>` → 生成新的版本化文件	renderer 仍然出错 → WARN，transcript 仍是事实来源	结束
B03	conditional_required	运行 `rank` 时未提供 `--judges`	只生成 blind packet，然后停止	—	W04

Validation và stopping

Validation 与 stopping

Tất định:

selftest

(12 checks) chứng minh cùng

answers.json

judges.json

+ seed → transcript byte-identical; report chỉ là lớp trình bày của transcript. Cần review: chất lượng synthesis của chairman. Dừng sau W07 khi report có synthesis.

Deterministic：

selftest

（12 项检查）证明相同的

answers.json

judges.json

+ seed 会产生 byte-identical transcript；report 只是 transcript 的展示层。需要人工 review：chairman synthesis 的质量。当 report 已包含 synthesis 时，在 W07 后停止。

Examples

Positive: "run a council: có nên tách monorepo không" với
```
roster --case decision
```
3 ghế → 3 seat trả lời tiếng Việt có dấu →
```
prepare
```
ra A/B/C → 3 judge rank →
```
rank --out scratchpad/council-monorepo/
```
ra winner + dissent → chairman tổng hợp →
```
render
```
ghi
```
council-report-NNN-seed<seed>.html
```
có synthesis.
Boundary/failure:
```
council.py selftest
```
exit khác 0 → dừng ở W01, không dispatch seat nào. Renderer lỗi trong
```
rank
```
→ chỉ WARN,
```
council.transcript.json
```
vẫn được ghi, chạy lại
```
render
```
sau.

Positive：「run a council：是否应该拆分 monorepo？」配合
```
roster --case decision
```
生成 3 个 seat → 3 个 seat 使用带变音符号的越南语回答 →
```
prepare
```
生成 A/B/C → 3 个 judge rank →
```
rank --out scratchpad/council-monorepo/
```
生成 winner + dissent → chairman 综合 →
```
render
```
写入包含 synthesis 的
```
council-report-NNN-seed<seed>.html
```
。
Boundary/failure：
```
council.py selftest
```
的退出码不为 0 → 停在 W01，不 dispatch 任何 seat。
```
rank
```
期间 renderer 出错 → 只输出 WARN，
```
council.transcript.json
```
仍会写入，之后重新运行
```
render
```
。

Reference — Persona lenses — góc nhìn "vĩ nhân" (optional, ADDITIVE)

Reference — Persona lenses —「伟人」视角（可选，ADDITIVE）

Mặc định mỗi seat = một MODEL trả lời. Lớp persona thêm đa-dạng GÓC NHÌN: mỗi seat đội một lens (Feynman / Munger / Taleb / Rams …) — quan trọng khi đa-dạng-model bị hạn chế (chỉ có ít provider). Engine

council.py

KHÔNG đổi: persona chỉ là chữ nhét vào prompt Stage-1.

Quên tên ai / cú pháp gì?

council.py roster --list

(hoặc

roster

trống) in hết case (theo VIỆC) · profile · 18 persona — chọn

--case

theo việc, không cần nhớ tên. Nhớ nhầm vẫn gọi chính xác được: khớp theo TÊN lẫn id, không phân biệt hoa/thường (

--personas Feynman,Taleb

ok); gõ sai → gợi ý gần nhất (

--case risks

→ "ý bạn là 'risk'?"), không fail trơ.

Bốc 3-5 người theo case (thuần code, log-được):

bash

python3 harness/scripts/council.py roster --list                 # catalog: case/profile/persona
python3 harness/scripts/council.py roster --case risk            # 3 ghế, có ≥1 cặp đối-trọng
python3 harness/scripts/council.py roster --case ml-ai --size 5  # 5 ghế
python3 harness/scripts/council.py roster --profile lean         # 5 người execution-lean
python3 harness/scripts/council.py roster --personas feynman,taleb,rams --json

Case tag:

design · strategy · debug · risk · product · decision · simplify · ml-ai

(bảng trong

harness/council.personas.yaml

Luật: roster luôn cài ≥1 cặp đối-trọng (chống phòng vọng âm); thiếu → cảnh báo ở stderr. Size lẻ (3/5) để mean-rank không hoà.
Thư viện: 18 persona + 13 cặp đối-trọng (nguồn
```
github.com/0xNyk/council-of-high-intelligence
```
).

Dùng trong protocol: sau khi bốc roster, gán mỗi persona vào một seat — có 2 cách:

Động (khuyên): orchestrator lấy output
```
roster --json
```
, với mỗi seat chèn lens vào prompt Stage-1: "Trả lời qua lăng kính <name>: <lens>. <sig>."
Cố định: điền field
```
persona:
```
mỗi seat trong
```
harness/council.config.yaml
```
.

Roster + lý do bốc (case, cặp tension) ghi vào transcript để auditable (Trụ 5). Phần "model nào fill seat" vẫn là unknown đã quarantine ở

council.config.yaml

(

verified

) — persona-lens độc lập với nó.

默认每个 seat = 一个 MODEL 回答。Persona 层增加多样化视角：每个 seat 佩戴一个 lens（Feynman / Munger / Taleb / Rams 等）——当多 model 方案受限时（只有少数 provider），这一点尤其重要。Engine

council.py

不变：persona 仅作为文本插入 Stage-1 prompt。

忘记名称或命令语法？

council.py roster --list

（或直接运行

roster

）会打印全部 case（按工作类型）· profile · 18 persona——按

--case

选择工作类型，无需记忆名称。即使记错也能准确调用：既可按名称也可按 id 匹配，不区分大小写（
--personas Feynman,Taleb
可用）；拼写错误 → 给出最接近的建议（

--case risks

→「你是指 'risk' 吗？」），不会无声失败。

按 case 抽取 3–5 人（纯代码、可记录日志）：

bash

python3 harness/scripts/council.py roster --list                 # catalog: case/profile/persona
python3 harness/scripts/council.py roster --case risk            # 3 ghế, có ≥1 cặp đối-trọng
python3 harness/scripts/council.py roster --case ml-ai --size 5  # 5 ghế
python3 harness/scripts/council.py roster --profile lean         # 5 người execution-lean
python3 harness/scripts/council.py roster --personas feynman,taleb,rams --json

Case tag：

design · strategy · debug · risk · product · decision · simplify · ml-ai

（表格位于

harness/council.personas.yaml

）。

**规则：**roster 始终包含 ≥1 对观点相反的 persona（防止群体偏袒）；缺失时向 stderr 输出警告。Size 使用奇数（3/5），以避免 mean-rank 出现平局。
库：18 persona + 13 对观点相反的 persona（来源：
```
github.com/0xNyk/council-of-high-intelligence
```
）。

**在 protocol 中使用：**抽取 roster 后，将每个 persona 分配给一个 seat——有两种方式：

**动态（推荐）：**orchestrator 获取
```
roster --json
```
输出，并为每个 seat 将 lens 插入 Stage-1 prompt：「Trả lời qua lăng kính <name>: <lens>. <sig>.」
**固定：**在
```
harness/council.config.yaml
```
中为每个 seat 填写
```
persona:
```
字段。

Roster + 抽取原因（case、tension pair）会写入 transcript，以便审计（支柱 5）。「哪个 model 填充 seat」仍是未知项，已在

harness/council.config.yaml

中隔离（

verified

）；它与 persona-lens 相互独立。

Reference — council.py commands

Command	Does
`rank <answers.json> --judges <judges.json>`	full aggregation → transcript.json + .md
`rank <answers.json> --judges <j>`	+ auto-writes versioned `llmwiki/html/council/council-report-NNN-seed<seed>.html` (Stage-4, mandatory)
`rank <answers.json>` (no judges)	emits the blind packet, then stops
`prepare <answers.json>`	blind packet only (Stage 2a)
`render <transcript.json>`	re-render Stage-4 HTML từ transcript đã có (vd sau khi dán `chairman_synthesis` ) → versioned file mới
`roster --case <tag>` / `--profile <p>` / `--personas a,b,c`	bốc 3-5 persona-lens (thuần lookup, ≥1 cặp đối-trọng); `--size 3\|5` , `--json`
`selftest`	conformance vectors; asserts determinism + correctness

Flags:

--seed N

(anchor-guard seed; overrides config

anchor_seed

--out DIR

(transcript json/md),

--config harness/council.config.yaml

--question "..."

(câu hỏi thật hiện trên report; bỏ trống → ẩn dòng question). Stage-4 HTML versioned luôn ghi vào

llmwiki/html/council/

— no flag needed.

Command	作用
`rank <answers.json> --judges <judges.json>`	完整聚合 → transcript.json + .md
`rank <answers.json> --judges <j>`	额外自动写入版本化的 `llmwiki/html/council/council-report-NNN-seed<seed>.html` （Stage-4，强制）
`rank <answers.json>` （无 judges）	生成 blind packet，然后停止
`prepare <answers.json>`	仅生成 blind packet（Stage 2a）
`render <transcript.json>`	根据已有 transcript 重新渲染 Stage-4 HTML（例如粘贴 `chairman_synthesis` 之后）→ 生成新的版本化文件
`roster --case <tag>` / `--profile <p>` / `--personas a,b,c`	抽取 3–5 个 persona-lens（纯 lookup，≥1 对观点相反的 persona）； `--size 3\|5` 、 `--json`
`selftest`	conformance vectors；断言 determinism + correctness

Flags：

--seed N

（anchor-guard seed；覆盖 config 中的

anchor_seed

）、

--out DIR

（transcript json/md）、

--config harness/council.config.yaml

、

--question "..."

（在 report 中显示真实问题；留空 → 隐藏 question 行）。版本化的 Stage-4 HTML 始终写入

llmwiki/html/council/

——无需额外 flag。

Reference — Adapter boundary (build-now-adapt-later)

Reference — Adapter boundary（build-now-adapt-later）

Contract (built + tested now): the json schemas (
```
answers.json
```
,
```
judges.json
```
, transcript) and all the deterministic ops in
```
council.py
```
.
Quarantine (
verified: false
): model identities in
```
harness/council.config.yaml
```
. The math is independent of them.
Adapt later (one file): edit seats/judges/chairman in the config, run a real council, then flip
```
verified: true
```
. No engine change.

**Contract（当前已构建并测试）：**json schemas（
```
answers.json
```
、
```
judges.json
```
、transcript）以及
```
council.py
```
中所有 deterministic 运算。
Quarantine（
verified: false
）：
```
harness/council.config.yaml
```
中的 model identities。协议运算不依赖这些身份。
**Adapt later（只需一个文件）：**在 config 中编辑 seats/judges/chairman，运行一次真实 council，然后将
```
verified
```
改为
```
true
```
。无需修改 engine。

Reference — Determinism guarantees

Same

answers.json

judges.json

+ seed → byte-identical transcript every run. Anonymization depends on

sha256(id)

, not input order or author, so neither position nor authorship leaks. The anchor guard is seeded per judge from the arg — never the global RNG.

selftest

proves all of this (12 checks).

每次运行使用相同的

answers.json

judges.json

+ seed，都会产生 byte-identical transcript。匿名化依赖

sha256(id)

，而不是输入顺序或 author，因此 position 和 authorship 都不会泄露。Anchor guard 根据参数为每个 judge 单独设定 seed——绝不使用全局 RNG。

selftest

会证明以上性质（12 项检查）。