pi-crew 0.6.1 → 0.6.4

package/src/runtime/skill-instructions.ts

@@ -3,15 +3,24 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { AgentConfig } from "../agents/agent-config.ts";
 import type { TeamRole } from "../teams/team-config.ts";
+import {
+	isSafePathId,
+	resolveContainedPath,
+	resolveRealContainedPath,
+} from "../utils/safe-paths.ts";
 import type { WorkflowStep } from "../workflows/workflow-config.ts";
-import { isSafePathId, resolveContainedPath, resolveRealContainedPath } from "../utils/safe-paths.ts";
 import {
+	CONFIDENCE_THRESHOLDS,
 	getWeightedSkillsForRole,
 	registerSkillEffectivenessHooks,
-	CONFIDENCE_THRESHOLDS,
 } from "./skill-effectiveness.ts";
 
-const PACKAGE_SKILLS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
+const PACKAGE_SKILLS_DIR = path.resolve(
+	path.dirname(fileURLToPath(import.meta.url)),
+	"..",
+	"..",
+	"skills",
+);
 const MAX_SKILL_CHARS = 1500;
 const MAX_TOTAL_CHARS = 6000;
 const MAX_SKILL_NAME_CHARS = 80;
@@ -23,7 +32,11 @@ const DEFAULT_ROLE_SKILLS: Record<string, string[]> = {
 	analyst: ["read-only-explorer", "requirements-to-task-packet"],
 	planner: ["delegation-patterns", "requirements-to-task-packet"],
 	critic: ["read-only-explorer", "multi-perspective-review"],
-	executor: ["state-mutation-locking", "safe-bash", "verification-before-done"],
+	executor: [
+		"state-mutation-locking",
+		"safe-bash",
+		"verification-before-done",
+	],
 	reviewer: ["read-only-explorer", "multi-perspective-review"],
 	// SECURITY NOTE: The following skill names are trusted package-level skills.
 	// If a project has a skills/ directory containing subdirectories with these names,
@@ -31,7 +44,10 @@ const DEFAULT_ROLE_SKILLS: Record<string, string[]> = {
 	// project dir before package dir) and their content injected verbatim into prompts.
 	// The "Applicable Skills" block will add an untrusted-content warning for project skills,
 	// but be aware this is a potential supply-chain risk in multi-contributor projects.
-	"security-reviewer": ["secure-agent-orchestration-review", "ownership-session-security"],
+	"security-reviewer": [
+		"secure-agent-orchestration-review",
+		"ownership-session-security",
+	],
 	"test-engineer": ["verification-before-done", "safe-bash"],
 	verifier: ["verification-before-done", "runtime-state-reader"],
 	writer: ["context-artifact-hygiene", "verify-evidence"],
@@ -50,11 +66,18 @@ export interface RenderSkillInstructionsInput extends ResolveTaskSkillsInput {
 }
 
 function isValidSkillName(name: string): boolean {
-	return name.length > 0 && name.length <= MAX_SKILL_NAME_CHARS && isSafePathId(name);
+	return (
+		name.length > 0 &&
+		name.length <= MAX_SKILL_NAME_CHARS &&
+		isSafePathId(name)
+	);
 }
 
 function sanitizeSkillName(name: string): string {
-	return name.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, MAX_SKILL_NAME_CHARS) || "invalid";
+	return (
+		name.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, MAX_SKILL_NAME_CHARS) ||
+		"invalid"
+	);
 }
 
 function unique(items: string[]): string[] {
@@ -69,11 +92,18 @@ function unique(items: string[]): string[] {
 	return result;
 }
 
-export function normalizeSkillOverride(value: string | string[] | boolean | undefined): string[] | false | undefined {
+export function normalizeSkillOverride(
+	value: string | string[] | boolean | undefined,
+): string[] | false | undefined {
 	if (value === false) return false;
-	if (typeof value === "string") return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+	if (typeof value === "string")
+		return value
+			.split(",")
+			.map((entry) => entry.trim())
+			.filter(Boolean);
 	if (value === true) return undefined;
-	if (Array.isArray(value)) return value.map((entry) => entry.trim()).filter(Boolean);
+	if (Array.isArray(value))
+		return value.map((entry) => entry.trim()).filter(Boolean);
 	return undefined;
 }
 
@@ -81,13 +111,17 @@ export function defaultSkillsForRole(role: string): string[] {
 	return DEFAULT_ROLE_SKILLS[role] ?? [];
 }
 
-function collectTaskSkillNames(input: ResolveTaskSkillsInput | undefined): string[] {
+function collectTaskSkillNames(
+	input: ResolveTaskSkillsInput | undefined,
+): string[] {
 	if (!input) return [];
 	if (input.override === false) return [];
-	const roleDefaultsDisabled = input.teamRole?.skills === false || input.step?.skills === false;
+	const roleDefaultsDisabled =
+		input.teamRole?.skills === false || input.step?.skills === false;
 	const names = roleDefaultsDisabled ? [] : defaultSkillsForRole(input.role);
 	if (input.agent?.skills?.length) names.push(...input.agent.skills);
-	if (Array.isArray(input.teamRole?.skills)) names.push(...input.teamRole.skills);
+	if (Array.isArray(input.teamRole?.skills))
+		names.push(...input.teamRole.skills);
 	if (Array.isArray(input.step?.skills)) names.push(...input.step.skills);
 	if (Array.isArray(input.override)) names.push(...input.override);
 	return unique(names);
@@ -103,10 +137,12 @@ export function resolveTaskSkillNames(input: ResolveTaskSkillsInput): string[] {
 // See: SECURITY-ISSUES.md SEC-003
 // ═══════════════════════════════════════════════════════════════════════════
 
-function candidateSkillDirs(cwd: string): Array<{ root: string; source: "project" | "package" }> {
+function candidateSkillDirs(
+	cwd: string,
+): Array<{ root: string; source: "project" | "package" }> {
 	return [
-		{ root: PACKAGE_SKILLS_DIR, source: "package" },   // ✓ Trusted first
-		{ root: path.resolve(cwd, "skills"), source: "project" },  // ⚠️ Override second
+		{ root: PACKAGE_SKILLS_DIR, source: "package" }, // ✓ Trusted first
+		{ root: path.resolve(cwd, "skills"), source: "project" }, // ⚠️ Override second
 	];
 }
 
@@ -120,7 +156,10 @@ interface CachedSkillMarkdown {
 
 const skillReadCache = new Map<string, CachedSkillMarkdown>();
 
-function rememberSkill(key: string, value: CachedSkillMarkdown): CachedSkillMarkdown {
+function rememberSkill(
+	key: string,
+	value: CachedSkillMarkdown,
+): CachedSkillMarkdown {
 	if (skillReadCache.has(key)) skillReadCache.delete(key);
 	skillReadCache.set(key, value);
 	while (skillReadCache.size > SKILL_CACHE_MAX_ENTRIES) {
@@ -144,7 +183,12 @@ function cachedSkillFresh(value: CachedSkillMarkdown): boolean {
 	}
 }
 
-function readSkillMarkdown(cwd: string, name: string): { path: string; source: "project" | "package"; content: string } | undefined {
+function readSkillMarkdown(
+	cwd: string,
+	name: string,
+):
+	| { path: string; source: "project" | "package"; content: string }
+	| undefined {
 	if (!isValidSkillName(name)) return undefined;
 	const cacheKey = `${path.resolve(cwd)}:${name}`;
 	const cached = skillReadCache.get(cacheKey);
@@ -158,9 +202,14 @@ function readSkillMarkdown(cwd: string, name: string): { path: string; source: "
 			if (fs.lstatSync(contained).isSymbolicLink()) continue;
 			const filePath = resolveRealContainedPath(entry.root, relative);
 			const stat = fs.statSync(filePath);
-			return rememberSkill(cacheKey, { path: filePath, source: entry.source, content: fs.readFileSync(filePath, "utf-8"), mtimeMs: stat.mtimeMs, size: stat.size });
-		} catch {
-		}
+			return rememberSkill(cacheKey, {
+				path: filePath,
+				source: entry.source,
+				content: fs.readFileSync(filePath, "utf-8"),
+				mtimeMs: stat.mtimeMs,
+				size: stat.size,
+			});
+		} catch {}
 	}
 	return undefined;
 }
@@ -168,7 +217,9 @@ function readSkillMarkdown(cwd: string, name: string): { path: string; source: "
 function frontmatterDescription(content: string): string | undefined {
 	const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
 	if (!match) return undefined;
-	const line = match[1].split(/\r?\n/).find((entry) => entry.startsWith("description:"));
+	const line = match[1]
+		.split(/\r?\n/)
+		.find((entry) => entry.startsWith("description:"));
 	return line?.slice("description:".length).trim();
 }
 
@@ -179,8 +230,12 @@ function stripFrontmatter(content: string): string {
 function compactSkillContent(content: string): string {
 	const body = stripFrontmatter(content);
 	if (body.length <= MAX_SKILL_CHARS) return body;
-	const preferred = body.split(/\r?\n## Verification\r?\n/)[0]?.trim() ?? body;
-	const truncated = preferred.length > MAX_SKILL_CHARS ? preferred.slice(0, MAX_SKILL_CHARS - 40).trimEnd() : preferred;
+	const preferred =
+		body.split(/\r?\n## Verification\r?\n/)[0]?.trim() ?? body;
+	const truncated =
+		preferred.length > MAX_SKILL_CHARS
+			? preferred.slice(0, MAX_SKILL_CHARS - 40).trimEnd()
+			: preferred;
 	return `${truncated}\n\n[skill instructions truncated]`;
 }
 
@@ -197,7 +252,11 @@ export interface RenderedSkillInstructions {
 	}>;
 }
 
-export function renderSkillInstructions(input: RenderSkillInstructionsInput & { runId?: string } = {} as RenderSkillInstructionsInput & { runId?: string }): RenderedSkillInstructions {
+export function renderSkillInstructions(
+	input: RenderSkillInstructionsInput & {
+		runId?: string;
+	} = {} as RenderSkillInstructionsInput & { runId?: string },
+): RenderedSkillInstructions {
 	const allNames = collectTaskSkillNames(input);
 	const names = allNames.slice(0, MAX_SELECTED_SKILLS);
 	const overflowCount = Math.max(0, allNames.length - names.length);
@@ -208,12 +267,18 @@ export function renderSkillInstructions(input: RenderSkillInstructionsInput & {
 	let omittedCount = overflowCount;
 
 	// ECC INSTINCT: Get confidence-weighted skills if runId is provided
-	let weightedSkills: RenderedSkillInstructions["weightedSkills"] = undefined;
+	let weightedSkills: RenderedSkillInstructions["weightedSkills"];
 	if (input.runId) {
 		// Register effectiveness hooks once per process
 		registerSkillEffectivenessHooks();
-		const weighted = getWeightedSkillsForRole(input.role, names, input.runId, CONFIDENCE_THRESHOLDS.TENTATIVE);
-		weightedSkills = weighted.map(w => ({
+		const weighted = getWeightedSkillsForRole(
+			input.cwd,
+			input.role,
+			names,
+			input.runId,
+			CONFIDENCE_THRESHOLDS.TENTATIVE,
+		);
+		weightedSkills = weighted.map((w) => ({
 			skillId: w.skillId,
 			confidence: w.confidence,
 			behavior: w.behavior,
@@ -237,13 +302,26 @@ export function renderSkillInstructions(input: RenderSkillInstructionsInput & {
 		}
 		skillPaths.push(path.dirname(loaded.path));
 		const description = frontmatterDescription(loaded.content);
-		const source = loaded.source === "project" ? `project:skills/${safeName}` : `package:skills/${safeName}`;
+		const source =
+			loaded.source === "project"
+				? `project:skills/${safeName}`
+				: `package:skills/${safeName}`;
 
 		// ECC INSTINCT: Add confidence annotation from weighted skills
-		const weighted = weightedSkills?.find(w => w.skillId === name);
-		const confidenceNote = weighted ? ` [Confidence: ${(weighted.confidence * 100).toFixed(0)}% — ${weighted.threshold}]` : "";
+		const weighted = weightedSkills?.find((w) => w.skillId === name);
+		const confidenceNote = weighted
+			? ` [Confidence: ${(weighted.confidence * 100).toFixed(0)}% — ${weighted.threshold}]`
+			: "";
 
-		const header = [`## ${safeName}`, description ? `Description: ${description}${confidenceNote}` : undefined, `Source: ${source}`].filter(Boolean).join("\n");
+		const header = [
+			`## ${safeName}`,
+			description
+				? `Description: ${description}${confidenceNote}`
+				: undefined,
+			`Source: ${source}`,
+		]
+			.filter(Boolean)
+			.join("\n");
 		const rawContent = compactSkillContent(loaded.content);
 		// Wrap skill content with provenance markers to help LLMs distinguish skill instructions
 		const wrappedContent = `<!-- skill: ${safeName} -->\n${rawContent}\n<!-- end-skill: ${safeName} -->`;