@akagilnc/pi-workflow-roles 0.1.2296 → 0.1.2310

package/README.md

@@ -161,6 +161,13 @@ Generated from `src/public-cli/option-definitions.ts`. Prefer `ak-role help <com
 | `--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). |
 
+### `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. |
+
 ### `analyst`
 
 | Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |

package/README.zh-CN.md

@@ -190,6 +190,13 @@ ak-role merger --project /path/to/worktree "Reconcile the active merge."
 | `--project` | — | `path` | 否 | 否 | option | — | 已有进行中 ordinary merge 的项目根（默认 cwd）。 |
 | `--attach` | — | `path` | 否 | 是 | option | — | 附加普通文件；受理即冻结（可重复）。 |
 
+### `notary`
+
+| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `--project` | — | `path` | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 |
+| `--source-run` | — | `runId@role\|path` | 是 | 否 | option | — | 必填源 run 定位符（簿内 runId@role，或该 run 目录路径）。零 prompt/附件投影。 |
+
 ### `analyst`
 
 | 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |

package/dist/notary-contracts.js

@@ -0,0 +1,96 @@
+/**
+ * Public Notary (符宝郎) terminating receipt contracts.
+ * Lawful explicit releases: pass | bounce | incomplete(with non-empty reason).
+ * Residual incomplete (no explicit release) is projected by public settlement, not here.
+ */
+import { Type } from "typebox";
+import { readActivationEngineLaborFallbackField, seatFallbackBaseStatus, seatFallbackStatusHasLawfulEvidence, withEngineLaborFallbackField, } from "./engine-labor-fallback.js";
+import { openToolObject } from "./open-tool-schema.js";
+export const NOTARY_OUTPUT_TOOL_NAME = "ak_notary_output";
+export const NOTARY_ACCEPTED_TEXT = "Notary output accepted";
+export const NOTARY_SOURCE_RUN_FLAG = {
+    name: "ak-notary-source-run",
+    definition: {
+        description: "Absolute source run directory bound for Notary self-fetch",
+        type: "string",
+    },
+};
+/** Package-owned kickoff only — callers supply zero prompt bytes (ADR 0067 / #448). */
+export const NOTARY_FIXED_KICKOFF = "Notary review. Bound source-run locator is on the session materials; fetch authoritative ticket, git, and dossier evidence yourself; submit one typed decision.";
+export const notaryOutputSchema = openToolObject(Type.Object({
+    status: Type.Unknown({
+        description: "pass | bounce | incomplete — guidance, not a schema gate.",
+    }),
+    findings: Type.Unknown({
+        description: "string[] findings retained with pass or bounce.",
+    }),
+    reason: Type.Unknown({
+        description: "Why the notary decision is incomplete.",
+    }),
+}));
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string");
+}
+/**
+ * Project one explicit Notary release. Throws when there is no lawful explicit
+ * pass / bounce / incomplete(reason) — callers map that to residual incomplete.
+ */
+export function validateNotaryOutput(value) {
+    if (!isRecord(value)) {
+        throw new Error("Notary output has no recognized execution discriminator");
+    }
+    const statusRaw = typeof value.status === "string" ? value.status : undefined;
+    if (statusRaw === undefined || !seatFallbackStatusHasLawfulEvidence(statusRaw, value)) {
+        throw new Error("Notary output has no recognized execution discriminator");
+    }
+    const status = seatFallbackBaseStatus(statusRaw);
+    if (status === "incomplete") {
+        const reason = value.reason;
+        if (typeof reason !== "string" || reason.trim() === "") {
+            throw new Error("Notary incomplete requires a non-empty reason");
+        }
+        return structuredClone(value);
+    }
+    if (status === "bounce") {
+        const clone = structuredClone(value);
+        if (clone.disposition === undefined)
+            clone.disposition = "rewrite";
+        if (!Array.isArray(clone.findings))
+            clone.findings = asStringArray(clone.findings);
+        return clone;
+    }
+    if (status === "pass") {
+        const clone = structuredClone(value);
+        if (!Array.isArray(clone.findings))
+            clone.findings = asStringArray(clone.findings);
+        return clone;
+    }
+    throw new Error("Notary output has no recognized execution discriminator");
+}
+/** Shape check for recorded accepted details (may include engineLaborFallback). */
+export function validateRecordedNotaryOutput(value) {
+    return validateNotaryOutput(value);
+}
+export function withNotaryAcceptedDetails(output) {
+    return withEngineLaborFallbackField(output, readActivationEngineLaborFallbackField());
+}
+export function notaryDecisiveFacts(output) {
+    const status = seatFallbackBaseStatus(String(output.status));
+    const facts = { status, officer: "notary" };
+    if (status === "pass" || status === "bounce") {
+        const findings = output.findings;
+        facts.findingsCount = Array.isArray(findings) ? findings.length : 0;
+    }
+    if (status === "bounce") {
+        facts.disposition = "rewrite";
+    }
+    if (status === "incomplete") {
+        facts.reason = output.reason;
+    }
+    return facts;
+}

package/dist/package-contracts/terminating-tools.js

@@ -9,8 +9,9 @@ import { isAuditEscalationResult } from "../audit-escalation.js";
 import { seatFallbackBaseStatus, seatFallbackStatusHasLawfulEvidence, } from "../engine-labor-fallback.js";
 import { DOCTOR_OUTPUT_TOOL_NAME, validateDoctorSubmissionShape, validateRecordedDoctorOutput } from "../doctor-contracts.js";
 import { MERGER_ACCEPTED_TEXT, MERGER_OUTPUT_TOOL_NAME, validateMergerOutput } from "../merger-contracts.js";
+import { NOTARY_ACCEPTED_TEXT, NOTARY_OUTPUT_TOOL_NAME, validateRecordedNotaryOutput } from "../notary-contracts.js";
 import { CODER_ACCEPTED_TEXT, CODER_OUTPUT_TOOL_NAME, FIXER_ACCEPTED_TEXT, FIXER_OUTPUT_TOOL_NAME, validateAcceptedWorkerDetails, } from "./worker-output.js";
-export { CODER_ACCEPTED_TEXT, CODER_OUTPUT_TOOL_NAME, COLLECTOR_ACCEPTED_TEXT, COLLECTOR_OUTPUT_TOOL, FIXER_ACCEPTED_TEXT, FIXER_OUTPUT_TOOL_NAME, JUDGE_ACCEPTED_TEXT, JUDGE_OUTPUT_TOOL_NAME, REVIEWER_ACCEPTED_TEXT, REVIEWER_OUTPUT_TOOL_NAME, MERGER_ACCEPTED_TEXT, MERGER_OUTPUT_TOOL_NAME, validateAcceptedCollectorReceipt, validateAcceptedJudgeDetails, projectReviewerIntentToReceipt, validateReviewerIntent, validateRuntimeReviewerReceipt, validateAcceptedWorkerDetails, validateDoctorSubmissionShape, validateRecordedDoctorOutput, validateMergerOutput, };
+export { CODER_ACCEPTED_TEXT, CODER_OUTPUT_TOOL_NAME, COLLECTOR_ACCEPTED_TEXT, COLLECTOR_OUTPUT_TOOL, FIXER_ACCEPTED_TEXT, FIXER_OUTPUT_TOOL_NAME, JUDGE_ACCEPTED_TEXT, JUDGE_OUTPUT_TOOL_NAME, REVIEWER_ACCEPTED_TEXT, REVIEWER_OUTPUT_TOOL_NAME, MERGER_ACCEPTED_TEXT, MERGER_OUTPUT_TOOL_NAME, validateAcceptedCollectorReceipt, validateAcceptedJudgeDetails, projectReviewerIntentToReceipt, validateReviewerIntent, validateRuntimeReviewerReceipt, validateAcceptedWorkerDetails, validateDoctorSubmissionShape, validateRecordedDoctorOutput, validateMergerOutput, validateRecordedNotaryOutput, };
 export const TERMINATING_TOOL_NAMES = [
     CODER_OUTPUT_TOOL_NAME,
     FIXER_OUTPUT_TOOL_NAME,
@@ -19,6 +20,7 @@ export const TERMINATING_TOOL_NAMES = [
     COLLECTOR_OUTPUT_TOOL,
     DOCTOR_OUTPUT_TOOL_NAME,
     MERGER_OUTPUT_TOOL_NAME,
+    NOTARY_OUTPUT_TOOL_NAME,
 ];
 export function isTerminatingToolName(name) {
     return TERMINATING_TOOL_NAMES.includes(name);
@@ -39,6 +41,8 @@ export function acceptedTextFor(toolName) {
             return "Doctor output accepted";
         case MERGER_OUTPUT_TOOL_NAME:
             return MERGER_ACCEPTED_TEXT;
+        case NOTARY_OUTPUT_TOOL_NAME:
+            return NOTARY_ACCEPTED_TEXT;
     }
 }
 export class AcceptedDetailsContractError extends Error {
@@ -78,6 +82,7 @@ export function validateAcceptedDetails(toolName, details) {
         [COLLECTOR_OUTPUT_TOOL]: [],
         [DOCTOR_OUTPUT_TOOL_NAME]: ["completed", "refused"],
         [MERGER_OUTPUT_TOOL_NAME]: ["completed", "escalate"],
+        [NOTARY_OUTPUT_TOOL_NAME]: ["pass", "bounce", "incomplete"],
     };
     const collectorDiscriminator = toolName === COLLECTOR_OUTPUT_TOOL && Array.isArray(candidate?.groups);
     const baseDiscriminator = typeof discriminator === "string" ? seatFallbackBaseStatus(discriminator) : discriminator;
@@ -107,6 +112,8 @@ export function validateAcceptedDetails(toolName, details) {
                 return validateRecordedDoctorOutput(details);
             case MERGER_OUTPUT_TOOL_NAME:
                 return validateMergerOutput(details);
+            case NOTARY_OUTPUT_TOOL_NAME:
+                return validateRecordedNotaryOutput(details);
         }
     }
     catch (error) {
@@ -143,7 +150,8 @@ export function acceptedFacts(toolName, details) {
         case CODER_OUTPUT_TOOL_NAME:
         case FIXER_OUTPUT_TOOL_NAME:
         case REVIEWER_OUTPUT_TOOL_NAME:
-        case DOCTOR_OUTPUT_TOOL_NAME: return { status: details.status };
+        case DOCTOR_OUTPUT_TOOL_NAME:
+        case NOTARY_OUTPUT_TOOL_NAME: return { status: details.status };
         case JUDGE_OUTPUT_TOOL_NAME: return { status: details.judgeStatus };
         case MERGER_OUTPUT_TOOL_NAME: {
             const output = details;

package/dist/packaged-role-registry.js

@@ -4,6 +4,7 @@ import { REVIEWER_OUTPUT_TOOL_NAME } from "./package-contracts/reviewer-output.j
 import { CODER_OUTPUT_TOOL_NAME, FIXER_OUTPUT_TOOL_NAME } from "./package-contracts/worker-output.js";
 import { DOCTOR_OUTPUT_TOOL_NAME } from "./doctor-contracts.js";
 import { MERGER_OUTPUT_TOOL_NAME } from "./merger-contracts.js";
+import { NOTARY_OUTPUT_TOOL_NAME } from "./notary-contracts.js";
 const PACKAGED_ROLE_REGISTRY = [
   { role: "judge", phases: [null], outputTool: JUDGE_OUTPUT_TOOL_NAME, inputFlag: void 0, phaseFlag: void 0, activationStage: "load-and-install" },
   { role: "fixer", phases: ["plan", "apply"], outputTool: FIXER_OUTPUT_TOOL_NAME, inputFlag: "ak-fix-packet", phaseFlag: "ak-fixer-phase", activationStage: "load-and-install" },
@@ -11,7 +12,8 @@ const PACKAGED_ROLE_REGISTRY = [
   { role: "reviewer", phases: [null], outputTool: REVIEWER_OUTPUT_TOOL_NAME, inputFlag: void 0, phaseFlag: void 0, activationStage: "load-and-install" },
   { role: "collector", phases: [null], outputTool: COLLECTOR_OUTPUT_TOOL, inputFlag: "ak-collector-repo", phaseFlag: void 0, activationStage: "load-and-install" },
   { role: "doctor", phases: [null], outputTool: DOCTOR_OUTPUT_TOOL_NAME, inputFlag: "ak-doctor-case", phaseFlag: void 0, activationStage: "load-and-install" },
-  { role: "merger", phases: [null], outputTool: MERGER_OUTPUT_TOOL_NAME, inputFlag: "ak-merger-input", phaseFlag: void 0, activationStage: "prepare-git-and-install" }
+  { role: "merger", phases: [null], outputTool: MERGER_OUTPUT_TOOL_NAME, inputFlag: "ak-merger-input", phaseFlag: void 0, activationStage: "prepare-git-and-install" },
+  { role: "notary", phases: [null], outputTool: NOTARY_OUTPUT_TOOL_NAME, inputFlag: "ak-notary-source-run", phaseFlag: void 0, activationStage: "load-and-install" }
 ];
 function packagedRoleMetadata(role) {
   return PACKAGED_ROLE_REGISTRY.find((entry) => entry.role === role);