@nseng-ai/areg 0.1.1 → 0.1.2

package/src/gateways.ts

@@ -1,135 +1,35 @@
 import {
 	SKILL_LOOKUP_ROOT_DESCRIPTORS,
 	skillLookupDescriptorForSourceType,
-} from "./skill-lookup.ts";
+} from "@nseng-ai/foundation/skill-lookup";
 import type {
 	SkillLookupRoot,
 	SkillLookupRootDescriptor,
 	SkillLookupSourceType,
-} from "./skill-lookup.ts";
+} from "@nseng-ai/foundation/skill-lookup";
+import type { GitGateway } from "@nseng-ai/capability-kit/git";
 import type { ErrorInfo, Result } from "@nseng-ai/foundation/result";
+import type { PathState, TextFileState } from "@nseng-ai/harness-artifacts/api";
 
-export const AREG_HOST_TOOL_NAMES = ["gh", "npx"] as const;
-export type AregHostToolName = (typeof AREG_HOST_TOOL_NAMES)[number];
+import type { AregManifestSkillSourcesInspection } from "./operations/manifest-sources.ts";
 
-export interface AregErrorInfo extends ErrorInfo {
-	displayCommand?: string;
-}
-
-export type AregOperationResult = Result<undefined, AregErrorInfo>;
-
-export type AregToolCheckResult =
-	| { type: "found"; tool: AregHostToolName; path: string }
-	| { type: "missing"; tool: AregHostToolName; message: string };
-
-export interface AregHostGateway {
-	checkTool(options: {
-		tool: AregHostToolName;
-		cwd: string;
-		env: NodeJS.ProcessEnv;
-	}): Promise<AregToolCheckResult>;
-}
-
-export type AregGithubSkillListResult =
-	| { type: "ok"; skillNames: readonly string[] }
-	| { type: "missing"; message: string }
-	| { type: "auth-error"; message: string }
-	| { type: "error"; error: AregErrorInfo };
-
-export type AregGithubSkillFileResult =
-	| { type: "found" }
-	| { type: "missing"; message: string }
-	| { type: "auth-error"; message: string }
-	| { type: "error"; error: AregErrorInfo };
-
-export interface AregGithubGateway {
-	listSkillDirectoryNames(options: {
-		repo: string;
-		ref?: string;
-		env: NodeJS.ProcessEnv;
-	}): Promise<AregGithubSkillListResult>;
-	checkSkillFile(options: {
-		repo: string;
-		path: string;
-		ref?: string;
-		env: NodeJS.ProcessEnv;
-	}): Promise<AregGithubSkillFileResult>;
-}
-
-export interface AregNpxSkillsAddRequest {
-	sourceRepo: string;
-	/** Empty means install all skills from the source repository. */
-	skillNames: readonly string[];
-	targetAgents: readonly string[];
-	cwd: string;
-	env: NodeJS.ProcessEnv;
-}
-
-export type AregNpxSkillsAddResult = { type: "ok" } | { type: "error"; error: AregErrorInfo };
-
-export interface AregNpxSkillsGateway {
-	addSkills(request: AregNpxSkillsAddRequest): Promise<AregNpxSkillsAddResult>;
-}
-
-export interface AregPromptGateway {
-	confirm(request: { message: string; defaultValue: boolean }): Promise<boolean>;
-}
-
-export interface AregSkillxInstalledSkill {
-	name: string;
-	directory: string;
-	skillFile: string;
-	relativeFiles: readonly string[];
-}
-
-export interface AregSkillxWorkspaceInstall {
-	workspaceRoot: string;
-	installedSkills: readonly AregSkillxInstalledSkill[];
-}
-
-export interface AregSkillxInstallRequest {
-	sourceRepo: string;
-	skillName?: string;
-	cwd: string;
-	env: NodeJS.ProcessEnv;
-}
-
-export interface AregSkillxWorkspaceCleanupRequest {
-	workspaceRoot: string;
-}
+// The git methods areg consumes: resolve the repo root and materialize
+// worktree-relative git paths (for example `info/exclude`). A full `GitGateway`
+// is assignable to this narrowed surface.
+export type AregGitGateway = Pick<GitGateway, "optionalRepoRoot" | "gitPath">;
 
-export type AregSkillxInstallResult =
-	| { type: "ok"; workspace: AregSkillxWorkspaceInstall }
-	| { type: "error"; error: AregErrorInfo };
+export type AregErrorInfo = ErrorInfo;
 
-export interface AregSkillxWorkspaceGateway {
-	installIntoWorkspace(request: AregSkillxInstallRequest): Promise<AregSkillxInstallResult>;
-	cleanupWorkspace(request: AregSkillxWorkspaceCleanupRequest): Promise<AregOperationResult>;
-}
-
-export type AregPathState =
-	| { type: "missing" }
-	| { type: "file" }
-	| { type: "directory" }
-	| { type: "symlink"; target: string }
-	| { type: "other" };
-
-export type AregTextFileState =
-	| { type: "missing" }
-	| { type: "file"; text: string }
-	| { type: "directory" }
-	| { type: "symlink"; target: string }
-	| { type: "other" }
-	| { type: "unreadable"; message: string };
+export type AregOperationResult = Result<undefined, AregErrorInfo>;
 
 export interface AregCheckSkillInspection {
 	name: string;
-	skillsPath: AregPathState;
-	agentsPath: AregPathState;
-	claudePath: AregPathState;
-	localSkillMd: AregTextFileState;
-	remoteSkillMd: AregTextFileState;
-	openaiPolicy: AregTextFileState;
+	skillsPath: PathState;
+	agentsPath: PathState;
+	claudePath: PathState;
+	localSkillMd: TextFileState;
+	remoteSkillMd: TextFileState;
+	openaiPolicy: TextFileState;
 }
 
 export function missingCheckSkillInspection(name: string): AregCheckSkillInspection {
@@ -178,8 +78,8 @@ export interface AregSkillFindSkillInspection {
 	root: SkillLookupRoot;
 	sourceType: SkillLookupSourceType;
 	baseRelativePath: string;
-	skillDir: AregPathState;
-	skillMd: AregTextFileState;
+	skillDir: PathState;
+	skillMd: TextFileState;
 }
 
 export interface AregSkillFindRootsInspection {
@@ -190,11 +90,11 @@ export interface AregSkillKindSkillInspection {
 	name: string;
 	sourceType: AregSkillKindSourceType;
 	baseRelativePath: string;
-	skillDir: AregPathState;
-	skillMd: AregTextFileState;
-	openaiPolicy: AregTextFileState;
-	agentsPath: AregPathState;
-	claudePath: AregPathState;
+	skillDir: PathState;
+	skillMd: TextFileState;
+	openaiPolicy: TextFileState;
+	agentsPath: PathState;
+	claudePath: PathState;
 }
 
 export interface AregReplacementInspection {
@@ -220,22 +120,15 @@ export interface AregSkillInspectionRequest {
 
 export interface AregProjectBaseInspection {
 	projectDir: string;
-	projectPathState: AregPathState;
-	lockfile: AregTextFileState;
-	nsToml: AregTextFileState;
-	aregJson: AregTextFileState;
-}
-
-export interface AregInstructionFilesInspection {
-	agentsMd: AregTextFileState;
-	claudeMd: AregTextFileState;
-	claudeDir: AregPathState;
-	claudeSettings: AregTextFileState;
+	projectPathState: PathState;
+	lockfile: TextFileState;
+	nsToml: TextFileState;
+	aregJson: TextFileState;
 }
 
 export interface AregPiArtifactsInspection {
-	piDir: AregPathState;
-	piSettings: AregTextFileState;
+	piDir: PathState;
+	piSettings: TextFileState;
 	replacement: AregReplacementInspection;
 }
 
@@ -263,15 +156,12 @@ export type AregSkillKindResolveResult =
 	| { type: "ok"; skillName: string }
 	| { type: "error"; error: AregErrorInfo };
 
-export type AregProjectMutationPolicy = "init" | "skill-kind";
-
 export interface AregProjectTextWriteRequest {
 	projectDir: string;
 	relativePath: string;
 	content: string;
 	description: string;
 	createParent: boolean;
-	policy: AregProjectMutationPolicy;
 	env: NodeJS.ProcessEnv;
 }
 
@@ -279,7 +169,6 @@ export interface AregProjectManagedTargetRequest {
 	projectDir: string;
 	relativePath: string;
 	description: string;
-	policy: "skill-kind";
 	env: NodeJS.ProcessEnv;
 }
 
@@ -298,15 +187,17 @@ export type AregProjectRemoveEmptyDirResult =
  * This is intentionally domain-oriented: it exposes named areg project facts and
  * project-scoped safe mutation primitives, not a generic filesystem API. Add new
  * reads here only when they represent stable areg project concepts, and route new
- * writes/deletes through project-scoped primitives with an explicit policy. Do not
+ * writes/deletes through project-scoped primitives. Do not
  * add an unrestricted filesystem gateway to areg as a convenience for operation code.
  */
 export interface AregProjectGateway {
 	inspectProjectBase(request: AregProjectInspectionRequest): Promise<AregProjectBaseInspection>;
-	inspectInstructionFiles(request: AregProjectDirRequest): Promise<AregInstructionFilesInspection>;
 	inspectPiArtifacts(request: AregProjectDirRequest): Promise<AregPiArtifactsInspection>;
 	inspectPiSkillInventory(request: AregProjectDirRequest): Promise<AregPiSkillInventoryInspection>;
 	inspectSkillNameInventory(request: AregProjectDirRequest): Promise<AregSkillNameInventory>;
+	inspectManifestSkillSources(
+		request: AregProjectDirRequest,
+	): Promise<AregManifestSkillSourcesInspection>;
 	inspectSkillFindRoots(request: AregProjectDirRequest): Promise<AregSkillFindRootsInspection>;
 	inspectCheckSkill(request: AregSkillInspectionRequest): Promise<AregCheckSkillInspection>;
 	inspectSkillKindSkill(request: AregSkillInspectionRequest): Promise<AregSkillKindSkillInspection>;
@@ -331,13 +222,6 @@ export interface AregProjectGateway {
 	): Promise<AregProjectRemoveEmptyDirResult>;
 }
 
-export interface AregInitTextWritePlan {
-	relativePath: "ns.toml" | "AGENTS.md" | "CLAUDE.md" | ".claude/settings.local.json";
-	content: string;
-	description: string;
-	createParent: boolean;
-}
-
 export interface AregSkillKindTextWritePlan {
 	relativePath: string;
 	content: string;

package/src/index.ts

@@ -5,44 +5,18 @@ export type {
 	AregCheckSkillInspection,
 	AregErrorInfo,
 	AregReplacementInspection,
-	AregGithubGateway,
-	AregGithubSkillListResult,
-	AregHostGateway,
-	AregHostToolName,
-	AregNpxSkillsAddRequest,
-	AregNpxSkillsAddResult,
-	AregNpxSkillsGateway,
 	AregOperationResult,
-	AregPathState,
 	AregProjectBaseInspection,
 	AregProjectDirRequest,
 	AregProjectGateway,
 	AregProjectInspectionRequest,
-	AregProjectMutationPolicy,
 	AregProjectMutationResult,
 	AregProjectRemoveEmptyDirResult,
 	AregProjectTextWriteRequest,
-	AregPromptGateway,
 	AregSkillInspectionRequest,
 	AregSkillKindResolveRequest,
 	AregSkillKindResolveResult,
 	AregSkillKindSkillInspection,
-	AregSkillxInstallRequest,
-	AregSkillxInstallResult,
-	AregSkillxInstalledSkill,
-	AregSkillxWorkspaceCleanupRequest,
-	AregSkillxWorkspaceGateway,
-	AregSkillxWorkspaceInstall,
-	AregTextFileState,
-	AregToolCheckResult,
 } from "./gateways.ts";
-export { parseLockfileData, parseSkillFrontmatterText } from "./operations/check.ts";
-export { parseSkillInput } from "./operations/skillx.ts";
-export {
-	buildNpxSkillsAddArgs,
-	RealAregGithubGateway,
-	RealAregHostGateway,
-	RealAregNpxSkillsGateway,
-	RealAregProjectGateway,
-	RealAregSkillxWorkspaceGateway,
-} from "./real-gateways.ts";
+export { parseSkillFrontmatterText } from "./operations/check.ts";
+export { RealAregProjectGateway } from "./gateways/project-gateway.ts";

package/src/operations/check.ts

@@ -2,26 +2,25 @@ import { failure, ok, negative, type ClinkrExit } from "@nseng-ai/clinkr";
 import type { Result } from "@nseng-ai/foundation/result";
 import { z } from "zod";
 
-import type { AregCliContext } from "../context.ts";
-import { missingCheckSkillInspection } from "../gateways.ts";
-import type { AregCheckSkillInspection } from "../gateways.ts";
-import { sortStrings } from "../sort.ts";
-import { isPathStateError } from "./file-state.ts";
-import { parseSkillFrontmatterBlock } from "./frontmatter.ts";
 import {
+	expectedAgentsSkillSymlinkTarget,
+	expectedClaudeSkillSymlinkTarget,
+	isAgentsSkillMirror,
+	isClaudeSkillMirror,
 	parseInspectedLockfile,
-	parseLockfileData,
+	parseSkillFrontmatterBlock,
 	type LockfileSkill,
 	type SkillsLockfile,
-} from "./lockfile.ts";
+} from "@nseng-ai/harness-artifacts/api";
+
+import type { AregCliContext } from "../context.ts";
+import { missingCheckSkillInspection } from "../gateways.ts";
+import { sortStringsLocaleAware } from "../sort.ts";
+import { manifestSourceFinding } from "./manifest-source-findings.ts";
+import type { AregCheckSkillInspection } from "../gateways.ts";
+import { isPathStateError } from "./file-state.ts";
 import { verifyPiReplacement } from "./pi-replacement.ts";
 import { parsePiSettings } from "./pi-settings.ts";
-import {
-	expectedAgentsSkillSymlinkTarget,
-	expectedClaudeSkillSymlinkTarget,
-	isAgentsSkillMirror,
-	isClaudeSkillMirror,
-} from "./skill-mirror-conventions.ts";
 import {
 	inferSkillKindRecord,
 	inspectSkillFrontmatter,
@@ -58,6 +57,9 @@ const CHECK_ISSUE_CODES = [
 	"agents-md-missing-peer",
 	"claude-md-missing-agents-ref",
 	"pi-settings-unusable",
+	"invalid-install-manifest",
+	"manifest-skill-target-missing",
+	"manifest-skill-md-missing",
 ] as const;
 
 const MAX_SKILL_DESCRIPTION_CHARS = 1024;
@@ -71,8 +73,6 @@ interface CheckIssue {
 	message: string;
 }
 
-export { parseLockfileData };
-
 const checkIssueSchema = z.object({
 	skill: z.string(),
 	code: z.enum(CHECK_ISSUE_CODES),
@@ -151,6 +151,7 @@ export function buildCheckReport(
 		issues.push(...checkSkillInvocationKind(entry, inspected, record));
 	}
 	issues.push(...checkLockfileHashes(lockfile));
+	issues.push(...checkManifestSkillSources(inspection));
 	issues.push(...checkOrphansAndDangling(lockfile, inspection));
 	issues.push(...checkPairing(inspection));
 	return {
@@ -175,7 +176,7 @@ export function formatCheckReport(report: Pick<CheckReport, "issues">): string {
 		grouped.set(issue.skill, existing);
 	}
 	const lines: string[] = [];
-	for (const skill of sortStrings([...grouped.keys()])) {
+	for (const skill of sortStringsLocaleAware([...grouped.keys()])) {
 		lines.push("", `${skill}:`);
 		for (const issue of grouped.get(skill) ?? []) lines.push(`  ${issue.message}`);
 	}
@@ -183,6 +184,18 @@ export function formatCheckReport(report: Pick<CheckReport, "issues">): string {
 	return lines.join("\n");
 }
 
+function checkManifestSkillSources(inspection: CheckProjectInspection): CheckIssue[] {
+	const issues: CheckIssue[] = [];
+	for (const error of inspection.manifestSkillSources.errors) {
+		issues.push(issue("project", "invalid-install-manifest", error.message));
+	}
+	for (const source of inspection.manifestSkillSources.sources) {
+		const finding = manifestSourceFinding(source);
+		if (finding !== undefined) issues.push(issue(source.skillName, finding.code, finding.message));
+	}
+	return issues;
+}
+
 function checkLocalSkill(
 	entry: LockfileSkill,
 	inspected: AregCheckSkillInspection,
@@ -470,7 +483,7 @@ function checkOrphansAndDangling(
 	const excluded = new Set(inspection.excludedSkillNames);
 	const byName = new Map(inspection.skills.map((skill) => [skill.name, skill]));
 	const issues: CheckIssue[] = [];
-	for (const name of sortStrings(inspection.skillsDirectoryNames)) {
+	for (const name of sortStringsLocaleAware(inspection.skillsDirectoryNames)) {
 		if (!lockNames.has(name) && !excluded.has(name))
 			issues.push(
 				issue(
@@ -480,7 +493,7 @@ function checkOrphansAndDangling(
 				),
 			);
 	}
-	for (const name of sortStrings(inspection.agentsSkillNames)) {
+	for (const name of sortStringsLocaleAware(inspection.agentsSkillNames)) {
 		if (!lockNames.has(name) && !excluded.has(name))
 			issues.push(
 				issue(
@@ -490,7 +503,7 @@ function checkOrphansAndDangling(
 				),
 			);
 	}
-	for (const name of sortStrings([...lockNames])) {
+	for (const name of sortStringsLocaleAware([...lockNames])) {
 		const inspected = byName.get(name) ?? missingCheckSkillInspection(name);
 		if (
 			inspected.skillsPath.type === "missing" &&

package/src/operations/doctor-skills.ts

@@ -4,16 +4,25 @@ import { optionalEntries, optionalEntry } from "@nseng-ai/foundation/primitives"
 import { z } from "zod";
 
 import type { AregCliContext } from "../context.ts";
+import type { PathState, TextFileState } from "@nseng-ai/harness-artifacts/api";
 import type {
 	AregCheckSkillInspection,
-	AregPathState,
 	AregPiSkillInventoryInspection,
 	AregProjectBaseInspection,
 	AregReplacementInspection,
 	AregSkillKindSkillInspection,
 	AregSkillNameInventory,
-	AregTextFileState,
 } from "../gateways.ts";
+import {
+	MANIFEST_FAILURE_CODE,
+	MANIFEST_FAILURE_REMEDIATION,
+	manifestSourceFinding,
+} from "./manifest-source-findings.ts";
+import {
+	manifestSkillKindNames,
+	toManifestSkillSourceView,
+	type AregManifestSkillSourcesInspection,
+} from "./manifest-sources.ts";
 import { uniqueSortedStrings } from "../sort.ts";
 import { renderDoctorSkills } from "./doctor-skills-report.ts";
 import {
@@ -24,7 +33,7 @@ import {
 import { parsePiSettings } from "./pi-settings.ts";
 import { collectCheckSkillInspections, collectSkillKindInspections } from "./project-inspection.ts";
 import { buildSkillKindRecords, type SkillKindRecord } from "./skill-kind-inference.ts";
-import { isAgentsSkillMirror, isClaudeSkillMirror } from "./skill-mirror-conventions.ts";
+import { isAgentsSkillMirror, isClaudeSkillMirror } from "@nseng-ai/harness-artifacts/api";
 
 const doctorStatusValues = ["ok", "warning", "error"] as const;
 
@@ -57,8 +66,9 @@ export interface DoctorSkillsInspection {
 	skillInventory: AregSkillNameInventory;
 	piSkillInventory: AregPiSkillInventoryInspection;
 	replacement: AregReplacementInspection;
-	piDir: AregPathState;
-	piSettings: AregTextFileState;
+	manifestSkillSources: AregManifestSkillSourcesInspection;
+	piDir: PathState;
+	piSettings: TextFileState;
 	checkSkills: readonly AregCheckSkillInspection[];
 	skillKindSkills: readonly AregSkillKindSkillInspection[];
 }
@@ -162,11 +172,13 @@ export function buildDoctorSkillFindings(
 		piDir: inspection.piDir,
 		piSettings: inspection.piSettings,
 		replacement: inspection.replacement,
+		manifestSkillSources: inspection.manifestSkillSources,
 		skills: inspection.skillKindSkills,
 	});
 	const records = skillKindRecords.ok ? skillKindRecords.value : [];
 	const findings: DoctorSkillFinding[] = [];
 	findings.push(...filesystemFindings(inspection));
+	findings.push(...manifestFindings(inspection));
 	findings.push(...piInventoryFindings(inspection));
 	findings.push(...replacementFindings(records, piSettings.value.exclusions));
 	if (!skillKindRecords.ok) {
@@ -206,9 +218,21 @@ async function inspectDoctorSkillsProject(
 	const piArtifacts = await ctx.project.inspectPiArtifacts({ projectDir, env: ctx.env });
 	const skillInventory = await ctx.project.inspectSkillNameInventory({ projectDir, env: ctx.env });
 	const piSkillInventory = await ctx.project.inspectPiSkillInventory({ projectDir, env: ctx.env });
-	const skillNames = allKnownSkillNames(skillInventory, { includeSkillKindNames: true });
+	const manifestSkillSources = await ctx.project.inspectManifestSkillSources({
+		projectDir,
+		env: ctx.env,
+	});
+	const baseSkillNames = allKnownSkillNames(skillInventory, { includeSkillKindNames: true });
+	const skillNames = uniqueSortedStrings([
+		...baseSkillNames,
+		...manifestSkillSources.sources.map((source) => source.skillName),
+	]);
 	const checkSkills = await collectCheckSkillInspections(ctx, projectDir, skillNames);
-	const skillKindSkills = await collectSkillKindInspections(ctx, projectDir, skillNames);
+	const skillKindNames = uniqueSortedStrings([
+		...baseSkillNames,
+		...manifestSkillKindNames(manifestSkillSources.sources),
+	]);
+	const skillKindSkills = await collectSkillKindInspections(ctx, projectDir, skillKindNames);
 	return {
 		type: "ok",
 		value: {
@@ -217,6 +241,7 @@ async function inspectDoctorSkillsProject(
 			skillInventory,
 			piSkillInventory,
 			replacement: piArtifacts.replacement,
+			manifestSkillSources,
 			piDir: piArtifacts.piDir,
 			piSettings: piArtifacts.piSettings,
 			checkSkills,
@@ -283,6 +308,45 @@ function filesystemFindings(inspection: DoctorSkillsInspection): readonly Doctor
 	return findings;
 }
 
+function manifestFindings(inspection: DoctorSkillsInspection): readonly DoctorSkillFinding[] {
+	const findings: DoctorSkillFinding[] = [];
+	for (const error of inspection.manifestSkillSources.errors) {
+		findings.push({
+			code: MANIFEST_FAILURE_CODE,
+			severity: "error",
+			message: error.message,
+			remediation: MANIFEST_FAILURE_REMEDIATION,
+			path: error.type === "manifest" ? error.manifestPath : error.harness,
+		});
+	}
+	for (const source of inspection.manifestSkillSources.sources) {
+		const evidence = toManifestSkillSourceView(source);
+		const finding = manifestSourceFinding(source);
+		if (finding !== undefined) {
+			findings.push({
+				code: finding.code,
+				severity: "warning",
+				skill: source.skillName,
+				path: finding.path,
+				message: finding.message,
+				remediation: finding.remediation,
+				evidence,
+			});
+		} else {
+			findings.push({
+				code: "manifest-skill-source",
+				severity: "info",
+				skill: source.skillName,
+				path: source.targetSkillRelativePath,
+				message: `${source.skillName} is tracked by shared manifest entry ${source.manifestKey} from ${source.provenance.packageName}@${source.provenance.version}.`,
+				remediation: "No action required unless this manifest provenance is stale.",
+				evidence,
+			});
+		}
+	}
+	return findings;
+}
+
 function piInventoryFindings(inspection: DoctorSkillsInspection): readonly DoctorSkillFinding[] {
 	const findings: DoctorSkillFinding[] = [];
 	const expected = new Set(inspection.skillInventory.skillKindNames);

package/src/operations/file-state.ts

@@ -1,10 +1,10 @@
 import { optionalEntry } from "@nseng-ai/foundation/primitives";
 import { resultErr, type Result } from "@nseng-ai/foundation/result";
 
-import type { AregPathState, AregTextFileState } from "../gateways.ts";
+import type { PathState, TextFileState } from "@nseng-ai/harness-artifacts/api";
 
-type NonUsableTextFileState = Exclude<AregTextFileState, { type: "file" } | { type: "missing" }>;
-type NonUsableDirectoryState = Exclude<AregPathState, { type: "directory" } | { type: "missing" }>;
+type NonUsableTextFileState = Exclude<TextFileState, { type: "file" } | { type: "missing" }>;
+type NonUsableDirectoryState = Exclude<PathState, { type: "directory" } | { type: "missing" }>;
 
 export function isPathStateError(error: { code: string }): boolean {
 	return (
@@ -16,7 +16,7 @@ export function isPathStateError(error: { code: string }): boolean {
 
 export function validateOptionalDirectoryState(options: {
 	pathLabel: string;
-	state: AregPathState;
+	state: PathState;
 	action: string;
 	symlinkSubject?: string;
 }): Result<undefined> {

package/src/operations/manifest-source-findings.ts

@@ -0,0 +1,45 @@
+import {
+	classifyManifestSkillSource,
+	type AregManifestSkillSourceInspection,
+} from "./manifest-sources.ts";
+
+export interface ManifestSourceFinding {
+	code: "manifest-skill-target-missing" | "manifest-skill-md-missing";
+	message: string;
+	path: string;
+	remediation: string;
+}
+
+export const MANIFEST_FAILURE_CODE = "invalid-install-manifest";
+export const MANIFEST_FAILURE_REMEDIATION =
+	"Fix the shared harness artifact manifest or run ns update to reconcile manifest-tracked artifacts.";
+export const MANIFEST_SOURCE_REMEDIATION =
+	"Run ns update to reconcile manifest-tracked harness artifacts, or remove/fix the stale manifest entry through the owning provisioning workflow.";
+
+export function manifestSourceLabel(source: AregManifestSkillSourceInspection): string {
+	return `Shared manifest entry ${source.manifestKey} from ${source.provenance.packageName}@${source.provenance.version}`;
+}
+
+export function manifestSourceFinding(
+	source: AregManifestSkillSourceInspection,
+): ManifestSourceFinding | undefined {
+	const label = manifestSourceLabel(source);
+	const status = classifyManifestSkillSource(source);
+	if (status === "target-missing") {
+		return {
+			code: "manifest-skill-target-missing",
+			path: source.targetSkillRelativePath,
+			message: `${label} targets ${source.targetSkillRelativePath}, but the skill directory is missing.`,
+			remediation: MANIFEST_SOURCE_REMEDIATION,
+		};
+	}
+	if (status === "md-missing") {
+		return {
+			code: "manifest-skill-md-missing",
+			path: `${source.targetSkillRelativePath}/SKILL.md`,
+			message: `${label} targets ${source.targetSkillRelativePath}, but SKILL.md is missing.`,
+			remediation: MANIFEST_SOURCE_REMEDIATION,
+		};
+	}
+	return undefined;
+}