@akagilnc/pi-workflow-roles 0.1.3356 → 0.1.3384

package/README.md

@@ -47,7 +47,7 @@ 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; direct commands available)
+# Gate officers (direct summons on DONE submissions; province remains independently callable)
 ak-role config set gatekeeper <provider/model[:thinking]>
 ak-role config set inspector <provider/model[:thinking]>
 ak-role config set notary <provider/model[:thinking]>
@@ -67,7 +67,7 @@ For Gate officers (`gatekeeper` / `inspector` / `notary`) resolution is officer
 
 Receipts are typed, so callers compose roles without parsing prose; ordering and stopping stay caller-owned ([ADR 0010](docs/adr/0010-callers-own-role-composition-and-repetition.md)). Programmatic consumers derive contracts from the exported schemas in `src/package-contracts/`, not from this guide.
 
-Gate submission gate: on completing-side submissions the package may spawn the Gate province before the run settles (`gatekeeper` dispatching `inspector` or `notary`); bounce means rewrite-and-resubmit in that same session, not role failure; `planned` / `refused` / `unfinished` skip the province; read gate history from the typed gate section of the receipt, never from session prose. Pointers: [ADR 0067](docs/adr/0067-menxia-province-founding-jishizhong-fubaolang.md), [ADR 0072](docs/adr/0072-menxia-pre-pr-submission-hooks.md). A labor-engine detour that fails to spawn, exits nonzero, or produces no usable output stops the run through the existing infrastructure-failure path with the original cause visible ([ADR 0071](docs/adr/0071-engine-detour-failure-seat-fallback-declaration.md)).
+Gate submission gate: on DONE-side submissions (`completed` / `partially_completed`) the package summons the subject officer directly (`inspector` for worker completion; `notary` for judge draft / countersign verdict) — it does not spawn a Gatekeeper child to choose the seat; bounce means rewrite-and-resubmit in that same session, not role failure; `planned` / `refused` / `unfinished` skip the officer summons and settle; `ak-role gatekeeper` remains available for independent province dispatch/pass; read gate history from the typed gate section of the receipt, never from session prose. Pointers: [ADR 0067](docs/adr/0067-menxia-province-founding-jishizhong-fubaolang.md), [ADR 0072](docs/adr/0072-menxia-pre-pr-submission-hooks.md), [ADR 0079](docs/adr/0079-direct-officer-summons-ticket-memory-pointer-input.md). A labor-engine detour that fails to spawn, exits nonzero, or produces no usable output stops the run through the existing infrastructure-failure path with the original cause visible ([ADR 0071](docs/adr/0071-engine-detour-failure-seat-fallback-declaration.md)).
 
 ## Call the roles
 

package/README.zh-CN.md

@@ -47,7 +47,7 @@ ak-role judge --attach ./plan.md "Review this plan." > result.txt
 ```bash
 ak-role config set judge <provider/model[:thinking]>
 ak-role config set navigator <provider/model[:thinking]>
-# 门下省交卷闸官席（察院/符宝郎交卷自动出席，亦可直调；给事中票庭由调用者直召，见「调用百官」）
+# 门下省官席（DONE 交卷直接传召察院/符宝郎；门下省仍可独立直调；给事中票庭由调用者直召，见「调用百官」）
 ak-role config set gatekeeper <provider/model[:thinking]>
 ak-role config set inspector <provider/model[:thinking]>
 ak-role config set notary <provider/model[:thinking]>
@@ -67,7 +67,7 @@ ak-role config set-auto-resume-limit 3
 
 回执是 typed 的，调用者不必解析散文即可组合角色；顺序与停止归调用者（[ADR 0010](docs/adr/0010-callers-own-role-composition-and-repetition.md)）。编程消费者从 `src/package-contracts/` 导出推导契约，不从本文。
 
-门下省交卷闸：完成侧交卷时包可在本局结算前起省（`gatekeeper` 派 `inspector`／`notary`），封驳＝当场重写重交，不是角色失败；`planned`／`refused`／`unfinished` 不调省；闸史读回执 typed gate 段，勿刮 session 散文。指针：[ADR 0067](docs/adr/0067-menxia-province-founding-jishizhong-fubaolang.md)、[ADR 0072](docs/adr/0072-menxia-pre-pr-submission-hooks.md)。劳务引擎绕行失败沿既有基础设施故障路径停止、真因可见（[ADR 0071](docs/adr/0071-engine-detour-failure-seat-fallback-declaration.md)）。
+门下省交卷闸：DONE 侧交卷（`completed`／`partially_completed`）时包按受审物直接传召官（将作监/修内司→`inspector`；大理寺判牒/给事中署章→`notary`），不再起门下省子 session 选席；封驳＝当场重写重交，不是角色失败；`planned`／`refused`／`unfinished` 不传召官、直接结算；`ak-role gatekeeper` 仍可独立 dispatch/pass；闸史读回执 typed gate 段，勿刮 session 散文。指针：[ADR 0067](docs/adr/0067-menxia-province-founding-jishizhong-fubaolang.md)、[ADR 0072](docs/adr/0072-menxia-pre-pr-submission-hooks.md)、[ADR 0079](docs/adr/0079-direct-officer-summons-ticket-memory-pointer-input.md)。劳务引擎绕行失败沿既有基础设施故障路径停止、真因可见（[ADR 0071](docs/adr/0071-engine-detour-failure-seat-fallback-declaration.md)）。
 
 ## 调用百官
 
@@ -135,7 +135,7 @@ ak-role resume <runId> "<裁定>"
 | **御史台** | reviewer | **察举百弊，风闻奏事。** 置身事外审视成果；Standards／Spec 两条取证腿由 runtime 代跑，本席收腿报告出薄回执与 amendment。弹章须指明所劾之处，言不为狱——不负坐实义务，坐实归大理寺。 |
 | **大理寺** | judge | **审理定谳。** 承接各方意见与材料，依照既定规则逐项判断，辨明是非曲直。可以准行、退回或请示更高决定，但自身不参与建设与修改。 |
 | **审刑院** | judge-auditor／doctor-auditor（无 CLI，共享内部接缝；御史台侧闸已退役） | **复核成案。** 不重新争论事情本身，而是检查整个办理过程是否合乎规矩。关注是否有人越过职责、是否遗漏必要步骤、是否以错误方式得出正确结果。直属陛下，不入门下省编制。 |
-| **门下省** | 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)。 |
+| **门下省** | gatekeeper（交卷闸不再自动出席；可 `ak-role gatekeeper` 独立直调） | **审署诏敕与质量保证的省。** 交卷闸按受审物直接传召察院/符宝郎，本省不介入选席；调用者仍可独立传召本省作 dispatch/pass；给事中票庭由调用者开工前传召；左拾遗由调用者合并前传召；省内政，不是外层编排器。规范见 [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)、[ADR 0079](docs/adr/0079-direct-officer-summons-ticket-memory-pointer-input.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 分立。 |

package/dist/auditor-dossier-tool.js

@@ -1,6 +1,12 @@
+import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { Type } from "typebox";
 export const AUDITOR_DOSSIER_TOOL_NAME = "ak_get_run_dossier";
+/** Run-relative leaf written before gate officer summons (#632 Grok header-only session). */
+export const GATE_SUBMISSION_CANDIDATE_FILE = "gate-submission-candidate.json";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 /** Resolve the exact run binding already carried by the parent record session. */
 export function auditorRunDirectory(context) {
     const sessionFile = context.sessionManager?.getSessionFile?.();
@@ -9,8 +15,46 @@ export function auditorRunDirectory(context) {
     // Sole layout: <run>/session/session.jsonl → climb two levels to the run directory.
     return resolve(dirname(dirname(sessionFile)));
 }
+/**
+ * Latest assistant toolCall leaf on parent session books (memory or disk-backed).
+ * Grok books the candidate in memory only (#617 DK-4); Pi books the same shape on JSONL.
+ */
+export function readLatestToolCallLeaf(context) {
+    const entries = [...(context.sessionManager?.getEntries?.() ?? [])];
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const entry = entries[i];
+        if (!isRecord(entry) || entry.type !== "message" || !isRecord(entry.message))
+            continue;
+        const message = entry.message;
+        if (message.role !== "assistant" || !Array.isArray(message.content))
+            continue;
+        for (const part of message.content) {
+            if (isRecord(part) && part.type === "toolCall") {
+                return entry;
+            }
+        }
+    }
+    return undefined;
+}
+export function gateSubmissionCandidatePath(runDirectory) {
+    return join(runDirectory, "artifacts", GATE_SUBMISSION_CANDIDATE_FILE);
+}
+/**
+ * Persist the in-flight tool-call leaf as a run-directory artifact so pointer-only
+ * officer summons resolve on hosts whose session.jsonl is header-only (#632 / DK-4).
+ * Returns the written path, or undefined when no toolCall leaf is on the books.
+ */
+export function persistGateSubmissionCandidate(runDirectory, context) {
+    const leaf = readLatestToolCallLeaf(context);
+    if (leaf === undefined)
+        return undefined;
+    const path = gateSubmissionCandidatePath(runDirectory);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(leaf)}\n`, "utf8");
+    return path;
+}
 /** The one shared, run-bound dossier locator exposed to every auditor seat. */
-export function createAuditorDossierTool(runDirectory) {
+export function createAuditorDossierTool(runDirectory, options) {
     return {
         name: AUDITOR_DOSSIER_TOOL_NAME,
         description: "定位本审计席绑定的 run 卷宗及其证据入口。",
@@ -22,12 +66,17 @@ export function createAuditorDossierTool(runDirectory) {
                     details: undefined,
                 };
             }
+            const sessionPath = join(runDirectory, "session", "session.jsonl");
+            const submissionCandidate = options?.submissionCandidate;
+            // Prefer the persisted gate leaf when present: Grok session.jsonl is header-only
+            // (#617 DK-4) and is not a candidate source after material deletion (#632).
             const details = {
                 runDirectory,
                 admittedRequest: join(runDirectory, "admitted-request.json"),
-                parentSessionCandidate: join(runDirectory, "session", "session.jsonl"),
+                parentSessionCandidate: submissionCandidate ?? sessionPath,
                 attachments: join(runDirectory, "attachments"),
                 artifacts: join(runDirectory, "artifacts"),
+                ...(submissionCandidate === undefined ? {} : { submissionCandidate }),
             };
             return {
                 content: [{ type: "text", text: JSON.stringify(details) }],

package/dist/gatekeeper-role.js

@@ -1,22 +1,15 @@
 import { Type } from "typebox";
+import { auditorRunDirectory, createAuditorDossierTool, persistGateSubmissionCandidate, } from "./auditor-dossier-tool.js";
 import { executeAuditorChild } from "./evidence-child-executor.js";
 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";
-import { GATEKEEPER_OUTPUT_TOOL_NAME, gatekeeperDecisionSchema, gatekeeperOutputSchema, projectLawfulGatekeeperOutput, } from "./package-contracts/gatekeeper-output.js";
+import { GATEKEEPER_OUTPUT_TOOL_NAME, gatekeeperDecisionSchema, gatekeeperOutputSchema, } 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";
 function gateSeatLabel(stage) {
-    switch (stage) {
-        case "gatekeeper":
-            return "门下省";
-        case "inspector":
-            return "察院";
-        case "notary":
-            return "符宝郎";
-    }
+    return stage === "inspector" ? "察院" : "符宝郎";
 }
 export { GatekeeperDecisionError } from "./submission-errors.js";
 export class GatekeeperEscalationError extends Error {
@@ -49,14 +42,6 @@ export const GATEKEEPER_TOOL_SPEC = {
 function result(content, details) {
     return { content: [{ type: "text", text: content }], details };
 }
-function subjectTool(subject) {
-    return {
-        name: SUBJECT_TOOL,
-        description: "读取已受理卷宗；只供取阅，不评判不改动。",
-        parameters: Type.Object({}, { additionalProperties: false }),
-        async execute() { return result(JSON.stringify(subject), subject); },
-    };
-}
 /** Shared officer decision tool — open transport; projection owns legality. */
 export function createOfficerDecisionTool(name) {
     return {
@@ -110,7 +95,7 @@ function noUsableReleaseFailure(stage, decision) {
     return {
         status: "transport_failure",
         stage,
-        reason: stage === "gatekeeper" ? "decision 无显式 dispatch" : "decision 无显式 pass/bounce/escalate",
+        reason: "decision 无显式 pass/bounce/escalate",
         submission: retainedSubmission(decision),
     };
 }
@@ -119,19 +104,6 @@ function readRecord(value) {
         return undefined;
     return value;
 }
-function projectProvinceDecision(decision) {
-    // 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 (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).
-    return { status: "pass", findings: projected.findings ?? [] };
-}
 function projectOfficerDecision(officer, decision) {
     const record = readRecord(decision);
     if (record === undefined)
@@ -163,45 +135,29 @@ function projectOfficerDecision(officer, decision) {
     }
     return noUsableReleaseFailure(officer, decision);
 }
+/** Submission-gate summons: subject kind determines the officer without a province child. */
 export async function runGatekeeper(options) {
     const loadSoul = options.loadSoul ?? defaultLoadSoul;
-    let provinceRun;
-    try {
-        // Seat identity only — shared executor owns model config/registry/auth (#453 / ADR 0018).
-        provinceRun = await executeAuditorChild({
-            context: options.context,
-            roleLabel: "Gatekeeper",
-            gateSeat: "gatekeeper",
-            systemPrompt: await loadSoul("gatekeeper"),
-            prompt: "卷宗已受理。",
-            tool: createGatekeeperOutputTool(),
-            dossierTool: subjectTool(options.subject),
-            ...(options.signal === undefined ? {} : { signal: options.signal }),
-            ...(options.runDirectory === undefined ? {} : { runDirectory: options.runDirectory }),
-        });
-    }
-    catch (error) {
-        return { status: "transport_failure", stage: "gatekeeper", reason: failureReason(error) };
-    }
-    if (provinceRun.noReceiptLifecycle !== undefined) {
-        return { status: "no_receipt", stage: "gatekeeper", reason: `${gateSeatLabel("gatekeeper")}未产生已接受回执即散局`, facts: provinceRun.noReceiptLifecycle };
-    }
-    const province = projectProvinceDecision(provinceRun.decision);
-    if (province.status !== "dispatch")
-        return province;
-    const officer = province.officer;
+    const officer = options.subject.kind === "worker_completion" ? "inspector" : "notary";
+    // Resolve once so dossier tool and child session share the same run binding (#632).
+    const runDirectory = options.runDirectory ?? auditorRunDirectory(options.context);
+    // Pointer-only summons need a resolvable leaf: Grok session.jsonl is header-only
+    // (#617 DK-4); write the in-memory tool-call candidate as a run artifact first (#632).
+    const submissionCandidate = runDirectory === undefined
+        ? undefined
+        : persistGateSubmissionCandidate(runDirectory, options.context);
     try {
-        const roleLabel = officer === "inspector" ? "Inspector" : "Notary";
         const officerRun = await executeAuditorChild({
             context: options.context,
-            roleLabel,
+            roleLabel: officer === "inspector" ? "Inspector" : "Notary",
             gateSeat: officer,
             systemPrompt: await loadSoul(officer),
             prompt: "卷宗已受理。",
             tool: createOfficerDecisionTool(officer === "inspector" ? INSPECTOR_OUTPUT_TOOL : NOTARY_OUTPUT_TOOL),
-            dossierTool: subjectTool(options.subject),
+            // Same locator as 审刑院 — run directory + path identifiers only; no receipt body (#632).
+            dossierTool: createAuditorDossierTool(runDirectory, submissionCandidate === undefined ? undefined : { submissionCandidate }),
             ...(options.signal === undefined ? {} : { signal: options.signal }),
-            ...(options.runDirectory === undefined ? {} : { runDirectory: options.runDirectory }),
+            ...(runDirectory === undefined ? {} : { runDirectory }),
         });
         if (officerRun.noReceiptLifecycle !== undefined) {
             return { status: "no_receipt", stage: officer, reason: `${gateSeatLabel(officer)}未产生已接受回执即散局`, facts: officerRun.noReceiptLifecycle };
@@ -223,7 +179,7 @@ export async function requireGatekeeperPass(options) {
         return;
     if (gatekeeper.status === "transport_failure") {
         // Typed stage/reason/submission ride failInfrastructure → durable tool_result (#475).
-        const error = new Error(`门下省 transport_failure（${gatekeeper.stage}）：${gatekeeper.reason}`);
+        const error = new Error(`交卷闸 transport_failure（${gatekeeper.stage}）：${gatekeeper.reason}`);
         error.stage = gatekeeper.stage;
         error.reason = gatekeeper.reason;
         if (gatekeeper.submission !== undefined)