@akagilnc/pi-workflow-roles 0.1.3262 → 0.1.3287

package/README.md

@@ -47,12 +47,12 @@ Seat and Gate-officer configuration:
 ```bash
 ak-role config set judge <provider/model[:thinking]>
 ak-role config set navigator <provider/model[:thinking]>
-# Gate officers (automatic on submission; inspector and notary also have direct commands)
+# Gate officers (automatic on submission; direct commands available)
 ak-role config set gatekeeper <provider/model[:thinking]>
 ak-role config set inspector <provider/model[:thinking]>
 ak-role config set notary <provider/model[:thinking]>
 ak-role config unset gatekeeper
-# persistent labor engine (callable roles; not navigator); one-shot override remains --engine
+# persistent labor engine (callable roles); one-shot override remains --engine
 ak-role config set-engine judge opus
 ak-role config unset-engine judge
 # persistent main-session host (callable roles); one-shot override remains --host
@@ -109,6 +109,12 @@ ak-role notary --source-run <runId@role|path> --ticket 582
 # inspector — direct complexity and test-quality check; one-shot
 ak-role inspector --attach ./change.patch "Review this material."
 
+# gatekeeper — direct Gate province review; dispatch an officer or pass
+ak-role gatekeeper --attach ./submission.json "审：这批材料该谁审？"
+
+# navigator — direct route advice (ordered next-role candidates); automatic attendance unchanged
+ak-role navigator "刚完成 coder apply 收敛，下一步？"
+
 # countersign — ticket-court five questions; optional --ticket (diarist pipeline refreshes court diary first)
 ak-role countersign --ticket 582 --attach ./ticket.md "裁：本票是否足以开工。"
 
@@ -127,126 +133,6 @@ Roles are named after Tang/Song offices; the full roster and naming rule live in
 
 Enable fast tier with `echo "fast_mode = on" > ~/.pi-codex-fast`; disable it with `echo "fast_mode = off" > ~/.pi-codex-fast` (or delete the file). The change takes effect on the next request without a restart. Fast tier costs more than the default tier.
 
-<!-- BEGIN GENERATED: public-cli-options -->
-## Public CLI options (generated)
-
-Generated from `src/public-cli/option-definitions.ts`. Prefer `ak-role help <command>`. Do not hand-edit this section.
-
-### `global`
-
-| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `--model` | — | `provider/model` | no | no | option | — | Override the effective seat model for this invocation (before or after the command). |
-| `--thinking` | — | `level` | no | no | option | — | Override thinking level: off\|minimal\|low\|medium\|high\|xhigh\|max. |
-| `--engine` | — | `name` | no | no | option | — | Labor engine for this invocation (owner pool-directive name; packaged notes attached when present; any role). |
-| `--host` | — | `name` | no | no | option | — | Select the named main-session host adapter for this invocation. |
-| `--help` | `-h` | — | no | no | option | — | Show public CLI help and exit. |
-
-### `judge`
-
-| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `--project` | — | `path` | no | no | option | — | Project root for ledger identity (defaults to process cwd). |
-| `--attach` | — | `path` | no | yes | option | — | Attach a regular file; frozen at admission (repeatable). |
-
-### `coder`
-
-| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `plan\|apply` | `plan`, `apply` | — | no | no | positional | phases=plan\|apply; default=apply | Optional phase token before the instruction; defaults to apply. |
-| `--project` | — | `path` | no | no | option | — | Project root for ledger identity (defaults to process cwd). |
-| `--attach` | — | `path` | no | yes | option | — | Attach a regular file; frozen at admission (repeatable). |
-
-### `fixer`
-
-| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `plan\|apply` | `plan`, `apply` | — | no | no | positional | phases=plan\|apply; default=apply | Optional phase token before the instruction; defaults to apply. |
-| `--project` | — | `path` | no | no | option | — | Project root for ledger identity (defaults to process cwd). |
-| `--attach` | — | `path` | no | yes | option | — | Attach a regular file; frozen at admission (repeatable). |
-| `--prerequisites` | — | `path` | no | no | option | — | JSON array of {id, requirement} prerequisite objects. |
-
-### `reviewer`
-
-| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `--project` | — | `path` | no | no | option | — | Project root for ledger identity (defaults to process cwd). |
-| `--base` | — | `revision` | yes | no | option | — | Required fixed-point revision for the pinned review target. |
-| `--authority-ref` | — | `ref` | no | yes | option | — | Durable authority reference/URL (repeatable; refs only, not inline prose). |
-
-### `collector`
-
-| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `--project` | — | `path` | no | no | option | — | Project root for ledger identity (defaults to process cwd). |
-| `--attach` | — | `path` | no | yes | option | — | Attach a regular file; frozen at admission (repeatable). |
-| `--pr` | — | `number` | yes | no | option | — | Required positive GitHub pull request number. |
-| `--repo` | — | `owner/repo` | no | no | option | — | GitHub owner/repo override (defaults from origin when github.com). |
-| `--request-manifest` | — | `path` | no | no | option | — | Optional request manifest JSON path ({requests:[{id,body}]}). |
-
-### `doctor`
-
-| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `--project` | — | `path` | no | no | option | — | Project root for ledger identity (defaults to process cwd). |
-| `--attach` | — | `path` | no | yes | option | — | Attach a regular file; frozen at admission (repeatable). |
-| `--issue` | — | `number` | yes | no | option | — | Required positive issue number for the retained case. |
-| `--runs` | — | `path` | no | no | option | — | Optional project-relative .ak-roles/books/<book>/issues/<n>/runs override matching --issue. |
-
-### `merger`
-
-| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `--project` | — | `path` | no | no | option | — | Project root with one ordinary in-progress merge (defaults to cwd). |
-| `--attach` | — | `path` | no | yes | option | — | Attach a regular file; frozen at admission (repeatable). |
-
-### `inspector`
-
-| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `--project` | — | `path` | no | no | option | — | Project root for ledger identity (defaults to process cwd). |
-| `--attach` | — | `path` | no | yes | option | — | Attach a regular file; frozen at admission (repeatable). |
-
-### `notary`
-
-| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `--project` | — | `path` | no | no | option | — | Project root for ledger identity (defaults to process cwd). |
-| `--source-run` | — | `runId@role\|path` | yes | no | option | — | Required source run locator (runId@role under the book home, or path to that run directory). Zero prompt/attachment projection. |
-| `--ticket` | — | `number` | no | no | option | — | Optional ticket/issue number when Notary reads the court diary (ticket-provenance) for a ticket. |
-
-
-### `countersign`
-
-| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `--project` | — | `path` | no | no | option | — | Project root for ledger identity (defaults to process cwd). |
-| `--attach` | — | `path` | no | yes | option | — | Attach a regular file; frozen at admission (repeatable). |
-| `--ticket` | — | `number` | no | no | option | — | Ticket/issue number for court diary (diarist) and ticket-keyed provenance. Overrides attachment frontmatter when both present. |
-
-### `gleaner-left`
-
-Optional free positional `instruction` may be empty. Callers must not pass directional instruction; the seat self-fetches the merge-candidate diff against `--base`.
-
-| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `--project` | — | `path` | no | no | option | — | Project root for ledger identity (defaults to process cwd). |
-| `--base` | — | `revision` | yes | no | option | — | Required comparison-base revision for the unanchored merge-candidate diff. |
-
-### `analyst`
-
-| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `sweep` | — | — | no | no | positional | modes=sweep | Optional sweep mode token (at most once; no other positionals). |
-| `--ticket` | — | `number` | no | no | option | modes=issue | Ticket/issue number; live filter by invocation.ticketNumber inside the cwd book (git common-dir). Bare call = whole book. No library-index bootstrap. |
-| `--attach` | — | `path` | when:sweep | yes | option | modes=sweep; max=sweep:1 | Sweep-mode attachment path; required exactly once in sweep; payload is the attachment body. |
-| `--cohort` | — | — | no | no | option | modes=cohort | Select cohort mode. |
-| `--group-a-label` | — | `label` | when:cohort | no | option | modes=cohort | Cohort group A label (required in cohort mode). |
-| `--group-a-issues` | — | `N\|book:N[,...]` | when:cohort | no | option | modes=cohort | Cohort group A issues: bare N joins cwd book; book:N selects another book; escape a literal comma/backslash in a book key as \, / \\ (required in cohort mode). |
-| `--group-b-label` | — | `label` | when:cohort | no | option | modes=cohort | Cohort group B label (required in cohort mode). |
-| `--group-b-issues` | — | `N\|book:N[,...]` | when:cohort | no | option | modes=cohort | Cohort group B issues: bare N joins cwd book; book:N selects another book; escape a literal comma/backslash in a book key as \, / \\ (required in cohort mode). |
-<!-- END GENERATED: public-cli-options -->
-
 ## Normative pointers
 
 - Command usage and refusal text: `ak-role help <command>`, `ak-role help config` (sole authority).

package/README.zh-CN.md

@@ -52,7 +52,7 @@ ak-role config set gatekeeper <provider/model[:thinking]>
 ak-role config set inspector <provider/model[:thinking]>
 ak-role config set notary <provider/model[:thinking]>
 ak-role config unset gatekeeper
-# 持久劳务引擎（可调用角色；不含 navigator）；一次性覆盖仍用 --engine
+# 持久劳务引擎（可调用角色）；一次性覆盖仍用 --engine
 ak-role config set-engine judge opus
 ak-role config unset-engine judge
 # 持久主会话宿主（可调用角色）；一次性覆盖仍用 --host
@@ -103,6 +103,12 @@ ak-role notary --source-run <runId@role|path> --ticket 582
 # 察院——直调复杂度与测试质量两轴；一次性
 ak-role inspector --attach ./change.patch "Review this material."
 
+# 门下省——直调省审：派官或放行
+ak-role gatekeeper --attach ./submission.json "审：这批材料该谁审？"
+
+# 游奕使——直调路线建议（有序的下一步角色候选）；自动出席不变
+ak-role navigator "刚完成 coder apply 收敛，下一步？"
+
 # 给事中——票庭五问；可选 --ticket（起居郎流水线前序工序按票刷新起居录）
 ak-role countersign --ticket 582 --attach ./ticket.md "裁：本票是否足以开工。"
 
@@ -129,14 +135,14 @@ ak-role resume <runId> "<裁定>"
 | **御史台** | reviewer | **察举百弊，风闻奏事。** 置身事外审视成果；Standards／Spec 两条取证腿由 runtime 代跑，本席收腿报告出薄回执与 amendment。弹章须指明所劾之处，言不为狱——不负坐实义务，坐实归大理寺。 |
 | **大理寺** | judge | **审理定谳。** 承接各方意见与材料，依照既定规则逐项判断，辨明是非曲直。可以准行、退回或请示更高决定，但自身不参与建设与修改。 |
 | **审刑院** | judge-auditor／doctor-auditor（无 CLI，共享内部接缝；御史台侧闸已退役） | **复核成案。** 不重新争论事情本身，而是检查整个办理过程是否合乎规矩。关注是否有人越过职责、是否遗漏必要步骤、是否以错误方式得出正确结果。直属陛下，不入门下省编制。 |
-| **门下省** | gatekeeper（无独立 CLI；交卷自动出席） | **审署诏敕与质量保证的省。** 交卷时判断受审物、够不够审、该谁审，派察院或符宝郎；给事中票庭由调用者开工前传召；左拾遗由调用者合并前传召（皆非闸派）；省内政，不是外层编排器。规范见 [ADR 0067](docs/adr/0067-menxia-province-founding-jishizhong-fubaolang.md)、[ADR 0072](docs/adr/0072-menxia-pre-pr-submission-hooks.md)、[ADR 0074](docs/adr/0074-gate-province-reorg-jishizhong-chaiyuan-split.md)。 |
+| **门下省** | gatekeeper（交卷自动出席，亦可 `ak-role gatekeeper` 直调） | **审署诏敕与质量保证的省。** 交卷时判断受审物、够不够审、该谁审，派察院或符宝郎；给事中票庭由调用者开工前传召；左拾遗由调用者合并前传召（皆非闸派）；省内政，不是外层编排器。规范见 [ADR 0067](docs/adr/0067-menxia-province-founding-jishizhong-fubaolang.md)、[ADR 0072](docs/adr/0072-menxia-pre-pr-submission-hooks.md)、[ADR 0074](docs/adr/0074-gate-province-reorg-jishizhong-chaiyuan-split.md)。 |
 | **给事中** | countersign（无交卷闸派发；开工前由调用者传召） | **票庭审读五问。** 制度符合／授权真实（以起居录为据）／文书符意／退回重议／发布资格；读码取证是本职，实现细节不上票面。票庭流水线在本席 turn 前跑起居郎工序（调用者无感）；交卷闸出席符宝郎。署＝放行开工，封驳＝退票重议，上呈＝陛下裁决。规范见 [ADR 0074](docs/adr/0074-gate-province-reorg-jishizhong-chaiyuan-split.md)、[ADR 0075](docs/adr/0075-ticket-provenance-diarist-pipeline.md)。 |
 | **左拾遗** | gleaner-left（无交卷闸派发；合并前由调用者传召） | **合并前无锚定风闻。** 对全幅合并候选作冷眼评审；只上弹章、不封驳不裁决。规范见 [ADR 0067](docs/adr/0067-menxia-province-founding-jishizhong-fubaolang.md) 修正案。 |
 | **察院** | inspector | **事后察举：复杂度与测试质量两轴。** 受审物是将作监／修内司完成侧交卷；封驳＝当场打回重写，不是本局失败。可被门下省派发，也可 `ak-role inspector` 单独调。原给事中，ADR 0074 分立。 |
 | **符宝郎** | notary | **首责唯一：核实实际授权出处**（防乱编乱扩）。行事两步：读该票起居录→以录核旨；引语真伪与票面对齐为手段。受审物是大理寺拟判与给事中署章；可被门下省派发，也可 `ak-role notary` 单独调。规范见 [ADR 0075](docs/adr/0075-ticket-provenance-diarist-pipeline.md)。 |
 | **通进司** | collector | **承接百议／收证。** 门下省下的收证衙门：收集外部 GitHub PR 材料与意见，只收不审、不替人裁决。canonical 键仍为 `collector`。 |
 | **校书郎** | merger | **雠校异文。** 面对不同来源的修改，负责整理、校合与调和。保留双方有价值的部分，解决彼此冲突；遇到无法自行决定之处，则留待重新裁量。 |
-| **游奕使** | navigator（无 CLI，自动出席） | **巡行问路。** 不掌具体事务，而是观察全局变化，结合当前局面提醒下一步方向。它提供建议与路径参考，但最终选择仍由执掌之人决定。 |
+| **游奕使** | navigator（自动出席，亦可 `ak-role navigator` 直调） | **巡行问路。** 不掌具体事务，而是观察全局变化，结合当前局面提醒下一步方向。它提供建议与路径参考，但最终选择仍由执掌之人决定。 |
 
 其余席位：
 
@@ -161,126 +167,6 @@ ak-role resume <runId> "<裁定>"
 
 开启：`echo "fast_mode = on" > ~/.pi-codex-fast`；关闭：`echo "fast_mode = off" > ~/.pi-codex-fast`（或删文件）。修改后无需重启，下一个请求即生效。Fast 档价格高于默认档。
 
-<!-- BEGIN GENERATED: public-cli-options -->
-## 公开 CLI 选项（生成）
-
-本表由 `src/public-cli/option-definitions.ts` 生成；以 `ak-role help <command>` 为准。勿手改本区。
-
-### `global`
-
-| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `--model` | — | `provider/model` | 否 | 否 | option | — | 覆盖本调用有效席位模型（可置于子命令前或后）。 |
-| `--thinking` | — | `level` | 否 | 否 | option | — | 覆盖 thinking 档位：off\|minimal\|low\|medium\|high\|xhigh\|max。 |
-| `--engine` | — | `name` | 否 | 否 | option | — | 本调用劳动引擎（池令名字；有包内调法笔记则附卷；全部角色可用）。 |
-| `--host` | — | `name` | 否 | 否 | option | — | 为本调用选择具名主会话宿主适配器。 |
-| `--help` | `-h` | — | 否 | 否 | option | — | 显示公开 CLI 帮助并退出。 |
-
-### `judge`
-
-| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `--project` | — | `path` | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 |
-| `--attach` | — | `path` | 否 | 是 | option | — | 附加普通文件；受理即冻结（可重复）。 |
-
-### `coder`
-
-| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `plan\|apply` | `plan`, `apply` | — | 否 | 否 | positional | phases=plan\|apply; default=apply | 指令前可选 phase 词元；默认 apply。 |
-| `--project` | — | `path` | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 |
-| `--attach` | — | `path` | 否 | 是 | option | — | 附加普通文件；受理即冻结（可重复）。 |
-
-### `fixer`
-
-| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `plan\|apply` | `plan`, `apply` | — | 否 | 否 | positional | phases=plan\|apply; default=apply | 指令前可选 phase 词元；默认 apply。 |
-| `--project` | — | `path` | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 |
-| `--attach` | — | `path` | 否 | 是 | option | — | 附加普通文件；受理即冻结（可重复）。 |
-| `--prerequisites` | — | `path` | 否 | 否 | option | — | {id, requirement} 前置条件 JSON 数组路径。 |
-
-### `reviewer`
-
-| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `--project` | — | `path` | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 |
-| `--base` | — | `revision` | 是 | 否 | option | — | 必填；钉住审查目标的 fixed-point revision。 |
-| `--authority-ref` | — | `ref` | 否 | 是 | option | — | 持久 authority 引用/URL（可重复；仅 ref，非内联散文）。 |
-
-### `collector`
-
-| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `--project` | — | `path` | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 |
-| `--attach` | — | `path` | 否 | 是 | option | — | 附加普通文件；受理即冻结（可重复）。 |
-| `--pr` | — | `number` | 是 | 否 | option | — | 必填；正整数 GitHub PR 号。 |
-| `--repo` | — | `owner/repo` | 否 | 否 | option | — | GitHub owner/repo 覆盖（默认取 github.com origin）。 |
-| `--request-manifest` | — | `path` | 否 | 否 | option | — | 可选 request manifest JSON 路径（{requests:[{id,body}]}）。 |
-
-### `doctor`
-
-| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `--project` | — | `path` | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 |
-| `--attach` | — | `path` | 否 | 是 | option | — | 附加普通文件；受理即冻结（可重复）。 |
-| `--issue` | — | `number` | 是 | 否 | option | — | 必填；留存病例的正整数 issue 号。 |
-| `--runs` | — | `path` | 否 | 否 | option | — | 可选项目相对 .ak-roles/books/<book>/issues/<n>/runs 覆盖，且须匹配 --issue。 |
-
-### `merger`
-
-| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `--project` | — | `path` | 否 | 否 | option | — | 已有进行中 ordinary merge 的项目根（默认 cwd）。 |
-| `--attach` | — | `path` | 否 | 是 | option | — | 附加普通文件；受理即冻结（可重复）。 |
-
-### `inspector`
-
-| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `--project` | — | `path` | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 |
-| `--attach` | — | `path` | 否 | 是 | option | — | 附加普通文件；受理即冻结（可重复）。 |
-
-### `notary`
-
-| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `--project` | — | `path` | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 |
-| `--source-run` | — | `runId@role\|path` | 是 | 否 | option | — | 必填源 run 定位符（簿内 runId@role，或该 run 目录路径）。零 prompt/附件投影。 |
-| `--ticket` | — | `number` | 否 | 否 | option | — | 可选票号：符宝郎按票键调取起居录时使用。 |
-
-
-### `countersign`
-
-| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `--project` | — | `path` | 否 | 否 | option | — | 卷宗身份的项目根（默认 process cwd）。 |
-| `--attach` | — | `path` | 否 | 是 | option | — | 附卷普通文件；受理时冻结（可重复）。 |
-| `--ticket` | — | `number` | 否 | 否 | option | — | 票号：起居郎流水线与起居录票键。与附件 frontmatter 并存时以本旗为准。 |
-
-### `gleaner-left`
-
-可选自由 positional `instruction` 可空。调用者不得传方向性 instruction；本席按 `--base` 自取合并候选 diff。
-
-| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `--project` | — | `path` | 否 | 否 | option | — | 卷宗身份的项目根（默认 process cwd）。 |
-| `--base` | — | `revision` | 是 | 否 | option | — | 必填；无锚定合并候选 diff 的比较基线 revision。 |
-
-### `analyst`
-
-| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `sweep` | — | — | 否 | 否 | positional | modes=sweep | 可选 sweep 模式词元（至多一次；不得夹带其他 positional）。 |
-| `--ticket` | — | `number` | 否 | 否 | option | modes=issue | 票号；在 cwd 候簿（git common-dir）内按 invocation.ticketNumber 现取现算。裸调用=整簿。不依赖 library-index 自举。 |
-| `--attach` | — | `path` | 条件:sweep | 是 | option | modes=sweep; max=sweep:1 | sweep 模式附件路径；sweep 必填且恰一次；载荷为附件正文。 |
-| `--cohort` | — | — | 否 | 否 | option | modes=cohort | 选择 cohort 模式。 |
-| `--group-a-label` | — | `label` | 条件:cohort | 否 | option | modes=cohort | cohort A 组标签（cohort 模式必填）。 |
-| `--group-a-issues` | — | `N\|book:N[,...]` | 条件:cohort | 否 | option | modes=cohort | cohort A 组 issue：裸 N 归属 cwd 簿；book:N 显式跨簿；簿键中的逗号/反斜杠用 \, / \\ 转义（cohort 模式必填）。 |
-| `--group-b-label` | — | `label` | 条件:cohort | 否 | option | modes=cohort | cohort B 组标签（cohort 模式必填）。 |
-| `--group-b-issues` | — | `N\|book:N[,...]` | 条件:cohort | 否 | option | modes=cohort | cohort B 组 issue：裸 N 归属 cwd 簿；book:N 显式跨簿；簿键中的逗号/反斜杠用 \, / \\ 转义（cohort 模式必填）。 |
-<!-- END GENERATED: public-cli-options -->
-
 ## 规范指针
 
 - 命令用法与拒绝文案：`ak-role help <command>`、`ak-role help config`（唯一权威）。

package/dist/gatekeeper-role.js

@@ -4,7 +4,7 @@ import { openToolObject } from "./open-tool-schema.js";
 import { loadGatekeeperSessionMaterials } from "./session-opening-materials.js";
 import { GatekeeperDecisionError } from "./submission-errors.js";
 import { INSPECTOR_OUTPUT_TOOL_NAME } from "./inspector-contracts.js";
-export const GATEKEEPER_OUTPUT_TOOL = "ak_gatekeeper_output";
+import { GATEKEEPER_OUTPUT_TOOL_NAME, gatekeeperDecisionSchema, gatekeeperOutputSchema, projectLawfulGatekeeperOutput, } from "./package-contracts/gatekeeper-output.js";
 export const INSPECTOR_OUTPUT_TOOL = INSPECTOR_OUTPUT_TOOL_NAME;
 export const NOTARY_OUTPUT_TOOL = "ak_notary_output";
 const SUBJECT_TOOL = "ak_gatekeeper_subject";
@@ -25,11 +25,18 @@ const officerDecisionSchema = openToolObject(Type.Object({
     status: Type.Unknown({ description: "pass | bounce — 形状指引，非 schema 闸" }),
     findings: Type.Unknown({ description: "string[] findings，随 pass 或 bounce 留存" }),
 }));
-const gatekeeperDecisionSchema = openToolObject(Type.Object({
-    status: Type.Unknown({ description: "dispatch | pass — 形状指引，非 schema 闸" }),
-    officer: Type.Unknown({ description: "status 为 dispatch 时为 inspector | notary" }),
-    findings: Type.Unknown({ description: "status 为 pass 时可选 string[] findings" }),
-}));
+/**
+ * Direct-seat decision tool spec (#639). Lifecycle assembly stays on the
+ * registration envelope — src/role-runtime.ts (ADR 0018). Schema authority is
+ * the shared contract module (with infrastructure-failure declaration).
+ */
+export const GATEKEEPER_TOOL_SPEC = {
+    name: GATEKEEPER_OUTPUT_TOOL_NAME,
+    label: "门下省决议",
+    description: "门下省终局决议，状态为 dispatch 或 pass。",
+    promptSnippet: "门下省决议",
+    parameters: gatekeeperOutputSchema,
+};
 function result(content, details) {
     return { content: [{ type: "text", text: content }], details };
 }
@@ -50,10 +57,10 @@ export function createOfficerDecisionTool(name) {
         async execute(_id, args) { return result(`已收 ${String(args?.status)}`, args); },
     };
 }
-/** Gatekeeper province decision tool — open transport; projection owns legality. */
+/** Gatekeeper province decision tool — open transport; package-contract projection owns legality. */
 export function createGatekeeperOutputTool() {
     return {
-        name: GATEKEEPER_OUTPUT_TOOL,
+        name: GATEKEEPER_OUTPUT_TOOL_NAME,
         description: "提交门下省派官决定。",
         parameters: gatekeeperDecisionSchema,
         async execute(_id, args) { return result(`已收 ${String(args?.status)}`, args); },
@@ -104,18 +111,17 @@ function readRecord(value) {
     return value;
 }
 function projectProvinceDecision(decision) {
-    const record = readRecord(decision);
-    if (record === undefined)
+    // Lawful dispatch/pass discriminant is owned by package-contracts; province
+    // wraps undefined into transport_failure while retaining the submission.
+    const projected = projectLawfulGatekeeperOutput(decision);
+    if (projected === undefined)
         return noUsableReleaseFailure("gatekeeper", decision);
-    if (record.status === "dispatch" && (record.officer === "inspector" || record.officer === "notary")) {
-        return { status: "dispatch", officer: record.officer };
+    if (projected.status === "dispatch") {
+        return { status: "dispatch", officer: projected.officer };
     }
     // Lawful non-dispatch release — province may pass without dispatching an officer
     // (ADR 0074 gate-non-mandatory; gate-output-guide pass = 正常放行; #597).
-    if (record.status === "pass") {
-        return { status: "pass", findings: asStringArray(record.findings) };
-    }
-    return noUsableReleaseFailure("gatekeeper", decision);
+    return { status: "pass", findings: projected.findings ?? [] };
 }
 function projectOfficerDecision(officer, decision) {
     const record = readRecord(decision);