@akagilnc/pi-workflow-roles 0.1.3280 → 0.1.3353

package/README.md

@@ -38,7 +38,7 @@ 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.
 
-`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. 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. Global `--model` / `--host` / `--engine` override the table for that resume only. 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: `runDirectory/grok-home`), 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. Collector, Doctor, Notary, and Inspector remain one-shot. Countersign and Gleaner-Left accept manual resume (#599).
+`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` / `--host` / `--engine` override the table for that resume only. 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: `runDirectory/grok-home`), 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.
 
 Judge, coder, fixer, reviewer, and merger 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.
 
@@ -90,23 +90,23 @@ ak-role coder 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."
 
-# collector — GitHub PR review evidence; one-shot
+# collector — GitHub PR review evidence
 ak-role collector --pr 42 --repo owner/repository
 
 # fixer — repair the assigned findings
 ak-role fixer --attach ./findings.md --prerequisites ./prereqs.json "Repair the findings."
 
-# doctor — diagnose one retained case; one-shot
+# doctor — diagnose one retained case
 ak-role doctor --issue 115 "Diagnose this retained case."
 
 # merger — resolve one merge already in conflict (start it with Git's ort first)
 ak-role merger --project /path/to/worktree "Reconcile the active merge."
 
-# notary — document-fidelity check on one retained source run; one-shot; optional --ticket for court diary
+# notary — document-fidelity check on one retained source run; optional --ticket for court diary
 ak-role notary --source-run <runId@role|path>
 ak-role notary --source-run <runId@role|path> --ticket 582
 
-# inspector — direct complexity and test-quality check; one-shot
+# inspector — direct complexity and test-quality check
 ak-role inspector --attach ./change.patch "Review this material."
 
 # gatekeeper — direct Gate province review; dispatch an officer or pass

package/README.zh-CN.md

@@ -38,7 +38,7 @@ ak-role judge --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，角色继续走到终局。`runId` 后可选的 `message` 原样作为续跑 prompt（opaque：不进全局旗标语法）；省略则用包自带 resume envelope。全局 `--model` / `--host` / `--engine` 仅覆盖本次 resume。真实换宿主时（现行席位 host 与上一次 invocation host 不同），将前序宿主原生卷宗一次性作为 context 交付目标宿主；同宿主续跑不重复注入。各宿主仅直写自身原生卷宗（Pi：`session/session.jsonl`，Grok：`runDirectory/grok-home`），统一账目归入司天台。要不要续跑由调用者决定：不再要求 typed HTTP 429，也不要求 `resumable` 状态。未知 run ID、session 主体不在则拒绝。通进司、太医署、符宝郎、察院仍为一次性，无 resume；给事中、左拾遗可手动 resume（#599）。
+`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` / `--host` / `--engine` 仅覆盖本次 resume。真实换宿主时（现行席位 host 与上一次 invocation host 不同），将前序宿主原生卷宗一次性作为 context 交付目标宿主；同宿主续跑不重复注入。各宿主仅直写自身原生卷宗（Pi：`session/session.jsonl`，Grok：`runDirectory/grok-home`），统一账目归入司天台。要不要续跑由调用者决定：不再要求 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` 仍可用。
 
@@ -84,23 +84,23 @@ ak-role coder apply --attach ./plan.md "Implement the approved slice."
 # 御史台——固定目标双轴察举；completed ≠ 准行，findings 在 Terminal 里
 ak-role reviewer --base main "Review the branch."
 
-# 通进司——GitHub PR 收证；一次性
+# 通进司——GitHub PR 收证
 ak-role collector --pr 42 --repo owner/repository
 
 # 修内司——缮修所指 findings
 ak-role fixer --attach ./findings.md --prerequisites ./prereqs.json "Repair the findings."
 
-# 太医署——单案诊断；一次性
+# 太医署——单案诊断
 ak-role doctor --issue 115 "Diagnose this retained case."
 
 # 校书郎——调和已在冲突的 merge（先用 Git ort 起动）
 ak-role merger --project /path/to/worktree "Reconcile the active merge."
 
-# 符宝郎——文书核验一份留存 source run；一次性；可选 --ticket 调起居录
+# 符宝郎——文书核验一份留存 source run；可选 --ticket 调起居录
 ak-role notary --source-run <runId@role|path>
 ak-role notary --source-run <runId@role|path> --ticket 582
 
-# 察院——直调复杂度与测试质量两轴；一次性
+# 察院——直调复杂度与测试质量两轴
 ak-role inspector --attach ./change.patch "Review this material."
 
 # 门下省——直调省审：派官或放行

package/dist/audit-escalation.js

@@ -22,15 +22,29 @@ export function buildAuditEscalationResult(decision, deliveredOutput) {
     if (Object.hasOwn(decision, "decisionGate")) {
         auditOwned.auditDecisionGate = decision.decisionGate;
     }
+    if (Object.hasOwn(decision, "reason") && decision.reason !== undefined) {
+        auditOwned.reason = decision.reason;
+    }
+    if (Object.hasOwn(decision, "officer") && decision.officer !== undefined) {
+        auditOwned.officer = decision.officer;
+    }
+    if (Object.hasOwn(decision, "findings") && decision.findings !== undefined) {
+        auditOwned.findings = decision.findings;
+    }
     const deliveredFields = deliveredOutput !== undefined &&
         deliveredOutput !== null &&
         typeof deliveredOutput === "object" &&
         !Array.isArray(deliveredOutput)
         ? { ...deliveredOutput }
         : {};
-    // Role output cannot fill an absent audit-owned field.
+    // Role output cannot fill an absent audit/officer-owned field.
     delete deliveredFields.conflicts;
     delete deliveredFields.auditDecisionGate;
+    if (Object.hasOwn(decision, "officer")) {
+        delete deliveredFields.reason;
+        delete deliveredFields.officer;
+        delete deliveredFields.findings;
+    }
     const result = {
         ...deliveredFields,
         ...auditOwned,
@@ -44,11 +58,24 @@ export function isAuditEscalationProjection(value) {
         return false;
     return AUDIT_ESCALATION_LIVE_REGISTRY.has(value);
 }
-function humanDecisionText(result) {
-    const lines = ["Human decision required: compliance audit escalation."];
+function humanDecisionText(decision, result) {
+    const officer = Object.hasOwn(decision, "officer")
+        ? decision.officer
+        : undefined;
+    const lines = [
+        officer === undefined
+            ? "Human decision required: compliance audit escalation."
+            : `Human decision required: ${officer} escalation.`,
+    ];
+    if (officer !== undefined && typeof result.reason === "string") {
+        lines.push(`Reason: ${result.reason}`);
+    }
     if (Array.isArray(result.conflicts)) {
         lines.push("Conflicts:", ...result.conflicts.map((conflict) => `- ${conflict}`));
     }
+    if (officer !== undefined && Array.isArray(result.findings) && result.findings.length > 0) {
+        lines.push("Findings:", ...result.findings.map((finding) => `- ${finding}`));
+    }
     const gate = result.auditDecisionGate;
     if (gate !== null && typeof gate === "object" && !Array.isArray(gate)) {
         const record = gate;
@@ -63,7 +90,7 @@ function humanDecisionText(result) {
 export function projectAuditEscalation(decision, deliveredOutput) {
     const details = buildAuditEscalationResult(decision, deliveredOutput);
     return {
-        content: [{ type: "text", text: humanDecisionText(details) }],
+        content: [{ type: "text", text: humanDecisionText(decision, details) }],
         details,
         terminate: true,
         ...(decision.usage === undefined ? {} : { usage: decision.usage }),

package/dist/gatekeeper-role.js

@@ -19,11 +19,20 @@ function gateSeatLabel(stage) {
     }
 }
 export { GatekeeperDecisionError } from "./submission-errors.js";
+export class GatekeeperEscalationError extends Error {
+    gatekeeper;
+    constructor(gatekeeper) {
+        super(`门下省${gateSeatLabel(gatekeeper.officer)}上呈`);
+        this.name = "GatekeeperEscalationError";
+        this.gatekeeper = gatekeeper;
+    }
+}
 // Unknown fields so wrong types/spellings still reach projection (ADR 0055/0057; 仓第 0 条).
 // Opening goes through the sole openToolObject owner — no parallel transport helper.
 const officerDecisionSchema = openToolObject(Type.Object({
-    status: Type.Unknown({ description: "pass | bounce — 形状指引，非 schema 闸" }),
-    findings: Type.Unknown({ description: "string[] findings，随 pass 或 bounce 留存" }),
+    status: Type.Unknown({ description: "pass | bounce | escalate — 形状指引，非 schema 闸" }),
+    reason: Type.Optional(Type.Unknown({ description: "status 为 escalate 时的理由" })),
+    findings: Type.Unknown({ description: "string[] findings，随 pass、bounce 或 escalate 留存" }),
 }));
 /**
  * Direct-seat decision tool spec (#639). Lifecycle assembly stays on the
@@ -52,7 +61,7 @@ function subjectTool(subject) {
 export function createOfficerDecisionTool(name) {
     return {
         name,
-        description: "提交一份 typed pass/bounce 决议。",
+        description: "提交一份 typed pass/bounce/escalate 决议。",
         parameters: officerDecisionSchema,
         async execute(_id, args) { return result(`已收 ${String(args?.status)}`, args); },
     };
@@ -101,7 +110,7 @@ function noUsableReleaseFailure(stage, decision) {
     return {
         status: "transport_failure",
         stage,
-        reason: stage === "gatekeeper" ? "decision 无显式 dispatch" : "decision 无显式 pass/bounce",
+        reason: stage === "gatekeeper" ? "decision 无显式 dispatch" : "decision 无显式 pass/bounce/escalate",
         submission: retainedSubmission(decision),
     };
 }
@@ -143,6 +152,15 @@ function projectOfficerDecision(officer, decision) {
             findings: asStringArray(record.findings),
         };
     }
+    if (record.status === "escalate") {
+        return {
+            status: "escalate",
+            officer,
+            ...(Object.hasOwn(record, "reason") ? { reason: record.reason } : {}),
+            findings: record.findings,
+            submission: retainedSubmission(decision),
+        };
+    }
     return noUsableReleaseFailure(officer, decision);
 }
 export async function runGatekeeper(options) {
@@ -212,6 +230,9 @@ export async function requireGatekeeperPass(options) {
             error.submission = gatekeeper.submission;
         options.hostActions.failInfrastructure(error, options.context, options.toolCallId);
     }
+    if (gatekeeper.status === "escalate") {
+        throw new GatekeeperEscalationError(gatekeeper);
+    }
     // Envelope owns the execute→tool_result bridge; this module only projects + throws.
     options.hostActions.bindSubmissionNonPass(options.toolCallId, gatekeeper);
     throw new GatekeeperDecisionError(gatekeeper);