@akagilnc/pi-workflow-roles 0.1.1766 → 0.1.1772

package/dist/package-contracts/fixer-output.js

@@ -32,7 +32,7 @@ const completedClassResultsSchema = Type.Array(completedClassResultSchema, { min
 const fixerOutputVariants = Type.Union([
     Type.Object({ status: Type.Literal("planned", { description: "Plan-phase proposal outcome." }), report: Type.String({ minLength: 1, description: "Truthful Fixer outcome report." }) }),
     Type.Object({ status: Type.Literal("refused", { description: "Lawfully refused outcome." }), report: Type.String({ minLength: 1, description: "Truthful Fixer outcome report." }), remainingScope: Type.String({ minLength: 1, description: "Work that cannot lawfully be performed." }), blocker: Type.Unsafe({ ...blockerSchema, description: "Lawful blocker preventing completion." }) }),
-    Type.Object({ status: Type.Literal("unfinished", { description: "Honest unfinished apply outcome." }), report: Type.String({ minLength: 1, description: "Truthful Fixer outcome report." }), remainingScope: Type.String({ minLength: 1, description: "Work remaining after this invocation." }), classResults: Type.Optional(Type.Unsafe({ ...completedClassResultsSchema, description: "Completed class settlements from this invocation." })), testEvidence: Type.Optional(testEvidenceSchema) }),
+    Type.Object({ status: Type.Literal("unfinished", { description: "Apply outcome when a missing prerequisite or an unconstitutional constraint blocks completing this invocation; state the reason." }), report: Type.String({ minLength: 1, description: "Truthful Fixer outcome report." }), remainingScope: Type.String({ minLength: 1, description: "Work remaining after this invocation." }), reason: Type.Optional(Type.String({ minLength: 1, description: "Blocking reason: prerequisite missing or unconstitutional. A missing pending owner decision or answer is a missing prerequisite." })), classResults: Type.Optional(Type.Unsafe({ ...completedClassResultsSchema, description: "Completed class settlements from this invocation." })), testEvidence: Type.Optional(testEvidenceSchema) }),
     Type.Object({ status: Type.Literal("completed", { description: "All assigned classes completed." }), report: Type.String({ minLength: 1, description: "Truthful Fixer outcome report." }), classResults: Type.Array(classResultSchema, { minItems: 1, description: "Completed class settlements." }), testEvidence: Type.Optional(testEvidenceSchema) }),
     Type.Object({ status: Type.Literal("refused", { description: "All assigned classes lawfully refused." }), report: Type.String({ minLength: 1, description: "Truthful Fixer outcome report." }), classResults: Type.Array(classResultSchema, { minItems: 1, description: "Per-class refusal settlements." }) }),
     Type.Object({ status: Type.Literal("partially_completed", { description: "Assigned classes include completions and lawful refusals." }), report: Type.String({ minLength: 1, description: "Truthful Fixer outcome report." }), classResults: Type.Array(classResultSchema, { minItems: 1, description: "Per-class completion or refusal settlements." }), testEvidence: Type.Optional(testEvidenceSchema) }),

package/dist/public-cli/main.js

@@ -13968,7 +13968,7 @@ var init_fixer_output = __esm({
     fixerOutputVariants = typebox_exports.Union([
       typebox_exports.Object({ status: typebox_exports.Literal("planned", { description: "Plan-phase proposal outcome." }), report: typebox_exports.String({ minLength: 1, description: "Truthful Fixer outcome report." }) }),
       typebox_exports.Object({ status: typebox_exports.Literal("refused", { description: "Lawfully refused outcome." }), report: typebox_exports.String({ minLength: 1, description: "Truthful Fixer outcome report." }), remainingScope: typebox_exports.String({ minLength: 1, description: "Work that cannot lawfully be performed." }), blocker: typebox_exports.Unsafe({ ...blockerSchema, description: "Lawful blocker preventing completion." }) }),
-      typebox_exports.Object({ status: typebox_exports.Literal("unfinished", { description: "Honest unfinished apply outcome." }), report: typebox_exports.String({ minLength: 1, description: "Truthful Fixer outcome report." }), remainingScope: typebox_exports.String({ minLength: 1, description: "Work remaining after this invocation." }), classResults: typebox_exports.Optional(typebox_exports.Unsafe({ ...completedClassResultsSchema, description: "Completed class settlements from this invocation." })), testEvidence: typebox_exports.Optional(testEvidenceSchema) }),
+      typebox_exports.Object({ status: typebox_exports.Literal("unfinished", { description: "Apply outcome when a missing prerequisite or an unconstitutional constraint blocks completing this invocation; state the reason." }), report: typebox_exports.String({ minLength: 1, description: "Truthful Fixer outcome report." }), remainingScope: typebox_exports.String({ minLength: 1, description: "Work remaining after this invocation." }), reason: typebox_exports.Optional(typebox_exports.String({ minLength: 1, description: "Blocking reason: prerequisite missing or unconstitutional. A missing pending owner decision or answer is a missing prerequisite." })), classResults: typebox_exports.Optional(typebox_exports.Unsafe({ ...completedClassResultsSchema, description: "Completed class settlements from this invocation." })), testEvidence: typebox_exports.Optional(testEvidenceSchema) }),
       typebox_exports.Object({ status: typebox_exports.Literal("completed", { description: "All assigned classes completed." }), report: typebox_exports.String({ minLength: 1, description: "Truthful Fixer outcome report." }), classResults: typebox_exports.Array(classResultSchema, { minItems: 1, description: "Completed class settlements." }), testEvidence: typebox_exports.Optional(testEvidenceSchema) }),
       typebox_exports.Object({ status: typebox_exports.Literal("refused", { description: "All assigned classes lawfully refused." }), report: typebox_exports.String({ minLength: 1, description: "Truthful Fixer outcome report." }), classResults: typebox_exports.Array(classResultSchema, { minItems: 1, description: "Per-class refusal settlements." }) }),
       typebox_exports.Object({ status: typebox_exports.Literal("partially_completed", { description: "Assigned classes include completions and lawful refusals." }), report: typebox_exports.String({ minLength: 1, description: "Truthful Fixer outcome report." }), classResults: typebox_exports.Array(classResultSchema, { minItems: 1, description: "Per-class completion or refusal settlements." }), testEvidence: typebox_exports.Optional(testEvidenceSchema) })
@@ -18777,6 +18777,10 @@ function coderDecisiveFacts(output) {
   if (status.readable && typeof status.value === "string") facts.coderStatus = status.value;
   const remainingScope = safelyRead(candidate, "remainingScope");
   if (status.readable && status.value === "unfinished" && remainingScope.readable && typeof remainingScope.value === "string") facts.remainingScope = remainingScope.value;
+  const reason = safelyRead(candidate, "reason");
+  if (status.readable && status.value === "unfinished" && reason.readable && typeof reason.value === "string" && reason.value.trim().length > 0) {
+    facts.reason = reason.value;
+  }
   const report = safelyRead(candidate, "report");
   if (report.readable && typeof report.value === "string") facts.reportPresent = report.value.trim().length > 0;
   return facts;
@@ -18788,6 +18792,10 @@ function fixerDecisiveFacts(output) {
   if (status.readable && typeof status.value === "string") facts.fixerStatus = status.value;
   const remainingScope = safelyRead(candidate, "remainingScope");
   if (status.readable && (status.value === "unfinished" || status.value === "refused") && remainingScope.readable && typeof remainingScope.value === "string") facts.remainingScope = remainingScope.value;
+  const reason = safelyRead(candidate, "reason");
+  if (status.readable && status.value === "unfinished" && reason.readable && typeof reason.value === "string" && reason.value.trim().length > 0) {
+    facts.reason = reason.value;
+  }
   const blockerRead = safelyRead(candidate, "blocker");
   if (status.readable && status.value === "refused" && blockerRead.readable && isRecord4(blockerRead.value)) {
     const cause = safelyRead(blockerRead.value, "cause");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.1766",
+  "version": "0.1.1772",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/souls/coder.md

@@ -6,6 +6,5 @@
 - 做最小垂直切片，优先复用已有 seam；不造平行机制，不借机扩大 scope。
 - 计划与施工都要说明真实刀口、行为边界和验证方法，不用空泛完成声明代替证据。
 - 切片验证只跑本片聚焦测试与 typecheck。
-- unfinished 仅一种情况可用：前置条件缺失、派单不合理或违宪导致本次无法完成，回执必须说明理由。
 - 派单与 authority 冲突、事实不成立或需要未授权设计时，据理拒绝并给出可核验证据；不猜测施工。
 - 不 amend、rewrite 或 push。Git 变化是证据之一，不取代角色报告。

package/souls/fixer.md

@@ -8,7 +8,6 @@
 * 前科检查:动刀前查相关文件 git log,不再提交既往已失败的同族修法。
 * 测试是红线:不得放松断言、删失败路径或改验收换绿灯,除非 authority 明确授权。
 * 每轮验证只跑与被修 finding 绑定的测试与 typecheck。
-* unfinished 仅一种情况可用:前置条件缺失、派单不合理或违宪导致本次无法完成,回执必须说明理由。
 * 只在当前指派无法合法执行时拒绝。
 * 保护开工前已有改动;本轮只含授权内容,只建新 forward commit,不 amend。commit带平台前缀
 * 交卷说明修了什么根因、未采纳的 finding 及理由,使修复与验证可独立审计。

package/src/package-contracts/fixer-output.ts

@@ -35,7 +35,7 @@ const completedClassResultsSchema = Type.Array(completedClassResultSchema, { min
 const fixerOutputVariants = Type.Union([
   Type.Object({ status: Type.Literal("planned", { description: "Plan-phase proposal outcome." }), report: Type.String({ minLength: 1, description: "Truthful Fixer outcome report." }) }),
   Type.Object({ status: Type.Literal("refused", { description: "Lawfully refused outcome." }), report: Type.String({ minLength: 1, description: "Truthful Fixer outcome report." }), remainingScope: Type.String({ minLength: 1, description: "Work that cannot lawfully be performed." }), blocker: Type.Unsafe({ ...blockerSchema, description: "Lawful blocker preventing completion." }) }),
-  Type.Object({ status: Type.Literal("unfinished", { description: "Honest unfinished apply outcome." }), report: Type.String({ minLength: 1, description: "Truthful Fixer outcome report." }), remainingScope: Type.String({ minLength: 1, description: "Work remaining after this invocation." }), classResults: Type.Optional(Type.Unsafe({ ...completedClassResultsSchema, description: "Completed class settlements from this invocation." })), testEvidence: Type.Optional(testEvidenceSchema) }),
+  Type.Object({ status: Type.Literal("unfinished", { description: "Apply outcome when a missing prerequisite or an unconstitutional constraint blocks completing this invocation; state the reason." }), report: Type.String({ minLength: 1, description: "Truthful Fixer outcome report." }), remainingScope: Type.String({ minLength: 1, description: "Work remaining after this invocation." }), reason: Type.Optional(Type.String({ minLength: 1, description: "Blocking reason: prerequisite missing or unconstitutional. A missing pending owner decision or answer is a missing prerequisite." })), classResults: Type.Optional(Type.Unsafe({ ...completedClassResultsSchema, description: "Completed class settlements from this invocation." })), testEvidence: Type.Optional(testEvidenceSchema) }),
   Type.Object({ status: Type.Literal("completed", { description: "All assigned classes completed." }), report: Type.String({ minLength: 1, description: "Truthful Fixer outcome report." }), classResults: Type.Array(classResultSchema, { minItems: 1, description: "Completed class settlements." }), testEvidence: Type.Optional(testEvidenceSchema) }),
   Type.Object({ status: Type.Literal("refused", { description: "All assigned classes lawfully refused." }), report: Type.String({ minLength: 1, description: "Truthful Fixer outcome report." }), classResults: Type.Array(classResultSchema, { minItems: 1, description: "Per-class refusal settlements." }) }),
   Type.Object({ status: Type.Literal("partially_completed", { description: "Assigned classes include completions and lawful refusals." }), report: Type.String({ minLength: 1, description: "Truthful Fixer outcome report." }), classResults: Type.Array(classResultSchema, { minItems: 1, description: "Per-class completion or refusal settlements." }), testEvidence: Type.Optional(testEvidenceSchema) }),

package/src/package-contracts/worker-output.ts

@@ -23,7 +23,7 @@ export type WorkerRoleLabel = "Coder" | "Fixer";
 export type CoderOutput =
   | { status: "planned"; report: string }
   | { status: "completed" | "refused"; report: string }
-  | { status: "unfinished"; report: string; remainingScope: string };
+  | { status: "unfinished"; report: string; remainingScope: string; reason?: string };
 export type WorkerOutput = CoderOutput | FixerOutput;
 
 export function validateAcceptedCoderDetails(output: unknown): CoderOutput {

package/src/public-cli/settlement.ts

@@ -900,6 +900,10 @@ function coderDecisiveFacts(output: CoderOutput): Record<string, unknown> {
   if (status.readable && typeof status.value === "string") facts.coderStatus = status.value;
   const remainingScope = safelyRead(candidate, "remainingScope");
   if (status.readable && status.value === "unfinished" && remainingScope.readable && typeof remainingScope.value === "string") facts.remainingScope = remainingScope.value;
+  const reason = safelyRead(candidate, "reason");
+  if (status.readable && status.value === "unfinished" && reason.readable && typeof reason.value === "string" && reason.value.trim().length > 0) {
+    facts.reason = reason.value;
+  }
   const report = safelyRead(candidate, "report");
   if (report.readable && typeof report.value === "string") facts.reportPresent = report.value.trim().length > 0;
   return facts;
@@ -912,6 +916,10 @@ function fixerDecisiveFacts(output: FixerOutput): Record<string, unknown> {
   if (status.readable && typeof status.value === "string") facts.fixerStatus = status.value;
   const remainingScope = safelyRead(candidate, "remainingScope");
   if (status.readable && (status.value === "unfinished" || status.value === "refused") && remainingScope.readable && typeof remainingScope.value === "string") facts.remainingScope = remainingScope.value;
+  const reason = safelyRead(candidate, "reason");
+  if (status.readable && status.value === "unfinished" && reason.readable && typeof reason.value === "string" && reason.value.trim().length > 0) {
+    facts.reason = reason.value;
+  }
   const blockerRead = safelyRead(candidate, "blocker");
   if (status.readable && status.value === "refused" && blockerRead.readable && isRecord(blockerRead.value)) {
     const cause = safelyRead(blockerRead.value, "cause");

package/src/worker-role.ts

@@ -61,9 +61,17 @@ const coderOutputVariants = Type.Union([
     report: Type.String({ minLength: 1, description: "Truthful Coder outcome report." }),
   }, { additionalProperties: false }),
   Type.Object({
-    status: StringEnum(["unfinished"] as const, { description: "Honest unfinished apply outcome." }),
+    status: StringEnum(["unfinished"] as const, {
+      description:
+        "Apply outcome when a missing prerequisite or an unconstitutional constraint blocks completing this invocation; state the reason.",
+    }),
     report: Type.String({ minLength: 1, description: "Truthful Coder outcome report." }),
     remainingScope: Type.String({ minLength: 1, description: "Work remaining after this invocation." }),
+    reason: Type.Optional(Type.String({
+      minLength: 1,
+      description:
+        "Blocking reason: prerequisite missing or unconstitutional. A missing pending owner decision or answer is a missing prerequisite.",
+    })),
   }, { additionalProperties: false }),
 ]);
 const coderOutputSchema = openToolObjectFromUnion(coderOutputVariants);
@@ -222,12 +230,13 @@ export function createFixerRoleRuntime(
           name: FIXER_OUTPUT_TOOL_NAME,
           label: "Fixer Output",
           description:
-            "Submit the plan refusal, apply settlement, or honest unfinished handover.",
+            "Submit the plan refusal, apply settlement, or unfinished blocked-handover receipt.",
           promptSnippet: "Submit the final fixer report",
           promptGuidelines: [
             `Use ${FIXER_OUTPUT_TOOL_NAME} as the final action for the fixer role.`,
             `${FIXER_OUTPUT_TOOL_NAME} reports only lawful assignment blockers; infrastructure failures abort.`,
             "plan permits planned|refused; apply permits completed|refused|partially_completed|unfinished.",
+            "unfinished is available only when a missing prerequisite or an unconstitutional constraint prevents completing this invocation; state the reason. A missing pending owner decision or answer is a missing prerequisite.",
             "When the diff includes test changes, submit testEvidence: contract proven, one-line minimum necessary cost, measured duration.",
           ],
           parameters: fixerOutputSchema,
@@ -242,7 +251,7 @@ export function createFixerRoleRuntime(
               ctx,
             );
             const output = deepFreeze(validateFixerOutputForPacket(parameters, phase, packet));
-            submissionGate.assertAcceptable(output.status);
+            submissionGate.assertAcceptable(output.status, output);
             return {
               content: [{ type: "text" as const, text: "Fixer report accepted" }],
               details: output,
@@ -345,12 +354,13 @@ export function createCoderRoleRuntime(
           name: CODER_OUTPUT_TOOL_NAME,
           label: "Coder Output",
           description:
-            "Submit a plan, completion, unfinished handoff, or evidence-bearing refusal for the active coder phase.",
+            "Submit a plan, completion, unfinished blocked-handover, or evidence-bearing refusal for the active coder phase.",
           promptSnippet: "Submit the final coder report",
           promptGuidelines: [
             `Use ${CODER_OUTPUT_TOOL_NAME} as the final action for the coder role.`,
             `${CODER_OUTPUT_TOOL_NAME} never escalates; explain authority or task conflicts in report for the caller to dispose.`,
-            "plan permits planned|refused; apply permits completed|unfinished|refused. unfinished requires a non-blank remainingScope.",
+            "plan permits planned|refused; apply permits completed|unfinished|refused.",
+            "unfinished is available only when a missing prerequisite or an unconstitutional constraint prevents completing this invocation; state the reason. A missing pending owner decision or answer is a missing prerequisite.",
             "A completed apply report must preserve evidence for TDD, the same-pattern check, introduced-regression check, and behavior-fact check.",
           ],
           parameters: coderOutputSchema,
@@ -373,7 +383,7 @@ export function createCoderRoleRuntime(
                 "Coder completed requires the Matt tdd skill to be expanded through Pi /skill:tdd",
               );
             }
-            submissionGate.assertAcceptable(output.status);
+            submissionGate.assertAcceptable(output.status, output);
             return {
               content: [{ type: "text" as const, text: "Coder report accepted" }],
               details: output,

package/src/worker-submission-gates.ts

@@ -24,6 +24,27 @@ export class WorkerCommitReminderError extends Error {
   constructor() { super("未观察到 commit"); this.name = "WorkerCommitReminderError"; }
 }
 
+/** #292 unfinished reason solicitation — same bounce shape as gate ①; in-session only. */
+export class WorkerUnfinishedReasonReminderError extends Error {
+  readonly code = "worker_unfinished_reason_reminder" as const;
+  constructor() {
+    super("补理由（前置缺失/违宪之一）或继续施工");
+    this.name = "WorkerUnfinishedReasonReminderError";
+  }
+}
+
+const UNFINISHED_REASON_BOUNCE_LIMIT = 2;
+
+function unfinishedReasonPresent(details?: unknown): boolean {
+  if (typeof details !== "object" || details === null) return false;
+  try {
+    const reason = (details as { reason?: unknown }).reason;
+    return typeof reason === "string" && reason.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
 export type WorkerSubmissionGateParent = RecordSessionParent;
 
 function git(cwd: string, args: string[]): string {
@@ -90,7 +111,25 @@ export function installWorkerGitHooks(cwd: string): void {
   try { bareInCommon = gitFile(commonConfig, ["--get", "core.bare"]) === "true"; } catch { /* unset */ }
   try { worktreeInCommon = gitFile(commonConfig, ["--get", "core.worktree"]); } catch { /* unset */ }
 
-  git(cwd, ["config", "extensions.worktreeConfig", "true"]);
+  // Skip shared write when already enabled in *this* repo — concurrent sibling activations
+  // otherwise race on .git/config.lock (#267). Scope must be --local (common config): a
+  // global/system true must not skip the repo's first enable. Value must use Git bool
+  // semantics (true/yes/on/1), not a literal "true" compare. First enable still writes;
+  // real write failures still throw. Only --get exit 1 means unset; other failures stay loud.
+  let worktreeConfigEnabled = false;
+  try {
+    worktreeConfigEnabled =
+      git(cwd, ["config", "--local", "--bool", "--get", "extensions.worktreeConfig"]) === "true";
+  } catch (error) {
+    const status =
+      typeof error === "object" && error !== null && "status" in error
+        ? (error as { status: unknown }).status
+        : undefined;
+    if (status !== 1) throw error;
+  }
+  if (!worktreeConfigEnabled) {
+    git(cwd, ["config", "extensions.worktreeConfig", "true"]);
+  }
 
   // Migrate immediately so sibling trees never observe bare-in-common under worktreeConfig.
   if (bareInCommon) {
@@ -176,11 +215,12 @@ function readGateState(session: SessionManager): {
 
 export function createWorkerSubmissionGate(): {
   arm(cwd: string, parent?: WorkerSubmissionGateParent): void;
-  assertAcceptable(status: string): void;
+  assertAcceptable(status: string, details?: unknown): void;
 } {
   let baseline: string | null | undefined;
   let root: string | undefined;
   let reminded = false;
+  let unfinishedReasonBounces = 0;
   let record: SessionManager | undefined;
   // null = unborn HEAD only; any other git failure throws (no swallow).
   const head = (cwd: string): string | null => {
@@ -209,7 +249,14 @@ export function createWorkerSubmissionGate(): {
         head: baseline,
       });
     },
-    assertAcceptable(status) {
+    assertAcceptable(status, details) {
+      // #292: unfinished without a non-blank reason → in-session bounce (max 2), then accept.
+      if (status === "unfinished" && !unfinishedReasonPresent(details)) {
+        if (unfinishedReasonBounces < UNFINISHED_REASON_BOUNCE_LIMIT) {
+          unfinishedReasonBounces += 1;
+          throw new WorkerUnfinishedReasonReminderError();
+        }
+      }
       if (baseline === undefined || root === undefined || !DONE.has(status)) return;
       const now = head(root);
       if ((now !== null && (baseline === null || now !== baseline)) || reminded) {