@akagilnc/pi-workflow-roles 0.1.1751

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,104 @@
+# @akagilnc/pi-workflow-roles
+
+Packaged workflow roles for [Pi](https://pi.dev): `judge`, `fixer`, `coder`, `reviewer`, `collector`, `doctor`, `merger`. 中文说明见 [README.zh-CN.md](README.zh-CN.md)。
+
+## Install
+
+Install through Pi so the CLI and runtime come from the same package copy, and add Pi’s private npm bin to `PATH` once:
+
+```bash
+pi install npm:@akagilnc/pi-workflow-roles
+export PATH="$HOME/.pi/agent/npm/node_modules/.bin:$PATH"
+```
+
+Update with `pi update npm:@akagilnc/pi-workflow-roles`—never a second global `npm install -g`. Inspect with `ak-role roles` and `ak-role help <role>`; set per-seat defaults with `ak-role config set judge openai-codex/gpt-5.6-sol:high`.
+
+## Reading results
+
+`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
+```
+
+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.
+
+A run interrupted by a typed Codex/xAI HTTP 429 with no lawful result prints a complete `ak-role resume <runId>` command in its failure Terminal. Resume reopens the exact session; override the model for one run with the global flags. The package never auto-switches providers, only a typed 429 makes a run resumable, and unknown, terminal, or concurrently-resumed run IDs are rejected. Collector and Doctor are one-shot.
+
+Global overrides work before or after the role: `ak-role --model xai/grok-4.5:high resume <runId>`.
+
+Every run also prepares Navigator advice in the same Terminal. Configure it like any other seat:
+
+```bash
+ak-role config set navigator openai-codex/gpt-5.6-luna:medium
+```
+
+Receipts are typed, so callers compose roles without parsing prose; ordering and stopping stay caller-owned. Programmatic consumers derive contracts from the exported schemas in `src/package-contracts/`, not from this guide.
+
+## Call the roles
+
+Most roles accept `--attach <file>` (repeatable, frozen at admission), but Reviewer does not. Reviewer requires `--base <revision>` to select the fixed point, and its review materials are acquired through the package-owned bundle mechanism rather than caller attachments. All roles accept `--project <path>`. An instruction is optional for judge, collector, and doctor, and required nonblank for coder, fixer, reviewer, and merger.
+
+```bash
+# judge — adjudicate the supplied materials; infers its burden, no burden flag
+ak-role judge --attach ./findings.md --attach ./adr.md "Adjudicate every finding."
+
+# coder — first implementation; phase defaults to apply, or pass plan
+ak-role coder plan "Propose the first implementation plan."
+ak-role coder apply --attach ./plan.md "Implement the approved slice."
+# apply binds the package-owned TDD method; do not bind a home Skill as a substitute
+
+# reviewer — fixed-target two-axis review (Standards + Spec)
+ak-role reviewer --base main "Review the branch against the governing issue and repository authority."
+# --base is required and pins the fixed point; Reviewer does not accept --attach
+# completed ≠ approved — read the findings in the Terminal
+
+# collector — GitHub PR review evidence; github.com only, needs gh auth; one-shot
+ak-role collector --pr 42 --repo owner/repository
+# repo defaults from origin; --repo owner/repo overrides
+
+# fixer — repair the assigned findings; phase defaults to apply, or pass plan
+ak-role fixer --attach ./findings.md --prerequisites ./prereqs.json "Repair the findings."
+# --prerequisites is a JSON array of {id, requirement}; malformed grammar exits 2
+# apply/resume mount the package-owned diagnosis and TDD methods from the install; neither is forced into the prompt
+
+# doctor — diagnose one retained case; one-shot
+ak-role doctor --issue 115 "Diagnose this retained case."
+# --runs must stay project-relative: .ak-roles/books/<book>/issues/<n>/runs matching --issue
+
+# merger — resolve one merge already in conflict (start it first with Git’s ort)
+ak-role merger --project /path/to/worktree "Reconcile the active merge."
+# hands new intent/authority questions back instead of inventing authority
+```
+
+## Names
+
+Roles are named after Tang/Song offices; the full roster and naming rule live in [README.zh-CN.md](README.zh-CN.md).
+
+## Developer seam: raw session invocation (advanced)
+
+Most callers never need this. The source tree retains an explicitly loadable raw-Pi seam for package development and low-level diagnosis; it is not a supported invocation recipe—external callers use `ak-role`.
+
+A raw run loads the role runtime explicitly and selects the role through the internal flag. This is the real argv shape, taken from the CLI’s own builders and recorded runs under the ledger book:
+
+```bash
+run=~/.ak-roles/books/<book>/issues/<issue>/runs/<invocation>@<source-tree>
+pi --no-extensions \
+  -e <packageRoot>/extensions/role-runtime.ts \
+  --no-skills --no-prompt-templates --no-themes --no-context-files \
+  --session "$run/session/session.jsonl" \
+  --session-dir "$run/session" \
+  --ak-role judge --mode json \
+  "Adjudicate the attached materials." \
+  </dev/null >/dev/null 2>"$run/stderr.log"
+```
+
+`--session` names the exact session file principal (never directory-latest); `--session-dir` is its directory. Judge takes the instruction as the prompt; other roles pass durable payload files through their own internal flags (`--ak-coder-task`, `--ak-fix-packet`, and siblings), assembled by each role’s builder in `src/public-cli/*-run.ts` through the load boundary in `src/public-cli/explicit-internal.ts`. Derive flags from that source—and from recorded runs under the ledger book—never from prose.
+
+Discipline:
+
+- seal stdin with `</dev/null`—Pi reads a non-TTY stdin to EOF before starting, so an open background pipe parks the run forever;
+- send stdout to `/dev/null`—the session file is the authoritative record and stdout is an unbounded copy surface; attach dashboards to `stderr.log` and the session file;
+- keep `stderr.log` and `invocation.json` in the same `runs/` directory, as in the example above.
+
+Codex fast tier: 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.

package/README.zh-CN.md

@@ -0,0 +1,133 @@
+# @akagilnc/pi-workflow-roles
+
+为 [Pi](https://pi.dev) 打包的工作流角色：大理寺（judge）、修内司（fixer）、将作监（coder）、御史台（reviewer）、门下省（collector）、太医署（doctor）、校书郎（merger）。English: [README.md](README.md)。
+
+## 安装
+
+经 Pi 安装，令 CLI 与运行时同出一份包副本；把 Pi 私有 npm bin 加进 `PATH`（一次）：
+
+```bash
+pi install npm:@akagilnc/pi-workflow-roles
+export PATH="$HOME/.pi/agent/npm/node_modules/.bin:$PATH"
+```
+
+更新用 `pi update npm:@akagilnc/pi-workflow-roles`——勿另起全局 `npm install -g`。查看能力：`ak-role roles`、`ak-role help <role>`；设席位默认：`ak-role config set judge openai-codex/gpt-5.6-sol:high`。
+
+## 读结果
+
+`ak-role` 是唯一受支持的调用方式。每次运行的完整 Terminal 结果写在 stdout——从那里读或正常重定向，不要刮 Pi session 文件：
+
+```bash
+ak-role judge --attach ./plan.md "Review this plan." > result.txt
+```
+
+退出码报的是生命周期诚实，不是业务成败：一切合法 typed 终态（含 `audit_escalation`）退出零；无合法终态的失败退出非零，其 Terminal 携带 Error Artifact 引用与原始原因，不伪造回执。
+
+被 Codex/xAI typed HTTP 429 打断且无合法终态的运行，其失败 Terminal 内含完整 `ak-role resume <runId>` 命令。resume 重开同一 session；临时换模型用全局旗标。包绝不自动换 provider；只有 typed 429 可恢复；未知、已终结、并发重复的 run ID 一律拒绝。门下省、太医署为一次性，无 resume。
+
+全局覆盖前后皆可：`ak-role --model xai/grok-4.5:high resume <runId>`。
+
+每次运行游奕使自动出席，建议随同一 Terminal 给出。配置：
+
+```bash
+ak-role config set navigator openai-codex/gpt-5.6-luna:medium
+```
+
+回执是 typed 的，调用者不必解析散文即可组合角色；顺序与停止归调用者。编程消费者从 `src/package-contracts/` 导出推导契约，不从本文。
+
+## 调用百官
+
+多数角色支持 `--attach <文件>`（可重复，受理即冻结），但御史台不接受该旗标。御史台必须用 `--base <revision>` 选定 fixed point，审查材料由包内 bundle 机制取得，而非由调用者附加。所有角色都支持 `--project <路径>`。指令对大理寺、门下省、太医署可省略，对将作监、修内司、御史台、校书郎必须非空。
+
+```bash
+# 大理寺——审断所供材料；自行推断举证责任，无 burden 旗标
+ak-role judge --attach ./findings.md --attach ./adr.md "Adjudicate every finding."
+
+# 将作监——营造新作；phase 默认 apply，或显式 plan
+ak-role coder plan "Propose the first implementation plan."
+ak-role coder apply --attach ./plan.md "Implement the approved slice."
+# apply 强制包内 TDD 方法；勿绑 home Skill 顶替
+
+# 御史台——固定目标双轴察举（Standards + Spec）
+ak-role reviewer --base main "Review the branch."
+# --base 为必填并钉住 fixed point；御史台不接受 --attach
+# completed ≠ 准行——findings 在 Terminal 里
+
+# 门下省——GitHub PR 收证；仅 github.com，需 gh 已认证；一次性
+ak-role collector --pr 42 --repo owner/repository
+ak-role collector --pr 42 --request-manifest ./requests.json
+# 无配置时仅观察；可选 request manifest 为 {requests:[{id,body}]}；repo 默认取 origin
+
+# 修内司——缮修所指 findings；phase 默认 apply，或显式 plan
+ak-role fixer --attach ./findings.md --prerequisites ./prereqs.json "Repair the findings."
+# --prerequisites 为 {id, requirement} JSON 数组；语法畸形退出 2
+
+# 太医署——单案诊断；一次性
+ak-role doctor --issue 115 "Diagnose this retained case."
+# --runs 须为项目相对的 .ak-roles/books/<book>/issues/<n>/runs 且匹配 --issue
+
+# 校书郎——雠校一个已在冲突的 merge（先用 Git ort 起动）
+ak-role merger --project /path/to/worktree "Reconcile the active merge."
+# 遇新意图/权限问题交回调用者，不捏造 authority
+```
+
+## 班子（唐宋官署命名）
+
+角色按唐宋官署／官职命名，判据与被否方案见 [ADR 0051](docs/adr/0051-roles-are-named-after-tang-song-offices.md)。**朝廷对应：皇帝＝陛下，宰相＝调用者，百官＝各角色。** 工厂没有政事堂——中枢是陛下。百官各司其职，彼此制衡，共同完成从谋划、建设、审查到收敛的完整流程。
+
+**只是名字。** `ak-role <name>` 的角色标识符以及工具名与 schema 字段一律使用下表席位列的英文名；中文名只是呈现层称谓。
+
+| 名号 | 席位 | 职掌 |
+| --- | --- | --- |
+| **将作监** | coder | **营造新作。** 承接新的谋划与需求，从一片空白开始设计、建造，直到形成可供使用的新成果。讲究先明其意，再定其形，不妄增枝节，只做当下所需之事。 |
+| **修内司** | fixer | **缮修旧物。** 面对已有问题，不急于表面修补，而是追寻问题根源，找到真正需要修整之处。既要修复眼前缺漏，也要防止同类问题再次出现。 |
+| **御史台** | reviewer | **察举百弊。** 置身事外，以旁观之眼审视成果，寻找其中的不妥、遗漏与隐患。只负责指出问题、陈明依据，不参与修改，也不替人作最终判断。 |
+| **大理寺** | judge | **审理定谳。** 承接各方意见与材料，依照既定规则逐项判断，辨明是非曲直。可以准行、退回或请示更高决定，但自身不参与建设与修改。 |
+| **审刑院** | judge-auditor／reviewer-auditor（无 CLI，共享内部接缝） | **复核成案。** 不重新争论事情本身，而是检查整个办理过程是否合乎规矩。关注是否有人越过职责、是否遗漏必要步骤、是否以错误方式得出正确结果。 |
+| **门下省** | collector | **承接百议。** 位于决策之前，收集各方反馈与意见，确认事情是否已经具备继续推进的条件。它不替人裁决，只负责让信息完整、状态清楚。 |
+| **校书郎** | merger | **雠校异文。** 面对不同来源的修改，负责整理、校合与调和。保留双方有价值的部分，解决彼此冲突；遇到无法自行决定之处，则留待重新裁量。 |
+| **游奕使** | navigator（无 CLI，自动出席） | **巡行问路。** 不掌具体事务，而是观察全局变化，结合当前局面提醒下一步方向。它提供建议与路径参考，但最终选择仍由执掌之人决定。 |
+
+其余席位：
+
+| 席位 | 名 | 职掌 | 状态 |
+| --- | --- | --- | --- |
+| doctor | **太医署** | 单案诊断工厂机制，开 `keep｜thin｜delete` 方 | 已建 |
+| — | **司天台** | 记候簿——只打点、只指针，不分析不执法 | **一期不是角色**（[ADR 0047](docs/adr/0047-sitian-phase-one-mechanism-not-role.md)：零 LLM 双面对账）；席位形态属 [#67](https://github.com/Akagilnc/ak-pi-workflow-roles/issues/67) 素材，未定 |
+| — | **兰台** | 读档议制——耗时／缺口／冗余三条，上奏不执法 | 未建（[#67](https://github.com/Akagilnc/ak-pi-workflow-roles/issues/67) 两席之一） |
+| — | **考功司** | 考具体效率——角色与档位的升档率、一次通过率、每票成本 | 留档，不属 #67，需要时另立票 |
+| — | **主簿** | 合并后勾稽销案：核实确已合上、清理残留、报到达 | 未建 |
+
+**merge 按钮归调用者**，没有任何角色握不可逆权限：门下省把收证这件苦活做完并报收集终态，人（或 AI）自己判断、自己点，点完想调主簿就调、不调也可以。
+
+上表**不规定调用顺序**——组合、顺序、重复次数归调用者（[ADR 0010](docs/adr/0010-callers-own-role-composition-and-repetition.md)）。御史台／大理寺／审刑院是**职责分立的类比，不是必经链**；审刑院也并非只跟在大理寺之后，大理寺、御史台、太医署各自都有一次。
+
+`拾遗补阙` 成对留档，待将来出现第二个进言席再启用。
+
+## 开发者接缝：手拼 session（高级）
+
+多数调用者不需要本节。源码树保留一条可显式装载的 raw-Pi 接缝，供包开发与底层诊断；它不是受支持的调用配方——外部调用者用 `ak-role`。
+
+原始运行显式装载角色运行时，经内部旗标选角色。以下 argv 全形取自 CLI 自身 builder 与卷宗实记：
+
+```bash
+run=~/.ak-roles/books/<book>/issues/<issue>/runs/<invocation>@<源树>
+pi --no-extensions \
+  -e <packageRoot>/extensions/role-runtime.ts \
+  --no-skills --no-prompt-templates --no-themes --no-context-files \
+  --session "$run/session/session.jsonl" \
+  --session-dir "$run/session" \
+  --ak-role judge --mode json \
+  "Adjudicate the attached materials." \
+  </dev/null >/dev/null 2>"$run/stderr.log"
+```
+
+`--session` 指精确 session 文件正本（非 directory-latest）；`--session-dir` 为其目录。大理寺的指令走 prompt；其余角色经各自内部旗标传持久 payload 文件（`--ak-coder-task`、`--ak-fix-packet` 等），由各角色 builder（`src/public-cli/*-run.ts`）经装载边界 `src/public-cli/explicit-internal.ts` 装配。旗标从源码与卷宗实记推导，勿从散文推导。
+
+纪律：
+
+- stdin 须以 `</dev/null` 封死——Pi 会将非 TTY stdin 读到 EOF 才开工，未封死的后台管道＝永久停车；
+- stdout 丢 `/dev/null`——session 文件才是正本，stdout 是无上限副本面；仪表挂 `stderr.log` 与 session 文件；
+- `stderr.log` 与 `invocation.json` 落在同次 `runs/` 目录，如上例。
+
+Codex fast 档：开启：`echo "fast_mode = on" > ~/.pi-codex-fast`；关闭：`echo "fast_mode = off" > ~/.pi-codex-fast`（或删文件）。修改后无需重启，下一个请求即生效。Fast 档价格高于默认档。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,60 @@
+# Third-Party Notices
+
+This project (`@akagilnc/pi-workflow-roles`) is licensed under **Apache-2.0**.
+The notices below are **third-party** licenses and are **not** the project
+license authority. Do not treat them as dual-licensing the package.
+
+## mattpocock/skills (MIT)
+
+Upstream provenance: [mattpocock/skills](https://github.com/mattpocock/skills).
+
+This package ships or will ship pinned snapshots of the following skills from
+that upstream repository. Each shipped method records immutable upstream
+commit/tag identity, per-file digests and git blob OIDs, and attribution under
+`resources/methods/<name>/provenance.json`.
+
+- `tdd` — shipped unchanged under `resources/methods/tdd/` from upstream
+  `skills/engineering/tdd` at commit `8b36d4fb2635b3c21998dcd8144439c9e5ba7302`
+  (tag `v1.2.2`) (#109)
+- `diagnosing-bugs` — shipped under `resources/methods/diagnosing-bugs/` from
+  upstream `skills/engineering/diagnosing-bugs` at the same commit/tag, with
+  package adaptation `fixer-boundary-no-external-skill-chain` so the Fixer
+  method cannot automatically launch architecture Grill or other role-external
+  Skill chains (#110)
+- `code-review` — shipped under `resources/methods/code-review/` from
+  upstream `skills/engineering/code-review` at the same commit/tag, with
+  package adaptation `reviewer-no-setup-fixed-target-two-axis` so Reviewer
+  remains usable without Matt setup files, does not modify project governance
+  as setup, preserves Standards/Spec axes, and never turns scratch probes into
+  product repairs (#111)
+- `resolving-merge-conflicts` — shipped under `resources/methods/resolving-merge-conflicts/` from
+  upstream `skills/engineering/resolving-merge-conflicts` at the same commit/tag, with
+  package adaptation `merger-merge-only-escalate-new-intent` so Merger stays merge-only,
+  escalates new intent/authority instead of guessing, and does not inherit upstream
+  unconditional-resolution or rebase workflow (#114)
+
+The complete upstream MIT license text follows.
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/dist/activation-ledger-git.js

@@ -0,0 +1,68 @@
+import { execFileSync } from "node:child_process";
+import { basename, dirname, isAbsolute, resolve } from "node:path";
+const GIT_DISCOVERY_ENV_KEYS = [
+  "GIT_DIR",
+  "GIT_COMMON_DIR",
+  "GIT_WORK_TREE",
+  "GIT_CEILING_DIRECTORIES",
+  "GIT_DISCOVERY_ACROSS_FILESYSTEM"
+];
+function envWithoutGitDiscovery(base = process.env) {
+  const env = { ...base };
+  for (const key of GIT_DISCOVERY_ENV_KEYS) {
+    delete env[key];
+  }
+  return env;
+}
+class ActivationGitRepositoryRequiredError extends Error {
+  code = "AK_ACTIVATION_GIT_REPOSITORY_REQUIRED";
+  constructor(detail, options) {
+    super(
+      `Workflow role activation requires a git repository cwd (git rev-parse --git-common-dir failed): ${detail || "unknown git error"}`,
+      options?.cause === void 0 ? void 0 : { cause: options.cause }
+    );
+    this.name = "ActivationGitRepositoryRequiredError";
+  }
+}
+function isGitSpawnInfrastructureError(error) {
+  if (error === null || typeof error !== "object" || !("code" in error)) return false;
+  const code = error.code;
+  return code === "ENOENT" || code === "EACCES" || code === "EPERM";
+}
+function gitChildExitedNonzero(error) {
+  if (error === null || typeof error !== "object" || !("status" in error)) return false;
+  const status = error.status;
+  return typeof status === "number" && status !== 0;
+}
+function resolveBookKeyFromGit(cwd) {
+  let commonDir;
+  try {
+    commonDir = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      env: envWithoutGitDiscovery()
+    }).trim();
+  } catch (error) {
+    if (isGitSpawnInfrastructureError(error) || !gitChildExitedNonzero(error)) {
+      throw error;
+    }
+    const err = error;
+    const detail = typeof err.stderr === "string" ? err.stderr.trim() : Buffer.isBuffer(err.stderr) ? err.stderr.toString("utf8").trim() : typeof err.message === "string" ? err.message : "";
+    throw new ActivationGitRepositoryRequiredError(detail || "unknown git error", { cause: error });
+  }
+  if (commonDir.length === 0) {
+    throw new Error("git rev-parse --git-common-dir returned an empty path");
+  }
+  const absoluteCommon = isAbsolute(commonDir) ? commonDir : resolve(cwd, commonDir);
+  const hostDirectory = basename(absoluteCommon) === ".git" ? dirname(absoluteCommon) : absoluteCommon;
+  const bookKey = basename(hostDirectory);
+  if (bookKey.length === 0 || bookKey === "." || bookKey === "/") {
+    throw new Error(`Unable to derive activation book key from git common dir: ${absoluteCommon}`);
+  }
+  return bookKey;
+}
+export {
+  ActivationGitRepositoryRequiredError,
+  resolveBookKeyFromGit
+};