@akagilnc/pi-workflow-roles 0.1.5037 → 0.1.5066

package/dist/host-descriptions.js

@@ -41,9 +41,8 @@ export const HOST_DESCRIPTIONS = Object.freeze({
  * Headless CLI family (#645 / #646). Claude print-mode is the first row;
  * codex exec (#646) adds another. Protocol-specific argv/parse live in
  * headless-host helpers (#752 per-host impl).
- * Claude fixedArgs: print mode, full permissions. stream-json + verbose: live
- * host events for sitian records (#811); result is last line. Forced methods
- * ride `--plugin-dir` (#922); operator skill/setting surfaces stay open.
+ * Claude fixedArgs: print mode. stream-json + verbose: live
+ * host events for sitian records (#811); result is last line.
  */
 export const HEADLESS_HOST_DESCRIPTIONS = Object.freeze({
     "claude": Object.freeze({

package/dist/migrate-book-topology.js

@@ -14051,8 +14051,7 @@ var init_packaged_role_registry = __esm({
             { key: "packetPath" },
             { key: "prerequisitesPath", omitUndefined: true },
             { key: "prerequisites" }
-          ],
-          method: "observed"
+          ]
         },
         boardPlacement: "marshal",
         activationFlags: [
@@ -14078,7 +14077,6 @@ var init_packaged_role_registry = __esm({
         worker: true,
         applyMethod: "tdd",
         /** Method-material load failure keeps the activation cause (not reviewer/fixer). */
-        methodLoadFailureCause: "activation",
         boardPlacement: "coder",
         phases: ["plan", "apply"],
         outputTool: CODER_OUTPUT_TOOL_NAME,
@@ -14089,8 +14087,7 @@ var init_packaged_role_registry = __esm({
           leaves: [
             { key: "phase" },
             { key: "taskPath" }
-          ],
-          method: "optional"
+          ]
         },
         activationFlags: [
           { field: "taskPath", flag: "ak-coder-task", binds: "input" },
@@ -14131,8 +14128,7 @@ var init_packaged_role_registry = __esm({
             { key: "lens" },
             { key: "authorityRefs", copyArray: true },
             { key: "callerProvenance", callerProvenance: true }
-          ],
-          method: "observed"
+          ]
         },
         /** Frozen base/lens/authority become the initial prompt; instruction follows. */
         transportPrompt: "skill-args",
@@ -14231,7 +14227,6 @@ var init_packaged_role_registry = __esm({
         methodSkills: ["resolving-merge-conflicts"],
         settleMethod: "resolving-merge-conflicts",
         /** Method-material load failure keeps the activation cause (not reviewer/fixer). */
-        methodLoadFailureCause: "activation",
         phases: [null],
         outputTool: MERGER_OUTPUT_TOOL_NAME,
         settlement: "residual",
@@ -14243,8 +14238,7 @@ var init_packaged_role_registry = __esm({
           leaves: [
             { key: "mergerInputPath" },
             { key: "derived" }
-          ],
-          method: "observed"
+          ]
         },
         activationFlags: [
           { field: "inputPath", from: "mergerInputPath", flag: "ak-merger-input", binds: "input" }

package/dist/packaged-role-registry.js

@@ -93,8 +93,7 @@ const PUBLIC_ROLE_RECORDS = [
         { key: "packetPath" },
         { key: "prerequisitesPath", omitUndefined: true },
         { key: "prerequisites" }
-      ],
-      method: "observed"
+      ]
     },
     boardPlacement: "marshal",
     activationFlags: [
@@ -120,7 +119,6 @@ const PUBLIC_ROLE_RECORDS = [
     worker: true,
     applyMethod: "tdd",
     /** Method-material load failure keeps the activation cause (not reviewer/fixer). */
-    methodLoadFailureCause: "activation",
     boardPlacement: "coder",
     phases: ["plan", "apply"],
     outputTool: CODER_OUTPUT_TOOL_NAME,
@@ -131,8 +129,7 @@ const PUBLIC_ROLE_RECORDS = [
       leaves: [
         { key: "phase" },
         { key: "taskPath" }
-      ],
-      method: "optional"
+      ]
     },
     activationFlags: [
       { field: "taskPath", flag: "ak-coder-task", binds: "input" },
@@ -173,8 +170,7 @@ const PUBLIC_ROLE_RECORDS = [
         { key: "lens" },
         { key: "authorityRefs", copyArray: true },
         { key: "callerProvenance", callerProvenance: true }
-      ],
-      method: "observed"
+      ]
     },
     /** Frozen base/lens/authority become the initial prompt; instruction follows. */
     transportPrompt: "skill-args",
@@ -273,7 +269,6 @@ const PUBLIC_ROLE_RECORDS = [
     methodSkills: ["resolving-merge-conflicts"],
     settleMethod: "resolving-merge-conflicts",
     /** Method-material load failure keeps the activation cause (not reviewer/fixer). */
-    methodLoadFailureCause: "activation",
     phases: [null],
     outputTool: MERGER_OUTPUT_TOOL_NAME,
     settlement: "residual",
@@ -285,8 +280,7 @@ const PUBLIC_ROLE_RECORDS = [
       leaves: [
         { key: "mergerInputPath" },
         { key: "derived" }
-      ],
-      method: "observed"
+      ]
     },
     activationFlags: [
       { field: "inputPath", from: "mergerInputPath", flag: "ak-merger-input", binds: "input" }
@@ -526,6 +520,18 @@ const PACKAGED_ROLE_REGISTRY = PUBLIC_ROLE_RECORDS.map(({ sessionMaterials: _omi
 function packagedRoleMetadata(role) {
   return PACKAGED_ROLE_REGISTRY.find((entry) => entry.role === role);
 }
+function packagedMethodSkillNames() {
+  const names = [];
+  for (const record of PACKAGED_ROLE_REGISTRY) {
+    if ("methodSkills" in record && record.methodSkills !== void 0) {
+      for (const name of record.methodSkills) if (!names.includes(name)) names.push(name);
+    }
+    if ("applyMethod" in record && record.applyMethod !== void 0 && !names.includes(record.applyMethod)) {
+      names.push(record.applyMethod);
+    }
+  }
+  return names;
+}
 function isOfficerReviewSeat(role) {
   const record = packagedRoleMetadata(role);
   return record !== void 0 && "reviewOfficer" in record && record.reviewOfficer === true;
@@ -560,11 +566,6 @@ function packagedRolePhaseFlag(role) {
 function packagedRoleOutputTool(role) {
   return packagedRoleMetadata(role)?.outputTool;
 }
-function packagedMethodLoadFailureCause(role) {
-  const record = packagedRoleMetadata(role);
-  if (record === void 0 || !("methodLoadFailureCause" in record)) return void 0;
-  return record.methodLoadFailureCause;
-}
 function packagedBindsBoardTicket(role) {
   const record = packagedRoleMetadata(role);
   return record?.sameParent === "board-ticket";
@@ -690,7 +691,7 @@ export {
   packagedEmitsAuthorityRefs,
   packagedGateStageLabel,
   packagedGateSummon,
-  packagedMethodLoadFailureCause,
+  packagedMethodSkillNames,
   packagedModelParent,
   packagedNavigatorSubject,
   packagedProjectsTargetBindRejection,

package/dist/pi/role-turn-host.js

@@ -6,7 +6,7 @@
 import { execFile, spawn } from "node:child_process";
 import { constants } from "node:fs";
 import { access, appendFile, readFile, realpath } from "node:fs/promises";
-import { basename, delimiter, dirname, isAbsolute, join, resolve } from "node:path";
+import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
 import { platform } from "node:process";
 import { promisify } from "node:util";
 import { randomUUID } from "node:crypto";
@@ -67,33 +67,11 @@ function buildMethodArgs(methods) {
     const skillArgs = [];
     for (const method of methods) {
         if (method.kind === "skill") {
-            skillArgs.push("--skill", method.path);
+            skillArgs.push("--skill", dirname(method.path));
         }
     }
     return skillArgs;
 }
-/**
- * Pi-native `/skill:<name>` for a single forced method (ADR 0082: pi is one adapter
- * with no privilege; Pi-only seams stay inside the pi adapter).
- * Driven by typed RoleTurnRequest.methods — middle-layer decision, Pi-only syntax.
- * Zero/many methods leave the prompt alone (Fixer optional pair stays `--skill` only).
- */
-export function applyPiNativeSkillInvocation(methods, prompt) {
-    const skills = methods.filter((method) => method.kind === "skill");
-    if (skills.length !== 1)
-        return prompt;
-    const name = basename(dirname(skills[0].path));
-    if (name.length === 0)
-        return prompt;
-    const token = `/skill:${name}`;
-    const trimmed = prompt.trimStart();
-    if (trimmed === token
-        || trimmed.startsWith(`${token} `)
-        || trimmed.startsWith(`${token}\n`)) {
-        return prompt;
-    }
-    return prompt.length === 0 ? token : `${token} ${prompt}`;
-}
 /**
  * Pi last-hop argv after `--no-extensions -e entry` (#819).
  * Activation flag membership comes from middle-layer projectActivationFlags;
@@ -135,9 +113,7 @@ function piUserDialogueBody(request) {
             const _exhaustive = request.continuation;
             return _exhaustive;
         })();
-    return request.continuation.kind === "resume"
-        ? rawPrompt
-        : applyPiNativeSkillInvocation(request.methods, rawPrompt);
+    return rawPrompt;
 }
 const execFileAsync = promisify(execFile);
 async function resolveSelectedPi(command, cwd, env) {

package/dist/public-cli/cli.js

@@ -12,6 +12,7 @@ import { loadHostProvidersTable, projectHostFacingProvider, renderHostProvidersT
 import { packagedModelParent } from "../packaged-role-registry.js";
 import { seatModelOnly } from "./registry.js";
 import { CliUsageError } from "./cli-errors.js";
+import { runMachineSkillSetup } from "./machine-method-skills.js";
 import { appendPiSessionCustomEntry } from "../pi/role-turn-host.js";
 import { composeRoleTurnHostAdapters, formatHostSelectionFailure, HostSelectionError, selectRoleTurnHost, } from "./role-turn-host-resolution.js";
 import { parseAnalystArgv, parsePublicSeatArgv, } from "./invocation.js";
@@ -793,6 +794,11 @@ export async function runAkRole(argv, env) {
                 exitCode: await runConfigCommand(parsed.args, home, env.packageRoot, io),
             };
         }
+        if (parsed.command === "setup") {
+            if (parsed.args.length !== 0)
+                throw new CliUsageError("setup takes no arguments");
+            return { exitCode: await runMachineSkillSetup(home, io.stdout) };
+        }
         // #724 explicit fresh summons: `ak-role new <role> …` — same role argv, always mint.
         // Rewrites onto the role command with freshSummons; auto-resume and resume stay intact.
         if (parsed.command === "new") {

package/dist/public-cli/instruction-seat-run.js

@@ -8,17 +8,17 @@ import { resolve, sep } from "node:path";
 import { isSafePositiveTicketNumber, readBoardTicketNumber } from "../run-ticket-number.js";
 import { NotarySourceRunError, resolveNotarySourceRunLocator } from "../notary-source-run.js";
 import { engineSessionMaterialFromOptions, pickEngineAxis } from "../package-resources/engine-material.js";
-import { loadPackagedMethodSkillMaterial, } from "../package-resources/method-skill.js";
-import { packagedAdmitsCountersign, packagedBindsBoardTicket, packagedMethodLoadFailureCause, packagedRebindSourceOnResume, packagedRoleMetadata, } from "../packaged-role-registry.js";
+import { packagedAdmitsCountersign, packagedBindsBoardTicket, packagedRebindSourceOnResume, packagedRoleMetadata, } from "../packaged-role-registry.js";
 import { isAuditorSoulRole } from "../auditor-soul.js";
 import { CliUsageError } from "./cli-errors.js";
 import { admitPublicRole, bindAdmittedTicketNumber, bindCourtTicketNumbersOnAdmitted, buildInstructionTransportPrompt, materializeCountersignInvocation, persistAdmittedSourceRunPath, recordAdmittedCorrelation, recordChildDiaristRun, relocateAdmittedRunToTicket, withPreparedAttachments, } from "./invocation.js";
-import { presentControlledFailure, prepareSummonsResumeMaterials, resolveResumeMethodMaterialAdapters, roleTurnOptions, runPostAdmissionOneShot, runPostAdmissionResumable, runPostAdmissionSeatResume, resumeTurnRequestProjectionOptions, } from "./post-admission.js";
+import { presentControlledFailure, prepareSummonsResumeMaterials, roleTurnOptions, runPostAdmissionOneShot, runPostAdmissionResumable, runPostAdmissionSeatResume, resumeTurnRequestProjectionOptions, } from "./post-admission.js";
 import { buildAutoResumeContinuationPrompt, loadResumablePublicRole, markRunAdmitted, parentRunPathFromGatePointerInstruction, } from "./run-lifecycle.js";
 import { tryResumeSameTicketSeatRun } from "./seat-ticket-binding.js";
 import { presentStructuralRejection, seatKnownFailureResolver, trySettlePublicSeat, } from "./settlement.js";
+import { warnMissingMethodSkills } from "./machine-method-skills.js";
 import { formatTerminalResult, isLawfulTypedTerminalOutcome, } from "./terminal.js";
-import { admittedSeatTurnDetails, packagedSettleSkill, projectRoleTurnRequest, } from "./turn-request.js";
+import { admittedSeatTurnDetails, projectRoleTurnRequest, requiredMethodSkills, } from "./turn-request.js";
 import { invokeCourtDiarist, runCountersignCourtDiaristStation, } from "./countersign-run.js";
 function roleRecord(role) {
     const record = packagedRoleMetadata(role);
@@ -29,7 +29,7 @@ function roleRecord(role) {
 }
 /** Project any admitted public role onto the host-neutral turn request. */
 export function buildInstructionSeatTurnRequest(admitted, options) {
-    return projectRoleTurnRequest(admitted, admittedSeatTurnDetails(admitted, options.packageRoot), options);
+    return projectRoleTurnRequest(admitted, admittedSeatTurnDetails(admitted, options.home, options.host), options);
 }
 function initialPrompt(admitted, env) {
     const record = roleRecord(admitted.role);
@@ -58,11 +58,11 @@ async function bindAndRelocateDiarist(admitted, authority, lease) {
     }
     await relocateAdmittedRunToTicket(admitted, authority, lease);
 }
-function seatAdapters(admitted, env, material) {
+function seatAdapters(admitted, env) {
     const record = roleRecord(admitted.role);
     const present = "presentSettled" in record ? record.presentSettled : "default";
     return {
-        trySettle: (seat, authority, scope) => trySettlePublicSeat(seat, authority, scope, material, env.packageRoot),
+        trySettle: (seat, authority, scope) => trySettlePublicSeat(seat, authority, scope),
         ...(present === "always" ? { shouldPresentSettled: () => true } : {}),
         ...(present === "typed"
             ? { shouldPresentSettled: (terminal) => isLawfulTypedTerminalOutcome(terminal.roleOutcome) }
@@ -126,24 +126,8 @@ async function withAuditorSoulEnv(options) {
 }
 async function dispatchAdmitted(admitted, env, io) {
     const record = roleRecord(admitted.role);
-    let material;
-    const skill = packagedSettleSkill(admitted);
-    if (skill !== undefined) {
-        try {
-            material = await loadPackagedMethodSkillMaterial(env.packageRoot, skill);
-        }
-        catch (error) {
-            const knownCause = packagedMethodLoadFailureCause(admitted.role);
-            return await presentControlledFailure(admitted, {
-                timedOut: false,
-                code: null,
-                stderr: "",
-                thrown: error,
-                ...(knownCause === undefined ? {} : { knownCause }),
-            }, seatAdapters(admitted, env), env.principalAuthority, io);
-        }
-    }
-    const adapters = seatAdapters(admitted, env, material);
+    await warnMissingMethodSkills(env.home, env.host, admitted.role, requiredMethodSkills(admitted), io.stdout);
+    const adapters = seatAdapters(admitted, env);
     const execute = async (activeEnv) => {
         const auto = "inCallAutoResume" in record && record.inCallAutoResume === true;
         if (auto) {
@@ -650,21 +634,9 @@ export async function runPublicInstructionSeatResume(request, env, io) {
         adapters: {
             trySettle: async () => undefined,
         },
-        afterAdmittedLoad: (admitted) => {
-            const skill = packagedSettleSkill(admitted);
-            if (skill === undefined) {
-                return Promise.resolve({ kind: "continue", adapters: seatAdapters(admitted, env) });
-            }
-            const knownCause = packagedMethodLoadFailureCause(admitted.role);
-            return resolveResumeMethodMaterialAdapters({
-                admitted,
-                authority: env.principalAuthority,
-                io,
-                loadMaterial: () => loadPackagedMethodSkillMaterial(env.packageRoot, skill),
-                adaptersWith: (material) => seatAdapters(admitted, env, material),
-                emptyAdapters: seatAdapters(admitted, env),
-                ...(knownCause === undefined ? {} : { knownCause }),
-            });
+        afterAdmittedLoad: async (admitted) => {
+            await warnMissingMethodSkills(env.home, env.host, admitted.role, requiredMethodSkills(admitted), io.stdout);
+            return { kind: "continue", adapters: seatAdapters(admitted, env) };
         },
         ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
     });

package/dist/public-cli/machine-method-skills.js

@@ -0,0 +1,150 @@
+import { accessSync, constants, statSync } from "node:fs";
+import { lstat, mkdir, symlink } from "node:fs/promises";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { HEADLESS_HOST_DESCRIPTIONS, HOST_DESCRIPTIONS } from "../host-descriptions.js";
+import { packagedMethodSkillNames } from "../packaged-role-registry.js";
+/** Install source only. Which names are required comes from the role registry. */
+const SKILL_SOURCE = {
+    tdd: "mattpocock/skills",
+    "diagnosing-bugs": "mattpocock/skills",
+    "resolving-merge-conflicts": "mattpocock/skills",
+    "ak-cross-m-review": "Akagilnc/ak-cross-m-review",
+};
+function skillRoot(home) {
+    return join(home, ".agents/skills");
+}
+export function installedMethodSkillPath(home, name) {
+    return installedSkillPath(skillRoot(home), name);
+}
+function installedSkillPath(root, name) {
+    const path = join(root, name, "SKILL.md");
+    try {
+        if (!statSync(path).isFile())
+            return undefined;
+        accessSync(path, constants.R_OK);
+        return path;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ENOTDIR" || code === "EACCES" || code === "EPERM" || code === "ELOOP")
+            return undefined;
+        throw error;
+    }
+}
+function linkedSkillRoot(home, host) {
+    if (host === "claude" || host === "claude-code") {
+        return join(process.env.CLAUDE_CONFIG_DIR?.trim() || join(home, ".claude"), "skills");
+    }
+    if (host === "hermes")
+        return join(home, ".hermes/skills");
+    return undefined;
+}
+async function occupied(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        return false;
+    }
+}
+function warnOccupied(path, stdout) {
+    stdout(`Warning: ${path} is already occupied; left untouched.\n`);
+}
+export async function warnMissingMethodSkills(home, host, role, skills, stdout) {
+    const missing = [];
+    const linkedRoot = linkedSkillRoot(home, host);
+    for (const skill of skills) {
+        if (installedMethodSkillPath(home, skill) === undefined ||
+            (linkedRoot !== undefined && installedSkillPath(linkedRoot, skill) === undefined))
+            missing.push(skill);
+    }
+    for (const skill of missing) {
+        stdout(`Warning: required machine Skill "${skill}" is missing for ${role}; its method guidance may be unavailable and reduce work quality. Run \`ak-role setup\` to install required Skills.\n`);
+    }
+}
+function runSkillsCli(args, home) {
+    const result = spawnSync("npx", ["--yes", "skills", ...args], {
+        stdio: "inherit",
+        env: { ...process.env, HOME: home },
+    });
+    if (result.error !== undefined)
+        throw result.error;
+    return result.status === 0;
+}
+function addSkills(source, skills, home) {
+    if (skills.length === 0)
+        return true;
+    return runSkillsCli([
+        "add", source,
+        ...skills.flatMap((skill) => ["--skill", skill]),
+        "--agent", "codex", "--global", "--yes",
+    ], home);
+}
+function updateRequiredSkills(home) {
+    const names = packagedMethodSkillNames();
+    if (names.length === 0)
+        return true;
+    return runSkillsCli(["update", "-g", "-y", ...names], home);
+}
+/** Explicit user-run setup; delegates acquisition/install to the ecosystem Skills CLI. */
+export async function runMachineSkillSetup(home, stdout) {
+    const canonical = skillRoot(home);
+    const missingBySource = new Map();
+    let unsourced = false;
+    for (const name of packagedMethodSkillNames()) {
+        const path = join(canonical, name);
+        if (await occupied(path)) {
+            warnOccupied(path, stdout);
+            continue;
+        }
+        const source = SKILL_SOURCE[name];
+        if (source === undefined) {
+            unsourced = true;
+            stdout(`Warning: required machine Skill "${name}" has no install source; setup did not install it.\n`);
+            continue;
+        }
+        const missing = missingBySource.get(source) ?? [];
+        missing.push(name);
+        missingBySource.set(source, missing);
+    }
+    for (const [source, missing] of missingBySource) {
+        if (!addSkills(source, missing, home))
+            return 1;
+    }
+    if (unsourced)
+        return 1;
+    for (const host of ["claude-code", "hermes"]) {
+        const root = linkedSkillRoot(home, host);
+        const binaryFromHome = host === "claude-code"
+            ? HEADLESS_HOST_DESCRIPTIONS.claude.binaryFromHome
+            : HOST_DESCRIPTIONS.hermes.binaryFromHome;
+        try {
+            accessSync(join(home, ...binaryFromHome), constants.X_OK);
+        }
+        catch (error) {
+            if (["ENOENT", "ENOTDIR", "EACCES"].includes(error.code ?? ""))
+                continue;
+            throw error;
+        }
+        for (const name of packagedMethodSkillNames()) {
+            const target = join(canonical, name);
+            if (installedMethodSkillPath(home, name) === undefined)
+                continue;
+            const link = join(root, name);
+            if (await occupied(link)) {
+                warnOccupied(link, stdout);
+                continue;
+            }
+            await mkdir(root, { recursive: true });
+            await symlink(target, link, "dir");
+        }
+    }
+    if (!updateRequiredSkills(home))
+        return 1;
+    stdout("Machine method Skills setup finished. Existing same-name Skills were left untouched.\n");
+    return 0;
+}