@akagilnc/pi-workflow-roles 0.1.4259 → 0.1.4274

package/README.md

@@ -20,12 +20,12 @@ Publish routing (Actions, not local stamp): successful `ci` push on the reposito
 `ak-role` is the only supported way to call the package. Every run writes its complete Terminal result to stdout—read or redirect it there, never scrape Pi session files:
 
 ```bash
-ak-role judge --attach ./plan.md "Review this plan." > result.txt
+ak-role judge --model <provider/model[:thinking]> --attach ./plan.md "Review this plan." > result.txt
 ```
 
 Exit status reports lifecycle honesty, not business success: every lawful typed result (including `audit_escalation`) exits zero; a failure without a lawful result exits nonzero, and its Terminal carries the Error Artifact ref and original cause instead of a fabricated receipt.
 
-`ak-role resume <runId> [message]` reopens that run under the **current seat table** for model / host / engine — the same resolution as starting a new leg (`--flag` → persistent seat → package default). Standard chain after a role `escalate`s: take the owner ruling and feed it back with `ak-role resume <runId> "<ruling>"` so the same run continues to a terminal. `[message]` applies only to seats that accept caller instruction: for those seats the optional `message` after `runId` is passed through unchanged as the continuation prompt (opaque: not parsed as flags); omit it to use the package resume envelope. Notary/符宝郎 must omit `message` and derives evidence from the existing source-run/dossier binding. Global `--model` / `--thinking` / `--host` / `--engine` override the table for that resume only — place them before `<runId>` (either before `resume` or between `resume` and `<runId>`, e.g. `ak-role --model xai/grok-4.5 resume 01abc…` or `ak-role resume --model xai/grok-4.5 01abc…`); the one argv after `<runId>` is always the opaque message, never a flag (#471). On a real host switch (live seat host differs from the previous invocation host), prior native records of the previous host are delivered once as context to the target host; same-host resume does not re-inject. Each host writes only its native volume (Pi: `session/session.jsonl`; Grok CLI journals stay in the operator grok home, factory dossier is sitian records on the run), with unified ledger entries recorded in 司天台 (Sitian). Whether to resume is the caller's decision: the command does not require a typed HTTP 429 or a `resumable` state. Unknown run IDs and missing session principals are rejected. Every callable role accepts manual resume; Countersign and Gleaner-Left gained it in #599, Collector, Doctor, Notary, and Inspector in #633.
+`ak-role resume <runId> [message]` reopens that run under the **current seat table** for model / host / engine — the same resolution as starting a new leg (model: `--model` → persistent seat → officer inherit; still none → error. host: `--host` → persistent seat host → package default `pi`). Configure seats first with `ak-role config set <seat> <provider/model[:thinking]>` or pass `--model` per invocation. Standard chain after a role `escalate`s: take the owner ruling and feed it back with `ak-role resume <runId> "<ruling>"` so the same run continues to a terminal. `[message]` applies only to seats that accept caller instruction: for those seats the optional `message` after `runId` is passed through unchanged as the continuation prompt (opaque: not parsed as flags); omit it to use the package resume envelope. Notary/符宝郎 must omit `message` and derives evidence from the existing source-run/dossier binding. Global `--model` / `--thinking` / `--host` / `--engine` override the table for that resume only — place them before `<runId>` (either before `resume` or between `resume` and `<runId>`, e.g. `ak-role --model xai/grok-4.5 resume 01abc…` or `ak-role resume --model xai/grok-4.5 01abc…`); the one argv after `<runId>` is always the opaque message, never a flag (#471). On a real host switch (live seat host differs from the previous invocation host), prior native records of the previous host are delivered once as context to the target host; same-host resume does not re-inject. Each host writes only its native volume (Pi: `session/session.jsonl`; Grok CLI journals stay in the operator grok home, factory dossier is sitian records on the run), with unified ledger entries recorded in 司天台 (Sitian). Whether to resume is the caller's decision: the command does not require a typed HTTP 429 or a `resumable` state. Unknown run IDs and missing session principals are rejected. Every callable role accepts manual resume; Countersign and Gleaner-Left gained it in #599, Collector, Doctor, Notary, and Inspector in #633.
 
 All callable roles also retry a non-lawful LLM call in place (same `runId` and session) up to `autoResumeLimit` times. Unset defaults to 2; `ak-role config set-auto-resume-limit <N>` writes the ceiling (`0` disables). Lawful typed terminals (`accepted`, `audit_escalation`, `no_receipt`) stop immediately. Manual `ak-role resume` stays available.
 
@@ -67,60 +67,64 @@ Gate submission gate: on DONE-side submissions (`completed` / `partially_complet
 The examples below are usage sketches; option identity, aliases, requiredness, and mode faces are owned by `ak-role help <command>`, not by a second flag contract here.
 
 ```bash
+# model axis (#178): caller specifies — either configure the seat once…
+#   ak-role config set <seat> <provider/model[:thinking]>
+# …or pass --model on the call (shown below). No package default model.
+
 # countersign — ticket-court review before work starts; admission runs the ticket's diarist first (#742, caller-transparent); resume continues the exact session
-ak-role countersign --attach ./ticket.md "裁：本票 #582 是否足以开工。"
+ak-role countersign --model <provider/model[:thinking]> --attach ./ticket.md "裁：本票 #582 是否足以开工。"
 
 # gleaner-left — unanchored pre-merge memorials; resume continues the exact session; --base required; instruction may be empty; callers must not pass directional instruction
-ak-role gleaner-left --base main
+ak-role gleaner-left --model <provider/model[:thinking]> --base main
 
 # judge — adjudicate the supplied materials
-ak-role judge --attach ./findings.md --attach ./adr.md "Adjudicate every finding."
+ak-role judge --model <provider/model[:thinking]> --attach ./findings.md --attach ./adr.md "Adjudicate every finding."
 
 # coder — first implementation
-ak-role coder plan "Propose the first implementation plan."
-ak-role coder apply --attach ./plan.md "Implement the approved slice."
+ak-role coder --model <provider/model[:thinking]> plan "Propose the first implementation plan."
+ak-role coder --model <provider/model[:thinking]> apply --attach ./plan.md "Implement the approved slice."
 
 # reviewer — fixed-target two-axis review; completed ≠ approved, read the findings
-ak-role reviewer --base main "Review the branch."
+ak-role reviewer --model <provider/model[:thinking]> --base main "Review the branch."
 
 # collector — GitHub PR review evidence (bind target, read handbook/field activity, trigger as needed, wait window, return materials)
-ak-role collector --pr 42 --repo owner/repository "Collect findings for the assigned issue."
-ak-role collector --repo owner/repository "Collect findings for #42"
+ak-role collector --model <provider/model[:thinking]> --pr 42 --repo owner/repository "Collect findings for the assigned issue."
+ak-role collector --model <provider/model[:thinking]> --repo owner/repository "Collect findings for #42"
 # optional: wait-window ms after the work step opens (default 600000 = 10 minutes)
-ak-role collector --pr 42 --repo owner/repository --wait-ms 120000 "Collect with a 2-minute window."
+ak-role collector --model <provider/model[:thinking]> --pr 42 --repo owner/repository --wait-ms 120000 "Collect with a 2-minute window."
 
 # fixer — repair the assigned findings
-ak-role fixer --attach ./findings.md --prerequisites ./prereqs.json "Repair the findings."
+ak-role fixer --model <provider/model[:thinking]> --attach ./findings.md --prerequisites ./prereqs.json "Repair the findings."
 
 # doctor — diagnose one retained case
-ak-role doctor --issue 115 "Diagnose this retained case."
+ak-role doctor --model <provider/model[:thinking]> --issue 115 "Diagnose this retained case."
 
 # merger — reconcile merge materials (role escalates when nothing is in progress)
-ak-role merger --project /path/to/worktree "Reconcile the merge."
+ak-role merger --model <provider/model[:thinking]> --project /path/to/worktree "Reconcile the merge."
 
 # notary — document-fidelity check on one retained source run; ticket key inherited from source-run admitted form
-ak-role notary --source-run <runId@role|path>
+ak-role notary --model <provider/model[:thinking]> --source-run <runId@role|path>
 
 # inspector — direct complexity and test-quality check
-ak-role inspector --attach ./change.patch "Review this material."
+ak-role inspector --model <provider/model[:thinking]> --attach ./change.patch "Review this material."
 
 # gatekeeper — direct Gate province review; dispatch an officer or pass
-ak-role gatekeeper --attach ./submission.json "审：这批材料该谁审？"
+ak-role gatekeeper --model <provider/model[:thinking]> --attach ./submission.json "审：这批材料该谁审？"
 
 # navigator — direct route advice (ordered next-role candidates); attends automatically on top-level public entry legs only
-ak-role navigator "刚完成 coder apply 收敛，下一步？"
+ak-role navigator --model <provider/model[:thinking]> "刚完成 coder apply 收敛，下一步？"
 
 # diarist — gather and organize this case's decision basis into its per-ticket 起居录 (LLM resolves the ticket itself, no mechanical verification since #779; countersign admission runs it automatically, other stations summon it explicitly)
-ak-role diarist "整理 #708 的本案依据。"
+ak-role diarist --model <provider/model[:thinking]> "整理 #708 的本案依据。"
 
 # countersign — ticket-court five questions; ticket recognition via instruction; admission runs the ticket's diarist first (#742)
-ak-role countersign --attach ./ticket.md "裁：本票 #582 是否足以开工。"
+ak-role countersign --model <provider/model[:thinking]> --attach ./ticket.md "裁：本票 #582 是否足以开工。"
 
-# analyst — deterministic metrics; bare call = whole book
+# analyst — deterministic metrics; bare call = whole book (no model seat)
 ak-role analyst
 
 # after escalate: feed the owner ruling into the same session (standard chain)
-ak-role resume <runId> "<ruling>"
+ak-role --model <provider/model[:thinking]> resume <runId> "<ruling>"
 ```
 
 ## Names

package/README.zh-CN.md

@@ -20,12 +20,12 @@ export PATH="$HOME/.pi/agent/npm/node_modules/.bin:$PATH"
 `ak-role` 是唯一受支持的调用方式。每次运行的完整 Terminal 结果写在 stdout——从那里读或正常重定向，不要刮 Pi session 文件：
 
 ```bash
-ak-role judge --attach ./plan.md "Review this plan." > result.txt
+ak-role judge --model <provider/model[:thinking]> --attach ./plan.md "Review this plan." > result.txt
 ```
 
 退出码报的是生命周期诚实，不是业务成败：一切合法 typed 终态（含 `audit_escalation`）退出零；无合法终态的失败退出非零，其 Terminal 携带 Error Artifact 引用与原始原因，不伪造回执。
 
-`ak-role resume <runId> [message]` 按**现行席位表**的 model / host / engine 续跑该次运行——与新起角色腿同一解析（调用旗 → 席位持久 → 包默认）。角色 `escalate`（直通御前）后拿到 owner 裁定，标准续跑是 `ak-role resume <runId> "<裁定>"`——把裁定喂回同一 run，角色继续走到终局。`[message]` 只适用于接收 caller instruction 的席位：对这些席位，`runId` 后可选的 `message` 原样作为续跑 prompt（opaque：不进全局旗标语法）；省略则用包自带 resume envelope。Notary/符宝郎必须省略 `message`，仅从既有 source-run/案卷绑定自取证。全局 `--model` / `--thinking` / `--host` / `--engine` 仅覆盖本次 resume——须置于 `<runId>` 之前（放 `resume` 之前或 `resume` 与 `<runId>` 之间均可，例如 `ak-role --model xai/grok-4.5 resume 01abc…` 或 `ak-role resume --model xai/grok-4.5 01abc…`）；`<runId>` 之后的那一个 argv 恒为原样透传的 message，绝非旗位（#471）。真实换宿主时（现行席位 host 与上一次 invocation host 不同），将前序宿主原生卷宗一次性作为 context 交付目标宿主；同宿主续跑不重复注入。各宿主仅直写自身原生卷宗（Pi：`session/session.jsonl`；Grok CLI 原始会话留在操作员 grok 家，工厂卷宗为该 run 的司天台记录），统一账目归入司天台。要不要续跑由调用者决定：不再要求 typed HTTP 429，也不要求 `resumable` 状态。未知 run ID、session 主体不在则拒绝。所有可调用角色均可手动 resume：给事中、左拾遗始于 #599，通进司、太医署、符宝郎、台院始于 #633。
+`ak-role resume <runId> [message]` 按**现行席位表**的 model / host / engine 续跑该次运行——与新起角色腿同一解析（model：`--model` → 席位持久 → 官席继承；仍无则报错。host：`--host` → 席位持久 host → 包默认 `pi`）。先 `ak-role config set <seat> <provider/model[:thinking]>` 配席，或逐次带 `--model`。角色 `escalate`（直通御前）后拿到 owner 裁定，标准续跑是 `ak-role resume <runId> "<裁定>"`——把裁定喂回同一 run，角色继续走到终局。`[message]` 只适用于接收 caller instruction 的席位：对这些席位，`runId` 后可选的 `message` 原样作为续跑 prompt（opaque：不进全局旗标语法）；省略则用包自带 resume envelope。Notary/符宝郎必须省略 `message`，仅从既有 source-run/案卷绑定自取证。全局 `--model` / `--thinking` / `--host` / `--engine` 仅覆盖本次 resume——须置于 `<runId>` 之前（放 `resume` 之前或 `resume` 与 `<runId>` 之间均可，例如 `ak-role --model xai/grok-4.5 resume 01abc…` 或 `ak-role resume --model xai/grok-4.5 01abc…`）；`<runId>` 之后的那一个 argv 恒为原样透传的 message，绝非旗位（#471）。真实换宿主时（现行席位 host 与上一次 invocation host 不同），将前序宿主原生卷宗一次性作为 context 交付目标宿主；同宿主续跑不重复注入。各宿主仅直写自身原生卷宗（Pi：`session/session.jsonl`；Grok CLI 原始会话留在操作员 grok 家，工厂卷宗为该 run 的司天台记录），统一账目归入司天台。要不要续跑由调用者决定：不再要求 typed HTTP 429，也不要求 `resumable` 状态。未知 run ID、session 主体不在则拒绝。所有可调用角色均可手动 resume：给事中、左拾遗始于 #599，通进司、太医署、符宝郎、台院始于 #633。
 
 全部可调用角色在单次调用内对非 lawful LLM 终态原地续跑（同一 `runId` 与 session），次数上限为 `autoResumeLimit`。缺键默认 2；`ak-role config set-auto-resume-limit <N>` 写入（`0` 关闭自动续）。lawful typed 终态（`accepted` / `audit_escalation` / `no_receipt`）立即停止。手动 `ak-role resume` 仍可用。
 
@@ -67,54 +67,57 @@ ak-role config set-auto-resume-limit 3
 下例只是用法速写；option 身份、别名、必填性与 mode 面以 `ak-role help <command>` 为准，不另立第二份旗标合同。
 
 ```bash
+# model 轴（#178）：调用者指定——可先 `ak-role config set <seat> <provider/model[:thinking]>`
+# 配席，或如下逐次带 `--model`。无包内默认模型。
+
 # 大理寺——审断所供材料
-ak-role judge --attach ./findings.md --attach ./adr.md "Adjudicate every finding."
+ak-role judge --model <provider/model[:thinking]> --attach ./findings.md --attach ./adr.md "Adjudicate every finding."
 
 # 将作监——营造新作
-ak-role coder plan "Propose the first implementation plan."
-ak-role coder apply --attach ./plan.md "Implement the approved slice."
+ak-role coder --model <provider/model[:thinking]> plan "Propose the first implementation plan."
+ak-role coder --model <provider/model[:thinking]> apply --attach ./plan.md "Implement the approved slice."
 
 # 御史台——固定目标双轴察举；completed ≠ 准行，findings 在 Terminal 里
-ak-role reviewer --base main "Review the branch."
+ak-role reviewer --model <provider/model[:thinking]> --base main "Review the branch."
 
 # 通进司——GitHub PR 收证（认票、读手册/现场活动、按需触发、等待窗、交回材料）
-ak-role collector --pr 42 --repo owner/repository "为所指 issue 收证。"
-ak-role collector --repo owner/repository "为 #42 收证。"
+ak-role collector --model <provider/model[:thinking]> --pr 42 --repo owner/repository "为所指 issue 收证。"
+ak-role collector --model <provider/model[:thinking]> --repo owner/repository "为 #42 收证。"
 # 可选：工作步骤开启后的等待窗毫秒（默认 600000＝十分钟）
-ak-role collector --pr 42 --repo owner/repository --wait-ms 120000 "两分钟窗收证。"
+ak-role collector --model <provider/model[:thinking]> --pr 42 --repo owner/repository --wait-ms 120000 "两分钟窗收证。"
 
 # 修内司——缮修所指 findings
-ak-role fixer --attach ./findings.md --prerequisites ./prereqs.json "Repair the findings."
+ak-role fixer --model <provider/model[:thinking]> --attach ./findings.md --prerequisites ./prereqs.json "Repair the findings."
 
 # 太医署——单案诊断
-ak-role doctor --issue 115 "Diagnose this retained case."
+ak-role doctor --model <provider/model[:thinking]> --issue 115 "Diagnose this retained case."
 
 # 校书郎——调和工作树中的 merge 材料（无进行中合并时由角色 escalate）
-ak-role merger --project /path/to/worktree "Reconcile the merge."
+ak-role merger --model <provider/model[:thinking]> --project /path/to/worktree "Reconcile the merge."
 
 # 符宝郎——文书核验一份留存 source run；票号从 source-run admitted form 继承
-ak-role notary --source-run <runId@role|path>
+ak-role notary --model <provider/model[:thinking]> --source-run <runId@role|path>
 
 # 台院——直调复杂度与测试质量两轴
-ak-role inspector --attach ./change.patch "Review this material."
+ak-role inspector --model <provider/model[:thinking]> --attach ./change.patch "Review this material."
 
 # 门下省——直调省审：派官或放行
-ak-role gatekeeper --attach ./submission.json "审：这批材料该谁审？"
+ak-role gatekeeper --model <provider/model[:thinking]> --attach ./submission.json "审：这批材料该谁审？"
 
 # 游奕使——直调路线建议（有序的下一步角色候选）；随公开入口顶层腿自动出席
-ak-role navigator "刚完成 coder apply 收敛，下一步？"
+ak-role navigator --model <provider/model[:thinking]> "刚完成 coder apply 收敛，下一步？"
 
 # 给事中——票庭五问；票号经由 instruction 识别；受理内先自动起居郎再本席（#742，调用者无感）
-ak-role countersign --attach ./ticket.md "裁：本票 #582 是否足以开工。"
+ak-role countersign --model <provider/model[:thinking]> --attach ./ticket.md "裁：本票 #582 是否足以开工。"
 
 # 左拾遗——合并前无锚定风闻；可 resume 续同一 session；--base 必填；instruction 可空；调用者不得传方向性 instruction
-ak-role gleaner-left --base main
+ak-role gleaner-left --model <provider/model[:thinking]> --base main
 
-# 太史——确定性指标；裸调＝整簿
+# 太史——确定性指标；裸调＝整簿（无 model 席）
 ak-role analyst
 
 # escalate 后：把 owner 裁定喂回同一 session（标准链）
-ak-role resume <runId> "<裁定>"
+ak-role --model <provider/model[:thinking]> resume <runId> "<裁定>"
 ```
 
 ## 班子（唐宋官署命名）