@akagilnc/pi-workflow-roles 0.1.3873 → 0.1.3886

package/src/public-cli/invocation.ts

@@ -211,11 +211,10 @@ export type AdmittedReviewerInvocation = AdmittedRoleInvocationBase & {
   readonly authorityRefs: readonly string[];
 };
 
-/** Mechanical envelope derived from the active ordinary two-parent merge. */
+/** Mechanical materials read from current Git state (may be empty). */
 export type DerivedMergerEnvelope = {
   readonly targetObjectId: string;
   readonly sourceObjectId: string;
-  readonly automaticMergeTreeId: string;
   readonly expectedConflictPaths: readonly string[];
   readonly resolutionScope: readonly string[];
 };
@@ -810,17 +809,6 @@ export type ParseAnalystArgvResult =
   | ParseAnalystSweepArgv
   | ParseAnalystCohortArgv;
 
-/** Honest activation-class failure while deriving the active-merge envelope. */
-export class MergerEnvelopeDerivationError extends Error {
-  readonly code = "merger-envelope-derivation" as const;
-  /** Typed cause for #107 classifyPostAdmissionFailure (isTypedActivationError). */
-  readonly knownCause = "activation" as const;
-  constructor(message: string, options?: { cause?: unknown }) {
-    super(message, options);
-    this.name = "MergerEnvelopeDerivationError";
-  }
-}
-
 /** Reject missing/blank path values so empty overrides cannot silently degrade. */
 function requireOptionPath(
   flag: string,
@@ -2868,7 +2856,7 @@ export function parseMergerArgv(args: readonly string[]): ParseMergerArgvResult
       token.startsWith("--resolutionScope=")
     ) {
       throw new CliUsageError(
-        "merger does not accept public packet fields; the adapter derives the active-merge envelope",
+        "merger does not accept public packet fields; the adapter reads Git merge materials",
       );
     }
     if (token.startsWith("-") && token !== "-") {
@@ -2894,36 +2882,20 @@ function mergerMaterialFromUtf8(text: string): MergerInput["materials"]["task"]
 }
 
 /**
- * Derive the mechanical Merger envelope from an already-active ordinary merge.
- * Uses the production Git seam (HEAD, sole MERGE_HEAD, AUTO_MERGE, unmerged set).
- * Failures are activation-class facts — not CLI semantic guesses.
+ * Read merger materials from current Git state.
+ * No in-progress merge / empty conflict set still yields materials (possibly empty);
+ * code does not gate attendance on merge state (#827).
  */
 export async function deriveMergerEnvelopeFromActiveMerge(
   projectRoot: string,
   gitState: MergerGitState = createProductionMergerGitState(projectRoot),
 ): Promise<DerivedMergerEnvelope> {
-  let state;
-  try {
-    state = await gitState.activeMerge();
-  } catch (error) {
-    const message =
-      error instanceof Error && error.message.trim() !== ""
-        ? error.message
-        : "Assigned repository does not have one ordinary in-progress merge";
-    throw new MergerEnvelopeDerivationError(message, { cause: error });
-  }
-  if (state.unmergedPaths.length === 0) {
-    throw new MergerEnvelopeDerivationError(
-      "Assigned repository does not have one ordinary in-progress merge with a complete conflict set",
-    );
-  }
+  const state = await gitState.activeMerge();
   const expectedConflictPaths = Object.freeze([...state.unmergedPaths]);
-  // Scope is derived as the complete conflict set; the role may not broaden it.
   const resolutionScope = Object.freeze([...state.unmergedPaths]);
   return Object.freeze({
     targetObjectId: state.targetObjectId,
     sourceObjectId: state.sourceObjectId,
-    automaticMergeTreeId: state.automaticMergeTreeId,
     expectedConflictPaths,
     resolutionScope,
   });
@@ -2945,8 +2917,9 @@ export type AdmitMergerInvocationOptions = {
 
 /**
  * Admit a Merger Role run on the common Invocation request.
- * Mechanical envelope (parents, AUTO_MERGE, conflicts, scope) is derived from
- * the active merge — callers never supply public packet fields for those facts.
+ * Git materials (parents, conflicts, scope) are read from the worktree and
+ * handed to the role as assignment materials — including when empty (#827).
+ * Callers never supply public packet fields for those facts.
  */
 export async function admitMergerInvocation(
   options: AdmitMergerInvocationOptions,
@@ -2960,8 +2933,6 @@ export async function admitMergerInvocation(
   }
 
   const projectRoot = resolve(options.project ?? options.cwd);
-  // Derive mechanical envelope before placing a run identity so no-merge/drift
-  // fails honestly without orphan ledger rows or guessed packet fields.
   const derived = await deriveMergerEnvelopeFromActiveMerge(
     projectRoot,
     options.gitState ?? createProductionMergerGitState(projectRoot),
@@ -2988,18 +2959,18 @@ export async function admitMergerInvocation(
   const attachments = await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
 
   // Intent materials seed primary-source investigation; the method owns the work.
+  const targetLabel = derived.targetObjectId === "" ? "(none observed)" : derived.targetObjectId;
+  const sourceLabel = derived.sourceObjectId === "" ? "(none observed)" : derived.sourceObjectId;
   const targetIntent = mergerMaterialFromUtf8(
-    `Investigate primary sources for target parent ${derived.targetObjectId}. Do not invent intent.`,
+    `Investigate primary sources for target parent ${targetLabel}. Do not invent intent.`,
   );
   const sourceIntent = mergerMaterialFromUtf8(
-    `Investigate primary sources for source parent ${derived.sourceObjectId}. Do not invent intent.`,
+    `Investigate primary sources for source parent ${sourceLabel}. Do not invent intent.`,
   );
   const taskMaterial = mergerMaterialFromUtf8(instruction);
   const authorityMaterial = mergerMaterialFromUtf8(instruction);
 
-  // Validate merger envelope before placing admitted identity.
   const mergerInput = validateMergerInput({
-    version: 1,
     attemptId: runId,
     targetObjectId: derived.targetObjectId,
     sourceObjectId: derived.sourceObjectId,
@@ -3011,7 +2982,6 @@ export async function admitMergerInvocation(
     },
     expectedConflictPaths: [...derived.expectedConflictPaths],
     resolutionScope: [...derived.resolutionScope],
-    // Authorized checks remain available on the assignment; default none.
     authorizedChecks: [],
   });
 
@@ -3035,7 +3005,6 @@ export async function admitMergerInvocation(
     derived: {
       targetObjectId: derived.targetObjectId,
       sourceObjectId: derived.sourceObjectId,
-      automaticMergeTreeId: derived.automaticMergeTreeId,
       expectedConflictPaths: [...derived.expectedConflictPaths],
       resolutionScope: [...derived.resolutionScope],
     },

package/src/public-cli/merger-run.ts

@@ -1,18 +1,13 @@
 /**
- * Public Merger Role run: derive active-merge envelope → force package
- * merge-only method → post-admission coordinator → settle Terminal result (#114 / #517).
+ * Public Merger Role run: read Git materials → force package merge-only method
+ * → post-admission coordinator → settle Terminal result (#114 / #517 / #827).
  * #526: execution via RoleTurnHost; argv is Pi adapter internal.
  */
 import type {
-  DurablePrincipalAuthority,
   MethodBinding,
   RoleTurnKnownFailure,
   RoleTurnRequest,
 } from "../host-contracts.ts";
-import { mkdir, writeFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
-
-import { ensureRealDirectoryTree } from "../activation-ledger-topology.ts";
 import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.ts";
 import {
   loadPackagedMethodSkillMaterial,
@@ -20,13 +15,10 @@ import {
   type PackagedMethodSkillMaterial,
   type PackagedMethodSkillProvenance,
 } from "../package-resources/method-skill.ts";
-import { uuidv7 } from "../uuidv7.ts";
 import { CliUsageError } from "./cli-errors.ts";
 import {
   admitMergerInvocation,
   buildMergerTransportPrompt,
-  issueAdmissionPlacement,
-  MergerEnvelopeDerivationError,
   type AdmittedMergerInvocation,
 } from "./invocation.ts";
 import {
@@ -116,82 +108,6 @@ async function loadMergerMethodMaterial(
   );
 }
 
-/**
- * Structural admit shell when envelope derivation fails: keeps role-correct
- * Terminal identity for honest activation-class settlement without inventing
- * parents/conflicts (those stay empty; the gate never receives a guessed packet).
- */
-async function admitMergerShellForActivationFailure(options: {
-  home: string;
-  cwd: string;
-  instruction: string;
-  project?: string;
-  createRunId?: () => string;
-  principalAuthority: DurablePrincipalAuthority;
-}): Promise<AdmittedMergerInvocation> {
-  const projectRoot = resolve(options.project ?? options.cwd);
-  const runId = (options.createRunId ?? uuidv7)();
-  const {
-    principal,
-    sessionDirectory,
-    sessionFile,
-    runDirectory,
-    ledgerHome,
-    bookKey,
-  } = issueAdmissionPlacement(options.principalAuthority, {
-    cwd: projectRoot,
-    runId,
-    role: "merger",
-    home: options.home,
-  });
-  ensureRealDirectoryTree(ledgerHome, sessionDirectory);
-  await mkdir(runDirectory, { recursive: true });
-  const emptyDerived = {
-    targetObjectId: "",
-    sourceObjectId: "",
-    automaticMergeTreeId: "",
-    expectedConflictPaths: [] as string[],
-    resolutionScope: [] as string[],
-  };
-  const admittedRequestPath = join(runDirectory, "admitted-request.json");
-  const mergerInputPath = join(runDirectory, "merger-input.json");
-  await writeFile(
-    admittedRequestPath,
-    `${JSON.stringify(
-      {
-        role: "merger",
-        runId,
-        bookKey,
-        projectRoot,
-        instruction: options.instruction,
-        instructionEmpty: false,
-        mergerInputPath,
-        derived: emptyDerived,
-        attachments: [],
-        sessionDirectory,
-        sessionFile,
-      },
-      null,
-      2,
-    )}\n`,
-    "utf8",
-  );
-  return {
-    role: "merger",
-    runId,
-    bookKey,
-    projectRoot,
-    instruction: options.instruction,
-    instructionEmpty: false,
-    attachments: [],
-    runDirectory,
-    principal,
-    admittedRequestPath,
-    mergerInputPath,
-    derived: emptyDerived,
-  };
-}
-
 function mergerTurnOptions(
   admitted: AdmittedMergerInvocation,
   env: MergerRunEnv,
@@ -263,33 +179,6 @@ export async function runPublicMerger(
       presentStructuralRejection(error, io);
       return { exitCode: 2 };
     }
-    if (error instanceof MergerEnvelopeDerivationError) {
-      const shell = await admitMergerShellForActivationFailure({
-        home: env.home,
-        principalAuthority: env.principalAuthority,
-        cwd: env.cwd,
-        instruction: parsed.instruction,
-        ...(parsed.project === undefined ? {} : { project: parsed.project }),
-        ...(env.createRunId === undefined
-          ? {}
-          : { createRunId: env.createRunId }),
-      });
-      await markRunAdmitted(shell, env.principalAuthority);
-      return (await presentControlledFailure(
-        shell,
-        {
-          timedOut: false,
-          code: null,
-          stderr: "",
-          thrown: error,
-          knownCause: "activation",
-          knownDiagnostic: error.message,
-        },
-        mergerAdapters(env.packageRoot),
-        env.principalAuthority,
-        io,
-      )) as { exitCode: number; admitted: AdmittedMergerInvocation; terminal: TerminalResult };
-    }
     throw error;
   }
 

package/src/public-cli/option-definitions.ts

@@ -670,7 +670,7 @@ const NOTARY_OPTIONS = [
 ] as const satisfies readonly PublicOptionDefinition[];
 
 const MERGER_OPTIONS = [
-  // Merger project face differs: requires an in-progress ordinary merge root.
+  // Merger project face: worktree whose Git materials are handed to the role.
   {
     id: "project",
     owner: "merger",
@@ -681,8 +681,8 @@ const MERGER_OPTIONS = [
     repeatable: false,
     form: "option",
     description: {
-      en: "Project root with one ordinary in-progress merge (defaults to cwd).",
-      zh: "已有进行中 ordinary merge 的项目根（默认 cwd）。",
+      en: "Project root whose Git merge materials are read (defaults to cwd).",
+      zh: "读取 Git merge 材料的项目根（默认 cwd）。",
     },
   },
   bindOwner("merger", SHARED_ATTACH_SEMANTICS),
@@ -1231,10 +1231,10 @@ const ROLE_COMMAND_HELP = {
   },
   merger: {
     command: "merger",
-    summary: "Resolve one ordinary merge already in conflict.",
+    summary: "Reconcile merge materials in a worktree (escalate when nothing to merge).",
     usage: ["ak-role merger [options] <instruction>"],
     examples: [
-      'ak-role merger --project /path/to/worktree "Reconcile the active merge."',
+      'ak-role merger --project /path/to/worktree "Reconcile the merge."',
     ],
   },
   inspector: {

package/src/public-cli/run-lifecycle.ts

@@ -1386,7 +1386,6 @@ async function loadResumableRunRecord(
         if (
           typeof d.targetObjectId === "string" &&
           typeof d.sourceObjectId === "string" &&
-          typeof d.automaticMergeTreeId === "string" &&
           Array.isArray(d.expectedConflictPaths) &&
           Array.isArray(d.resolutionScope) &&
           d.expectedConflictPaths.every((p) => typeof p === "string") &&
@@ -1395,7 +1394,6 @@ async function loadResumableRunRecord(
           derived = {
             targetObjectId: d.targetObjectId,
             sourceObjectId: d.sourceObjectId,
-            automaticMergeTreeId: d.automaticMergeTreeId,
             expectedConflictPaths: d.expectedConflictPaths as string[],
             resolutionScope: d.resolutionScope as string[],
           };

package/src/role-runtime-dependencies.ts

@@ -5,7 +5,6 @@ import { loadCanonicalSkillBinding as loadHomeCanonicalSkillBinding } from "./ca
 import { createGhCollectorGitHubTransport, createGhIssueSoftFetcher } from "./collector-github.ts";
 import { createPiDoctorAuditor } from "./doctor-auditor.ts";
 import { loadDoctorCase } from "./doctor-evidence.ts";
-import { createProductionMergerGitState } from "./merger-git-state.ts";
 import { createNativeNavigatorSessionFactory, createNavigatorAttendance } from "./navigator-attendance.ts";
 import { loadNavigatorWorkContext } from "./navigator-work-context.ts";
 import { loadNotarySourceRunLocator } from "./notary-source-run.ts";
@@ -53,7 +52,6 @@ export function createRoleRuntimeDependencies(packageRoot: string): RoleRuntimeD
     loadNotarySourceRun: loadNotarySourceRunLocator,
     loadMergerSoul: () => loadMainRoleSessionMaterials("merger"),
     loadMergerInput: async (path) => JSON.parse(await readFile(path, "utf8")),
-    createMergerGitState: (repositoryRoot) => createProductionMergerGitState(repositoryRoot),
     async loadCanonicalSkillBinding(name) {
       if (name === "tdd") {
         return loadPackagedCanonicalSkillBinding(packageRoot, "tdd");

package/src/role-runtime.ts

@@ -423,7 +423,7 @@ export { MERGER_INPUT_FLAG, createMergerRoleRuntime } from "./merger-role.ts";
 export { MERGER_OUTPUT_TOOL_NAME, mergerInputSchema, mergerOutputSchema, validateMergerInput, validateMergerOutput } from "./merger-contracts.ts";
 export type { MergerInput, MergerMaterial, MergerOutput } from "./merger-contracts.ts";
 export { createProductionMergerGitState } from "./merger-git-state.ts";
-export type { MergerGitState, ActiveMergerGitState, CompletedMergerGitState } from "./merger-git-state.ts";
+export type { MergerGitState, ActiveMergerGitState } from "./merger-git-state.ts";
 export type { MergerRoleDependencies } from "./merger-role.ts";
 
 type WorkerArmable = {
@@ -627,8 +627,6 @@ export type RoleRuntimeDependencies = {
   loadDoctorCase?(path: string): Promise<import("./doctor-contracts.ts").DoctorCase>;
   loadMergerSoul?(): Promise<string>;
   loadMergerInput?(path: string): Promise<unknown>;
-  mergerGitState?: MergerRoleDependencies["gitState"];
-  createMergerGitState?(repositoryRoot: string): MergerRoleDependencies["gitState"];
   auditDoctorCompliance?(options: { context: HostContext; signal?: AbortSignal }): Promise<ComplianceDecision>;
   createCollectorClock?(): CollectorClock;
   createNavigatorAttendance?(options: { context: HostContext; role: string; phase: NavigatorPhase; subjectKey: string; subject: string; authority: string; contextError?: unknown; invocationId: string; onEvent: (event: import("./navigator-attendance.ts").NavigatorEvent, report: import("./navigator-attendance.ts").NavigatorReport) => void | Promise<void> }): NavigatorAttendanceDependency | Promise<NavigatorAttendanceDependency>;
@@ -1682,15 +1680,10 @@ export function createRoleRuntimeExtension(
         },
       },
     );
-    let sessionMergerGitState = dependencies.mergerGitState;
     const merger = createMergerRoleRuntime(roleHost, {
       async loadSoul() { if (!dependencies.loadMergerSoul) throw new Error("Merger runtime dependencies are not configured"); return dependencies.loadMergerSoul(); },
       async loadInput(path) { if (!dependencies.loadMergerInput) throw new Error("Merger runtime dependencies are not configured"); return dependencies.loadMergerInput(path); },
-      gitState: {
-        activeMerge() { if (!sessionMergerGitState) throw new Error("Merger runtime dependencies are not configured"); return sessionMergerGitState.activeMerge(); },
-        completedMerge(mergeCommitId, automaticMergeTreeId) { if (!sessionMergerGitState) throw new Error("Merger runtime dependencies are not configured"); return sessionMergerGitState.completedMerge(mergeCommitId, automaticMergeTreeId); },
-      },
-    }, hostActions);
+    });
     // #676 E: shared envelope owns collector lifecycle (mode/fork, tool surface,
     // event gates). Role module supplies business activate/tools/materials only.
     let activeCollector: CollectorActivation | undefined;
@@ -1997,10 +1990,6 @@ export function createRoleRuntimeExtension(
         auditor,
         diarist,
         merger: async () => {
-          if (dependencies.mergerGitState === undefined) {
-            sessionMergerGitState = dependencies.createMergerGitState?.(ctx.cwd);
-          }
-          if (sessionMergerGitState === undefined) throw new Error("Merger runtime dependencies are not configured");
           await merger.activate();
         },
       };