@akagilnc/pi-workflow-roles 0.1.1751

package/src/package-resources/method-skill-binding.ts

@@ -0,0 +1,87 @@
+/**
+ * Canonical Skill binding built from package-owned method material.
+ * Lives beside the method seam but may import Pi skill parsers — used by the
+ * Internal role runtime, not the public ak-role bin bundle.
+ */
+import { dirname } from "node:path";
+
+import { parseSkillBlock } from "@earendil-works/pi-coding-agent";
+
+import {
+  type CanonicalSkillBinding,
+  type CanonicalSkillEvidence,
+  type CanonicalSkillName,
+} from "../canonical-skill-binding.ts";
+import {
+  loadPackagedMethodSkillMaterial,
+  resolvePackagedMethodSkillPath,
+  type PackagedMethodSkillName,
+} from "./method-skill.ts";
+
+type PackagedCanonicalSkillName = Extract<
+  PackagedMethodSkillName,
+  CanonicalSkillName
+>;
+
+/**
+ * Build a CanonicalSkillBinding from package-owned material.
+ * captureExpansion accepts the package skill path (configured or realpath).
+ */
+export async function loadPackagedCanonicalSkillBinding<
+  Name extends PackagedCanonicalSkillName,
+>(
+  packageRoot: string,
+  name: Name,
+): Promise<CanonicalSkillBinding<Name>> {
+  // Forced expansion bindings are only defined for canonical completion-gated skills.
+  // Optional Fixer diagnosing-bugs stays available via --skill without this binding.
+  const material = await loadPackagedMethodSkillMaterial(packageRoot, name);
+  const configuredPath = resolvePackagedMethodSkillPath(packageRoot, name);
+  const snapshot = Object.freeze({
+    raw: material.raw,
+    path: material.skillPath,
+    baseDir: dirname(material.skillPath),
+    body: material.body,
+    snapshotIdentity: Object.freeze({ text: material.raw }),
+  });
+
+  const binding: CanonicalSkillBinding<Name> = {
+    name,
+    snapshot,
+    invocation(originalRequest) {
+      return `/skill:${name} ${originalRequest}`;
+    },
+    captureExpansion(
+      prompt,
+      originalRequest,
+    ): CanonicalSkillEvidence<Name> | undefined {
+      const parsed = parseSkillBlock(prompt);
+      const matchedPath =
+        parsed?.location === configuredPath
+          ? configuredPath
+          : parsed?.location === snapshot.path
+            ? snapshot.path
+            : undefined;
+      const expectedContent =
+        matchedPath === undefined
+          ? undefined
+          : `References are relative to ${dirname(matchedPath)}.\n\n${snapshot.body}`;
+      const userMessage = parsed?.userMessage ?? "";
+      if (
+        parsed?.name !== name ||
+        matchedPath === undefined ||
+        parsed.content !== expectedContent ||
+        userMessage !== originalRequest
+      ) {
+        return undefined;
+      }
+      return Object.freeze({
+        name,
+        location: parsed.location,
+        content: parsed.content,
+        userMessage,
+      });
+    },
+  };
+  return Object.freeze(binding);
+}

package/src/package-resources/method-skill.ts

@@ -0,0 +1,358 @@
+/**
+ * Package-owned role method Skill seam (ADR 0052 / #109).
+ * Forced methods load from the installed package copy — never ambient home discovery.
+ *
+ * This module is intentionally free of @earendil-works/pi-coding-agent so the
+ * public ak-role bin can load provenance/path without bundling peer runtime.
+ */
+import { createHash } from "node:crypto";
+import { readFile, realpath } from "node:fs/promises";
+import { join } from "node:path";
+
+import { sha256Hex } from "../sha256.ts";
+
+/** Package-side unavailable method Skill (mirrors CanonicalSkillUnavailableError identity). */
+export class PackagedMethodSkillUnavailableError extends Error {
+  readonly code = "canonical-skill-unavailable" as const;
+  constructor(
+    readonly skillName: PackagedMethodSkillName,
+    path: string,
+    cause: unknown,
+  ) {
+    super(`Canonical ${skillName} Skill is unavailable at ${path}`, { cause });
+    this.name = "CanonicalSkillUnavailableError";
+  }
+}
+
+/** Method Skill names shipped as package resources under resources/methods/. */
+export type PackagedMethodSkillName =
+  | "tdd"
+  | "diagnosing-bugs"
+  | "code-review"
+  | "resolving-merge-conflicts";
+
+export type PackagedMethodFileProvenance = Readonly<{
+  sha256: string;
+  byteLength: number;
+  /** Independent upstream git blob OID (sha1) for the exact file bytes. */
+  gitBlob: string;
+}>;
+
+export type PackagedMethodUpstreamProvenance = Readonly<{
+  repository: string;
+  path: string;
+  /** Immutable upstream commit (full lowercase git object id). */
+  commit: string;
+  /** Immutable upstream release tag when the snapshot is tag-addressable. */
+  tag?: string;
+  /** Immutable upstream version label when no single tag is the pin. */
+  version?: string;
+  license: string;
+  copyright: string;
+  attribution: string;
+}>;
+
+/** Exact upstream provenance + per-file digests recorded beside the skill body. */
+export type PackagedMethodSkillProvenance = Readonly<{
+  name: PackagedMethodSkillName;
+  kind: "role-method-skill";
+  upstream: PackagedMethodUpstreamProvenance;
+  packageAdaptation: string;
+  files: Readonly<Record<string, PackagedMethodFileProvenance>>;
+}>;
+
+export type PackagedMethodSkillMaterial = Readonly<{
+  name: PackagedMethodSkillName;
+  /** Absolute directory containing SKILL.md and companions. */
+  rootDirectory: string;
+  /** Absolute SKILL.md path (pass to Pi `--skill`). */
+  skillPath: string;
+  raw: string;
+  body: string;
+  provenance: PackagedMethodSkillProvenance;
+  /** Companion relative paths present beside SKILL.md (tests/mocking/...). */
+  companionRelativePaths: readonly string[];
+}>;
+
+const METHOD_SKILL_RELATIVE_ROOT = "resources/methods" as const;
+const GIT_COMMIT_RE = /^[0-9a-f]{40}$/;
+const GIT_BLOB_RE = /^[0-9a-f]{40}$/;
+const SHA256_RE = /^[0-9a-f]{64}$/;
+
+const REQUIRED_COMPANIONS: Readonly<
+  Record<PackagedMethodSkillName, readonly string[]>
+> = {
+  tdd: ["tests.md", "mocking.md", "agents/openai.yaml"],
+  "diagnosing-bugs": ["agents/openai.yaml", "scripts/hitl-loop.template.sh"],
+  "code-review": ["agents/openai.yaml"],
+  "resolving-merge-conflicts": ["agents/openai.yaml"],
+};
+
+/** Git blob OID for raw file bytes (sha1 of `blob <size>\\0` + content). */
+export function gitBlobOid(bytes: string | Uint8Array): string {
+  const body =
+    typeof bytes === "string" ? Buffer.from(bytes, "utf8") : Buffer.from(bytes);
+  const header = Buffer.from(`blob ${body.byteLength}\0`, "utf8");
+  return createHash("sha1").update(header).update(body).digest("hex");
+}
+
+/** Minimal frontmatter strip — body after closing `---` fence (or full text). */
+export function stripSkillFrontmatter(content: string): string {
+  if (!content.startsWith("---")) return content;
+  const end = content.indexOf("\n---", 3);
+  if (end === -1) return content;
+  const after = content.slice(end + "\n---".length);
+  return after.replace(/^\r?\n/, "");
+}
+
+export function packagedMethodSkillRelativeDirectory(
+  name: PackagedMethodSkillName,
+): string {
+  return `${METHOD_SKILL_RELATIVE_ROOT}/${name}`;
+}
+
+export function resolvePackagedMethodSkillRoot(
+  packageRoot: string,
+  name: PackagedMethodSkillName,
+): string {
+  return join(packageRoot, packagedMethodSkillRelativeDirectory(name));
+}
+
+export function resolvePackagedMethodSkillPath(
+  packageRoot: string,
+  name: PackagedMethodSkillName,
+): string {
+  return join(resolvePackagedMethodSkillRoot(packageRoot, name), "SKILL.md");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseProvenance(
+  raw: unknown,
+  expectedName: PackagedMethodSkillName,
+): PackagedMethodSkillProvenance {
+  if (!isRecord(raw)) {
+    throw new Error(`Packaged method provenance must be an object for ${expectedName}`);
+  }
+  if (raw.name !== expectedName) {
+    throw new Error(
+      `Packaged method provenance name mismatch: expected ${expectedName}, got ${String(raw.name)}`,
+    );
+  }
+  if (raw.kind !== "role-method-skill") {
+    throw new Error(`Packaged method provenance kind must be role-method-skill`);
+  }
+  if (typeof raw.packageAdaptation !== "string" || raw.packageAdaptation.trim() === "") {
+    throw new Error(`Packaged method provenance packageAdaptation must be nonblank`);
+  }
+  if (!isRecord(raw.upstream)) {
+    throw new Error(`Packaged method provenance upstream must be an object`);
+  }
+  const upstream = raw.upstream;
+  for (const key of [
+    "repository",
+    "path",
+    "license",
+    "copyright",
+    "attribution",
+  ] as const) {
+    if (typeof upstream[key] !== "string" || upstream[key].trim() === "") {
+      throw new Error(`Packaged method provenance upstream.${key} must be nonblank`);
+    }
+  }
+  if (typeof upstream.commit !== "string" || !GIT_COMMIT_RE.test(upstream.commit)) {
+    throw new Error(
+      `Packaged method provenance upstream.commit must be a 40-char lowercase git object id`,
+    );
+  }
+  const tag =
+    typeof upstream.tag === "string" && upstream.tag.trim() !== ""
+      ? upstream.tag.trim()
+      : undefined;
+  const version =
+    typeof upstream.version === "string" && upstream.version.trim() !== ""
+      ? upstream.version.trim()
+      : undefined;
+  if (tag === undefined && version === undefined) {
+    throw new Error(
+      `Packaged method provenance upstream must include nonblank tag or version`,
+    );
+  }
+  if (!isRecord(raw.files)) {
+    throw new Error(`Packaged method provenance files must be an object`);
+  }
+  const files: Record<string, PackagedMethodFileProvenance> = {};
+  for (const [rel, entry] of Object.entries(raw.files)) {
+    if (!isRecord(entry)) {
+      throw new Error(`Packaged method provenance file entry must be an object: ${rel}`);
+    }
+    if (typeof entry.sha256 !== "string" || !SHA256_RE.test(entry.sha256)) {
+      throw new Error(`Packaged method provenance file sha256 invalid: ${rel}`);
+    }
+    if (
+      typeof entry.byteLength !== "number" ||
+      !Number.isInteger(entry.byteLength) ||
+      entry.byteLength < 0
+    ) {
+      throw new Error(`Packaged method provenance file byteLength invalid: ${rel}`);
+    }
+    if (typeof entry.gitBlob !== "string" || !GIT_BLOB_RE.test(entry.gitBlob)) {
+      throw new Error(
+        `Packaged method provenance file gitBlob must be a 40-char lowercase git object id: ${rel}`,
+      );
+    }
+    files[rel] = {
+      sha256: entry.sha256,
+      byteLength: entry.byteLength,
+      gitBlob: entry.gitBlob,
+    };
+  }
+  if (files["SKILL.md"] === undefined) {
+    throw new Error(`Packaged method provenance must include SKILL.md`);
+  }
+  return Object.freeze({
+    name: expectedName,
+    kind: "role-method-skill",
+    packageAdaptation: raw.packageAdaptation,
+    upstream: Object.freeze({
+      repository: upstream.repository as string,
+      path: upstream.path as string,
+      commit: upstream.commit,
+      ...(tag === undefined ? {} : { tag }),
+      ...(version === undefined ? {} : { version }),
+      license: upstream.license as string,
+      copyright: upstream.copyright as string,
+      attribution: upstream.attribution as string,
+    }),
+    files: Object.freeze(files),
+  });
+}
+
+/**
+ * Load a package-owned method Skill and verify per-file provenance digests.
+ * Does not consult HOME or ambient Skill discovery paths.
+ */
+export async function loadPackagedMethodSkillMaterial(
+  packageRoot: string,
+  name: PackagedMethodSkillName,
+): Promise<PackagedMethodSkillMaterial> {
+  const rootDirectory = resolvePackagedMethodSkillRoot(packageRoot, name);
+  const skillPathConfigured = join(rootDirectory, "SKILL.md");
+  const provenancePath = join(rootDirectory, "provenance.json");
+
+  let provenanceRaw: string;
+  try {
+    provenanceRaw = await readFile(provenancePath, "utf8");
+  } catch (error) {
+    throw new PackagedMethodSkillUnavailableError(name, provenancePath, error);
+  }
+  let provenanceJson: unknown;
+  try {
+    provenanceJson = JSON.parse(provenanceRaw);
+  } catch (error) {
+    throw new Error(`Packaged method provenance is not valid JSON at ${provenancePath}`, {
+      cause: error,
+    });
+  }
+  const provenance = parseProvenance(provenanceJson, name);
+
+  // Verify every declared file digest + independent git blob against package bytes (no network).
+  for (const [rel, expected] of Object.entries(provenance.files)) {
+    const absolute = join(rootDirectory, rel);
+    let bytes: Buffer;
+    try {
+      bytes = await readFile(absolute);
+    } catch (error) {
+      throw new PackagedMethodSkillUnavailableError(name, absolute, error);
+    }
+    const actualSha = sha256Hex(bytes);
+    const actualBlob = gitBlobOid(bytes);
+    if (
+      actualSha !== expected.sha256 ||
+      bytes.byteLength !== expected.byteLength ||
+      actualBlob !== expected.gitBlob
+    ) {
+      throw new Error(
+        `Packaged method file digest mismatch for ${name}/${rel}: expected sha256=${expected.sha256} byteLength=${expected.byteLength} gitBlob=${expected.gitBlob}, got sha256=${actualSha} byteLength=${bytes.byteLength} gitBlob=${actualBlob}`,
+      );
+    }
+  }
+
+  let skillPath: string;
+  let raw: string;
+  try {
+    skillPath = await realpath(skillPathConfigured);
+    raw = await readFile(skillPath, "utf8");
+  } catch (error) {
+    throw new PackagedMethodSkillUnavailableError(name, skillPathConfigured, error);
+  }
+  const body = stripSkillFrontmatter(raw).trim();
+  if (body.length === 0) {
+    throw new Error(`Canonical ${name} Skill is empty at ${skillPath}`);
+  }
+
+  const companionRelativePaths = REQUIRED_COMPANIONS[name].filter(
+    (rel) => provenance.files[rel] !== undefined,
+  );
+  for (const rel of REQUIRED_COMPANIONS[name]) {
+    if (provenance.files[rel] === undefined) {
+      throw new Error(
+        `Packaged method ${name} missing required companion in provenance: ${rel}`,
+      );
+    }
+  }
+
+  return Object.freeze({
+    name,
+    rootDirectory,
+    skillPath,
+    raw,
+    body,
+    provenance,
+    companionRelativePaths: Object.freeze([...companionRelativePaths]),
+  });
+}
+
+/** Observed Pi-native method Skill expansion (structured skill block, not free prose). */
+export type ObservedPackagedMethodSkillInvocation = Readonly<{
+  name: PackagedMethodSkillName;
+  location: string;
+}>;
+
+/**
+ * Observe one Pi-native packaged method Skill expansion from a user-turn text.
+ * Matches the structured `<skill name location>` block format only; rejects ambient
+ * home locations that are not in the allowed package path set.
+ */
+export function observePackagedMethodSkillInvocation(
+  text: string,
+  expected: {
+    readonly name: PackagedMethodSkillName;
+    readonly allowedLocations: readonly string[];
+  },
+): ObservedPackagedMethodSkillInvocation | undefined {
+  // Structured skill-block grammar (same shape Pi expands); not free-text classification.
+  if (!text.startsWith("<skill name=\"")) return undefined;
+  const nameStart = "<skill name=\"".length;
+  const nameEnd = text.indexOf("\"", nameStart);
+  if (nameEnd <= nameStart) return undefined;
+  const name = text.slice(nameStart, nameEnd);
+  if (name !== expected.name) return undefined;
+  const locationMarker = "\" location=\"";
+  if (!text.startsWith(locationMarker, nameEnd)) return undefined;
+  const locationStart = nameEnd + locationMarker.length;
+  const locationEnd = text.indexOf("\"", locationStart);
+  if (locationEnd <= locationStart) return undefined;
+  const location = text.slice(locationStart, locationEnd);
+  const openTail = ">\n";
+  if (!text.startsWith(openTail, locationEnd + 1)) return undefined;
+  const closeTag = "\n</skill>";
+  const closeAt = text.indexOf(closeTag, locationEnd + 1 + openTail.length);
+  if (closeAt === -1) return undefined;
+  const afterClose = text.slice(closeAt + closeTag.length);
+  if (afterClose.length > 0 && !afterClose.startsWith("\n")) return undefined;
+  if (!expected.allowedLocations.includes(location)) return undefined;
+  return Object.freeze({ name: expected.name, location });
+}

package/src/packaged-role-registry.ts

@@ -0,0 +1,36 @@
+/** The single package-owned source for role attendance and settlement metadata. */
+import { COLLECTOR_OUTPUT_TOOL } from "./package-contracts/collector-output.ts";
+import { JUDGE_OUTPUT_TOOL_NAME } from "./package-contracts/judge-output.ts";
+import { REVIEWER_OUTPUT_TOOL_NAME } from "./package-contracts/reviewer-output.ts";
+import { CODER_OUTPUT_TOOL_NAME, FIXER_OUTPUT_TOOL_NAME } from "./package-contracts/worker-output.ts";
+import { DOCTOR_OUTPUT_TOOL_NAME } from "./doctor-contracts.ts";
+import { MERGER_OUTPUT_TOOL_NAME } from "./merger-contracts.ts";
+
+export const PACKAGED_ROLE_REGISTRY = [
+  { role: "judge", phases: [null], outputTool: JUDGE_OUTPUT_TOOL_NAME, inputFlag: undefined, phaseFlag: undefined, 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" },
+  { role: "coder", phases: ["plan", "apply"], outputTool: CODER_OUTPUT_TOOL_NAME, inputFlag: "ak-coder-task", phaseFlag: "ak-coder-phase", activationStage: "load-and-install" },
+  { role: "reviewer", phases: [null], outputTool: REVIEWER_OUTPUT_TOOL_NAME, inputFlag: undefined, phaseFlag: undefined, activationStage: "load-and-install" },
+  { role: "collector", phases: [null], outputTool: COLLECTOR_OUTPUT_TOOL, inputFlag: "ak-collector-repo", phaseFlag: undefined, activationStage: "load-and-install" },
+  { role: "doctor", phases: [null], outputTool: DOCTOR_OUTPUT_TOOL_NAME, inputFlag: "ak-doctor-case", phaseFlag: undefined, activationStage: "load-and-install" },
+  { role: "merger", phases: [null], outputTool: MERGER_OUTPUT_TOOL_NAME, inputFlag: "ak-merger-input", phaseFlag: undefined, activationStage: "prepare-git-and-install" },
+] as const;
+
+export type PackagedRole = (typeof PACKAGED_ROLE_REGISTRY)[number]["role"];
+export type PackagedRoleMetadata = (typeof PACKAGED_ROLE_REGISTRY)[number];
+
+export function packagedRoleMetadata(role: string): PackagedRoleMetadata | undefined {
+  return PACKAGED_ROLE_REGISTRY.find((entry) => entry.role === role);
+}
+
+export function packagedRoleInputFlag(role: string): string | undefined {
+  return packagedRoleMetadata(role)?.inputFlag;
+}
+
+export function packagedRolePhaseFlag(role: string): string | undefined {
+  return packagedRoleMetadata(role)?.phaseFlag;
+}
+
+export function packagedRoleOutputTool(role: string): string | undefined {
+  return packagedRoleMetadata(role)?.outputTool;
+}

package/src/public-cli/cli-errors.ts

@@ -0,0 +1,11 @@
+/** Shared public CLI usage error (structural reject before admission). */
+export class CliUsageError extends Error {
+  readonly code = "AK_ROLE_USAGE";
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(
+      message,
+      options?.cause === undefined ? undefined : { cause: options.cause },
+    );
+    this.name = "CliUsageError";
+  }
+}

package/src/public-cli/cli-io.ts

@@ -0,0 +1,4 @@
+export type CliIo = {
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+};