@iowarp/clio-coder 0.3.3 → 0.3.4

package/src/tools/verify/catalog.ts

@@ -0,0 +1,346 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { parseDocument } from "yaml";
+import { resolveSafeCwd, SAFE_EXEC_DEFAULT_TIMEOUT_MS } from "../../core/safe-exec.js";
+import { isProjectVerifierCheckId } from "../../core/verification-scripts.js";
+import { compareCodepoints } from "../../domains/evidence/ordering.js";
+
+export const PROJECT_VERIFIER_CATALOG_RELATIVE_PATH = ".clio-coder/verifiers.yaml";
+export const PROJECT_VERIFIER_CATALOG_VERSION = 1;
+
+/** Public schema limits. Diagnostics cite these values instead of hiding policy. */
+export const PROJECT_VERIFIER_CATALOG_CAPS = Object.freeze({
+	fileBytes: 256 * 1024,
+	checks: 128,
+	idBytes: 64,
+	descriptionBytes: 512,
+	argvEntries: 64,
+	argumentBytes: 4096,
+	cwdBytes: 512,
+	timeoutMs: 900_000,
+	tags: 16,
+	tagBytes: 32,
+});
+
+export type DeclaredCheckSourceKind = "package.json" | "project-catalog";
+
+export interface DeclaredCheckSourceRef {
+	kind: DeclaredCheckSourceKind;
+	path: string;
+}
+
+/** Canonical projection shared by built-in and project check providers. */
+export interface DeclaredCheck {
+	id: string;
+	description: string;
+	command: string[];
+	cwd: string;
+	timeoutMs: number;
+	tags: string[];
+	source: DeclaredCheckSourceRef;
+}
+
+export interface DeclaredCheckSource extends DeclaredCheckSourceRef {
+	checks: DeclaredCheck[];
+}
+
+export type ProjectCatalogLoadResult = { ok: true; source: DeclaredCheckSource | null } | { ok: false; reason: string };
+
+const ROOT_FIELDS = new Set(["version", "checks"]);
+const CHECK_FIELDS = new Set(["id", "description", "command", "cwd", "timeoutMs", "tags"]);
+const TAG_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+const SHELL_EXECUTABLES = new Set([
+	"bash",
+	"cmd",
+	"command.com",
+	"dash",
+	"fish",
+	"ksh",
+	"powershell",
+	"pwsh",
+	"sh",
+	"tcsh",
+	"zsh",
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function utf8Bytes(value: string): number {
+	return Buffer.byteLength(value, "utf8");
+}
+
+function hasControlCharacter(value: string): boolean {
+	for (let index = 0; index < value.length; index += 1) {
+		const code = value.charCodeAt(index);
+		if (code <= 31 || code === 127) return true;
+	}
+	return false;
+}
+
+function catalogDiagnostic(message: string): ProjectCatalogLoadResult {
+	return { ok: false, reason: `${PROJECT_VERIFIER_CATALOG_RELATIVE_PATH}: ${message}` };
+}
+
+function unknownFields(record: Record<string, unknown>, allowed: ReadonlySet<string>): string[] {
+	return Object.keys(record)
+		.filter((key) => !allowed.has(key))
+		.sort(compareCodepoints);
+}
+
+function relativeCwd(workspaceRoot: string, resolved: string): string {
+	const relative = path.relative(workspaceRoot, resolved);
+	return relative.length === 0 ? "." : relative.split(path.sep).join("/");
+}
+
+interface ProjectVerifierCwdResolution {
+	declared: string;
+	execution: string;
+}
+
+function safelyResolveCatalogCwd(
+	rawCwd: string,
+	workspaceRoot: string,
+	location: string,
+): ProjectVerifierCwdResolution | Error {
+	if (path.isAbsolute(rawCwd) || path.win32.isAbsolute(rawCwd)) {
+		return new Error(`${location} must be repository-relative; absolute cwd '${rawCwd}' is not allowed`);
+	}
+	let resolved: string;
+	try {
+		resolved = resolveSafeCwd(rawCwd, workspaceRoot);
+	} catch {
+		return new Error(`${location} escapes the workspace root: '${rawCwd}'`);
+	}
+	let realCwd: string;
+	try {
+		const cwdStat = statSync(resolved);
+		if (!cwdStat.isDirectory()) return new Error(`${location} is not a directory: '${rawCwd}'`);
+		const realRoot = realpathSync(workspaceRoot);
+		realCwd = realpathSync(resolved);
+		resolveSafeCwd(realCwd, realRoot);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (message.includes("escapes workspace root")) {
+			return new Error(`${location} escapes the workspace root through a symbolic link: '${rawCwd}'`);
+		}
+		return new Error(`${location} cannot be resolved as a repository directory: '${rawCwd}' (${message})`);
+	}
+	return { declared: relativeCwd(workspaceRoot, resolved), execution: realCwd };
+}
+
+/** Revalidate a stored catalog cwd and return its canonical in-workspace execution path. */
+export function resolveProjectVerifierExecutionCwd(rawCwd: string, workspaceRoot: string): string | Error {
+	const resolution = safelyResolveCatalogCwd(rawCwd, workspaceRoot, "project check cwd");
+	return resolution instanceof Error ? resolution : resolution.execution;
+}
+
+function validateId(value: unknown, location: string): string | Error {
+	if (typeof value !== "string" || value.length === 0) return new Error(`${location} must be a non-empty string`);
+	if (utf8Bytes(value) > PROJECT_VERIFIER_CATALOG_CAPS.idBytes) {
+		return new Error(`${location} exceeds the ${PROJECT_VERIFIER_CATALOG_CAPS.idBytes}-byte cap`);
+	}
+	if (!isProjectVerifierCheckId(value)) {
+		return new Error(`${location} must match /^[a-z0-9][a-z0-9._:-]*$/`);
+	}
+	if (value === "frontend") return new Error(`${location} uses reserved built-in check id 'frontend'`);
+	return value;
+}
+
+function validateDescription(value: unknown, location: string): string | Error {
+	if (typeof value !== "string" || value.length === 0) return new Error(`${location} must be a non-empty string`);
+	if (value.trim() !== value || hasControlCharacter(value)) {
+		return new Error(`${location} must be trimmed, single-line text without control characters`);
+	}
+	if (utf8Bytes(value) > PROJECT_VERIFIER_CATALOG_CAPS.descriptionBytes) {
+		return new Error(`${location} exceeds the ${PROJECT_VERIFIER_CATALOG_CAPS.descriptionBytes}-byte cap`);
+	}
+	return value;
+}
+
+function validateCommand(value: unknown, location: string): string[] | Error {
+	if (!Array.isArray(value) || value.length === 0) {
+		return new Error(`${location} must be a non-empty argv string array; shell command strings are not allowed`);
+	}
+	if (value.length > PROJECT_VERIFIER_CATALOG_CAPS.argvEntries) {
+		return new Error(`${location} exceeds the ${PROJECT_VERIFIER_CATALOG_CAPS.argvEntries}-entry cap`);
+	}
+	const command: string[] = [];
+	for (const [index, entry] of value.entries()) {
+		const entryLocation = `${location}[${index}]`;
+		if (typeof entry !== "string" || entry.length === 0) {
+			return new Error(`${entryLocation} must be a non-empty string`);
+		}
+		if (entry.includes("\0")) return new Error(`${entryLocation} must not contain a NUL byte`);
+		if (utf8Bytes(entry) > PROJECT_VERIFIER_CATALOG_CAPS.argumentBytes) {
+			return new Error(`${entryLocation} exceeds the ${PROJECT_VERIFIER_CATALOG_CAPS.argumentBytes}-byte cap`);
+		}
+		command.push(entry);
+	}
+	const executable = command[0] ?? "";
+	if (/\s/u.test(executable)) {
+		return new Error(`${location}[0] must be one executable token, not a shell command string`);
+	}
+	const executableName = path
+		.basename(executable)
+		.toLowerCase()
+		.replace(/\.exe$/u, "");
+	if (SHELL_EXECUTABLES.has(executableName)) {
+		return new Error(`${location}[0] may not invoke shell executable '${executable}'`);
+	}
+	return command;
+}
+
+function validateTimeout(value: unknown, location: string): number | Error {
+	if (!Number.isInteger(value) || typeof value !== "number" || value <= 0) {
+		return new Error(`${location} must be a positive integer number of milliseconds`);
+	}
+	if (value > PROJECT_VERIFIER_CATALOG_CAPS.timeoutMs) {
+		return new Error(`${location} exceeds the ${PROJECT_VERIFIER_CATALOG_CAPS.timeoutMs}ms cap`);
+	}
+	return value;
+}
+
+function validateTags(value: unknown, location: string): string[] | Error {
+	if (!Array.isArray(value)) return new Error(`${location} must be an array of bounded tag strings`);
+	if (value.length > PROJECT_VERIFIER_CATALOG_CAPS.tags) {
+		return new Error(`${location} exceeds the ${PROJECT_VERIFIER_CATALOG_CAPS.tags}-tag cap`);
+	}
+	const tags: string[] = [];
+	const seen = new Set<string>();
+	for (const [index, entry] of value.entries()) {
+		const entryLocation = `${location}[${index}]`;
+		if (typeof entry !== "string" || entry.length === 0) {
+			return new Error(`${entryLocation} must be a non-empty string`);
+		}
+		if (utf8Bytes(entry) > PROJECT_VERIFIER_CATALOG_CAPS.tagBytes) {
+			return new Error(`${entryLocation} exceeds the ${PROJECT_VERIFIER_CATALOG_CAPS.tagBytes}-byte cap`);
+		}
+		if (!TAG_PATTERN.test(entry)) return new Error(`${entryLocation} must match /^[a-z0-9][a-z0-9._-]*$/`);
+		if (seen.has(entry)) return new Error(`${location} contains duplicate tag '${entry}'`);
+		seen.add(entry);
+		tags.push(entry);
+	}
+	return tags;
+}
+
+function sourcePathInsideWorkspace(catalogPath: string, workspaceRoot: string): string | Error {
+	try {
+		const realRoot = realpathSync(workspaceRoot);
+		const realCatalogPath = realpathSync(catalogPath);
+		resolveSafeCwd(realCatalogPath, realRoot);
+		return realCatalogPath;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return new Error(`catalog file must resolve inside the workspace root (${message})`);
+	}
+}
+
+export function loadProjectVerifierCatalog(workspaceRoot: string): ProjectCatalogLoadResult {
+	const catalogPath = path.join(workspaceRoot, PROJECT_VERIFIER_CATALOG_RELATIVE_PATH);
+	if (!existsSync(catalogPath)) return { ok: true, source: null };
+	const safeSourcePath = sourcePathInsideWorkspace(catalogPath, workspaceRoot);
+	if (safeSourcePath instanceof Error) return catalogDiagnostic(safeSourcePath.message);
+	let text: string;
+	try {
+		const stats = statSync(safeSourcePath);
+		if (!stats.isFile()) return catalogDiagnostic("catalog path must be a regular file");
+		if (stats.size > PROJECT_VERIFIER_CATALOG_CAPS.fileBytes) {
+			return catalogDiagnostic(`file exceeds the ${PROJECT_VERIFIER_CATALOG_CAPS.fileBytes}-byte cap`);
+		}
+		text = readFileSync(safeSourcePath, "utf8");
+	} catch (error) {
+		return catalogDiagnostic(`cannot read catalog (${error instanceof Error ? error.message : String(error)})`);
+	}
+	return parseProjectVerifierCatalogText(text, workspaceRoot, catalogPath);
+}
+
+/** Parse catalog text through the production schema and canonical normalizer. */
+export function parseProjectVerifierCatalogText(
+	text: string,
+	workspaceRoot: string,
+	catalogPath = path.join(workspaceRoot, PROJECT_VERIFIER_CATALOG_RELATIVE_PATH),
+): ProjectCatalogLoadResult {
+	const document = parseDocument(text, { prettyErrors: false, strict: true, uniqueKeys: true });
+	if (document.errors.length > 0) {
+		return catalogDiagnostic(`invalid YAML: ${document.errors.map((error) => error.message).join("; ")}`);
+	}
+	let parsed: unknown;
+	try {
+		parsed = document.toJS({ maxAliasCount: 0 }) as unknown;
+	} catch (error) {
+		return catalogDiagnostic(`invalid YAML: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!isRecord(parsed)) return catalogDiagnostic("root must be an object with version and checks fields");
+	const rootUnknown = unknownFields(parsed, ROOT_FIELDS);
+	if (rootUnknown.length > 0) return catalogDiagnostic(`root has unknown field(s): ${rootUnknown.join(", ")}`);
+	if (!Object.hasOwn(parsed, "version")) return catalogDiagnostic("root.version is required");
+	if (parsed.version !== PROJECT_VERIFIER_CATALOG_VERSION) {
+		return catalogDiagnostic(
+			`unsupported version ${JSON.stringify(parsed.version)}; supported version is ${PROJECT_VERIFIER_CATALOG_VERSION}`,
+		);
+	}
+	if (!Object.hasOwn(parsed, "checks")) return catalogDiagnostic("root.checks is required");
+	if (!Array.isArray(parsed.checks)) return catalogDiagnostic("root.checks must be an array");
+	if (parsed.checks.length > PROJECT_VERIFIER_CATALOG_CAPS.checks) {
+		return catalogDiagnostic(`root.checks exceeds the ${PROJECT_VERIFIER_CATALOG_CAPS.checks}-check cap`);
+	}
+
+	const sourceRef: DeclaredCheckSourceRef = { kind: "project-catalog", path: catalogPath };
+	const checks: DeclaredCheck[] = [];
+	const ids = new Map<string, number>();
+	for (const [index, value] of parsed.checks.entries()) {
+		const location = `checks[${index}]`;
+		if (!isRecord(value)) return catalogDiagnostic(`${location} must be an object`);
+		const checkUnknown = unknownFields(value, CHECK_FIELDS);
+		if (checkUnknown.length > 0) {
+			return catalogDiagnostic(`${location} has unknown field(s): ${checkUnknown.join(", ")}`);
+		}
+		for (const field of CHECK_FIELDS) {
+			if (!Object.hasOwn(value, field)) return catalogDiagnostic(`${location}.${field} is required`);
+		}
+
+		const id = validateId(value.id, `${location}.id`);
+		if (id instanceof Error) return catalogDiagnostic(id.message);
+		const duplicateIndex = ids.get(id);
+		if (duplicateIndex !== undefined) {
+			return catalogDiagnostic(`${location}.id duplicates '${id}' from checks[${duplicateIndex}].id`);
+		}
+		const description = validateDescription(value.description, `${location}.description`);
+		if (description instanceof Error) return catalogDiagnostic(description.message);
+		const command = validateCommand(value.command, `${location}.command`);
+		if (command instanceof Error) return catalogDiagnostic(command.message);
+		if (typeof value.cwd !== "string" || value.cwd.length === 0) {
+			return catalogDiagnostic(`${location}.cwd must be a non-empty repository-relative string`);
+		}
+		if (value.cwd.includes("\0")) return catalogDiagnostic(`${location}.cwd must not contain a NUL byte`);
+		if (utf8Bytes(value.cwd) > PROJECT_VERIFIER_CATALOG_CAPS.cwdBytes) {
+			return catalogDiagnostic(`${location}.cwd exceeds the ${PROJECT_VERIFIER_CATALOG_CAPS.cwdBytes}-byte cap`);
+		}
+		const cwdResolution = safelyResolveCatalogCwd(value.cwd, workspaceRoot, `${location}.cwd`);
+		if (cwdResolution instanceof Error) return catalogDiagnostic(cwdResolution.message);
+		const cwd = cwdResolution.declared;
+		const timeoutMs = validateTimeout(value.timeoutMs, `${location}.timeoutMs`);
+		if (timeoutMs instanceof Error) return catalogDiagnostic(timeoutMs.message);
+		const tags = validateTags(value.tags, `${location}.tags`);
+		if (tags instanceof Error) return catalogDiagnostic(tags.message);
+
+		ids.set(id, index);
+		checks.push({ id, description, command, cwd, timeoutMs, tags, source: { ...sourceRef } });
+	}
+	checks.sort((left, right) => compareCodepoints(left.id, right.id));
+	return { ok: true, source: { ...sourceRef, checks } };
+}
+
+export function packageDeclaredCheck(id: string, packagePath: string, cwd: string, tags: string[]): DeclaredCheck {
+	return {
+		id,
+		description: `Run package.json script '${id}'.`,
+		command: ["npm", "run", id],
+		cwd,
+		timeoutMs: SAFE_EXEC_DEFAULT_TIMEOUT_MS,
+		tags,
+		source: { kind: "package.json", path: packagePath },
+	};
+}

package/src/tools/verify/index.ts

@@ -1,13 +1,19 @@
 import { isVerificationScriptName } from "../../core/verification-scripts.js";
 import type { ToolResult, ToolSpec } from "../registry.js";
 import { runFrontendCheck } from "./frontend.js";
-import { listChecks, runScriptCheck, VERIFICATION_SCRIPT_FAMILY_HINT } from "./scripts.js";
+import {
+	discoverDeclaredChecks,
+	listChecks,
+	runProjectCheck,
+	runScriptCheck,
+	VERIFICATION_SCRIPT_FAMILY_HINT,
+} from "./scripts.js";
 import { prepareVerifyArguments, verifyToolSurface } from "./surface.js";
 
 /**
  * The verify tool: one EXECUTE entry point for declared verification.
- * verify() lists declared checks, verify(check=<script>) runs a package.json
- * verification script via the safe-exec spine, verify(check="frontend",
+ * verify() lists canonical checks, verify(check=<id>) runs a package script or
+ * exact project-catalog vector via safe-exec, and verify(check="frontend",
  * path=<file>) validates an HTML/CSS/JS artifact without shell access.
  */
 
@@ -20,6 +26,10 @@ export const verifyTool: ToolSpec = {
 			return listChecks(typeof args.cwd === "string" && args.cwd.length > 0 ? args.cwd : undefined);
 		}
 		if (check === "frontend") return runFrontendCheck(args, options);
+		const discovery = discoverDeclaredChecks(typeof args.cwd === "string" && args.cwd.length > 0 ? args.cwd : undefined);
+		if (!discovery.ok) return { kind: "error", message: `verify: ${discovery.reason}` };
+		const declared = discovery.sources.flatMap((source) => source.checks).find((candidate) => candidate.id === check);
+		if (declared?.source.kind === "project-catalog") return runProjectCheck(declared, options);
 		if (!isVerificationScriptName(check)) {
 			return {
 				kind: "error",

package/src/tools/verify/scripts.ts

@@ -4,58 +4,156 @@ import { resolveSafeCwd } from "../../core/safe-exec.js";
 import { declaredVerificationScripts, VERIFICATION_SCRIPT_FAMILY_HINT } from "../../core/verification-scripts.js";
 import type { ToolResult } from "../registry.js";
 import { runVectorTool } from "../safe-exec.js";
+import {
+	type DeclaredCheck,
+	type DeclaredCheckSource,
+	loadProjectVerifierCatalog,
+	PROJECT_VERIFIER_CATALOG_RELATIVE_PATH,
+	packageDeclaredCheck,
+	resolveProjectVerifierExecutionCwd,
+} from "./catalog.js";
 
 /**
- * verify(check=<script>): run one declared package.json verification script
- * through npm with no shell, and verify() with no check: list what is
- * declared. Internal module of the verify tool. The listing shape is grouped
- * by source so later check providers (Makefile, justfile, pixi) can add their
- * own groups without changing the surface.
+ * Package scripts and the project catalog meet here as one canonical check
+ * projection. Project checks retain their admitted argv/cwd/timeout exactly;
+ * package scripts keep the established npm argument-widening behavior.
  */
 
-export interface DeclaredCheckSource {
-	kind: "package.json";
-	path: string;
-	checks: string[];
+export type DeclaredCheckDiscoveryResult = { ok: true; sources: DeclaredCheckSource[] } | { ok: false; reason: string };
+
+function repositoryRelativeCwd(workspaceRoot: string, resolved: string): string {
+	const relative = path.relative(workspaceRoot, resolved);
+	return relative.length === 0 ? "." : relative.split(path.sep).join("/");
 }
 
-function declaredCheckSources(cwd: string): DeclaredCheckSource[] {
-	const pkgPath = path.join(cwd, "package.json");
-	if (!existsSync(pkgPath)) return [];
-	const pkg = parsePackageJson(pkgPath);
-	if (!pkg.ok) return [];
-	return [{ kind: "package.json", path: pkgPath, checks: declaredVerificationScripts(pkg.scripts) }];
+function packageTag(id: string): string[] {
+	const separator = id.search(/[:.-]/u);
+	return [separator === -1 ? id : id.slice(0, separator)];
 }
 
-export function listChecks(cwdArg: string | undefined): ToolResult {
-	let cwd: string;
+function packageCheckSource(packageRoot: string, workspaceRoot: string): DeclaredCheckSource | null {
+	const packagePath = path.join(packageRoot, "package.json");
+	if (!existsSync(packagePath)) return null;
+	const pkg = parsePackageJson(packagePath);
+	if (!pkg.ok) return null;
+	const cwd = repositoryRelativeCwd(workspaceRoot, packageRoot);
+	const checks = declaredVerificationScripts(pkg.scripts).map((id) =>
+		packageDeclaredCheck(id, packagePath, cwd, packageTag(id)),
+	);
+	return { kind: "package.json", path: packagePath, checks };
+}
+
+function providerCollision(sources: ReadonlyArray<DeclaredCheckSource>): string | null {
+	const seen = new Map<string, DeclaredCheck>();
+	for (const source of sources) {
+		for (const check of source.checks) {
+			const prior = seen.get(check.id);
+			if (prior !== undefined) {
+				return (
+					`duplicate declared check id '${check.id}' from ` +
+					`${prior.source.kind} (${prior.source.path}) and ${check.source.kind} (${check.source.path})`
+				);
+			}
+			seen.set(check.id, check);
+		}
+	}
+	return null;
+}
+
+export function discoverDeclaredChecksAtRoot(
+	workspaceRoot: string,
+	cwdArg: string | undefined,
+): DeclaredCheckDiscoveryResult {
+	let packageRoot: string;
 	try {
-		cwd = resolveSafeCwd(cwdArg, process.cwd());
-	} catch (err) {
-		return { kind: "error", message: `verify: ${err instanceof Error ? err.message : String(err)}` };
+		packageRoot = resolveSafeCwd(cwdArg, workspaceRoot);
+	} catch (error) {
+		return { ok: false, reason: error instanceof Error ? error.message : String(error) };
 	}
-	const sources = declaredCheckSources(cwd);
+	const sources: DeclaredCheckSource[] = [];
+	const packageSource = packageCheckSource(packageRoot, workspaceRoot);
+	if (packageSource !== null) sources.push(packageSource);
+	const projectCatalog = loadProjectVerifierCatalog(workspaceRoot);
+	if (!projectCatalog.ok) return projectCatalog;
+	if (projectCatalog.source !== null) sources.push(projectCatalog.source);
+	const collision = providerCollision(sources);
+	if (collision !== null) return { ok: false, reason: collision };
+	return { ok: true, sources };
+}
+
+export function discoverDeclaredChecks(cwdArg: string | undefined): DeclaredCheckDiscoveryResult {
+	return discoverDeclaredChecksAtRoot(process.cwd(), cwdArg);
+}
+
+function clonedSources(sources: ReadonlyArray<DeclaredCheckSource>): DeclaredCheckSource[] {
+	return sources.map((source) => ({
+		kind: source.kind,
+		path: source.path,
+		checks: source.checks.map((check) => ({
+			...check,
+			command: [...check.command],
+			tags: [...check.tags],
+			source: { ...check.source },
+		})),
+	}));
+}
+
+export function listChecks(cwdArg: string | undefined): ToolResult {
+	const discovery = discoverDeclaredChecks(cwdArg);
+	if (!discovery.ok) return { kind: "error", message: `verify: ${discovery.reason}` };
 	const lines: string[] = [];
-	if (sources.length === 0 || sources.every((source) => source.checks.length === 0)) {
-		lines.push("No declared verification checks found (no package.json verification scripts).");
+	if (discovery.sources.length === 0 || discovery.sources.every((source) => source.checks.length === 0)) {
+		lines.push(
+			`No declared verification checks found (no package.json verification scripts or ${PROJECT_VERIFIER_CATALOG_RELATIVE_PATH} entries).`,
+			"Run `clio-coder verifiers author` to inspect declared project tooling, preview exact argv checks, and create the catalog after confirmation.",
+		);
 	} else {
 		lines.push("Declared verification checks:");
-		for (const source of sources) {
-			lines.push(`${source.kind}:`);
-			for (const check of source.checks) lines.push(`- ${check}`);
+		for (const source of discovery.sources) {
+			lines.push(source.kind === "package.json" ? "package.json:" : `${PROJECT_VERIFIER_CATALOG_RELATIVE_PATH}:`);
+			for (const check of source.checks) {
+				const tags = check.tags.length > 0 ? ` [${check.tags.join(", ")}]` : "";
+				lines.push(`- ${check.id}${tags}: ${check.description}`);
+			}
 		}
 	}
 	lines.push(
 		"",
-		'Run one with verify(check="<name>"). verify(check="frontend", path=<file>) validates an HTML/CSS/JS artifact.',
+		'Run one with verify(check="<id>"). verify(check="frontend", path=<file>) validates an HTML/CSS/JS artifact.',
 	);
 	return {
 		kind: "ok",
 		output: lines.join("\n"),
-		details: { sources: sources.map((source) => ({ ...source })) },
+		details: { sources: clonedSources(discovery.sources) },
 	};
 }
 
+function withDeclaredEvidence(result: ToolResult, check: DeclaredCheck): ToolResult {
+	return {
+		...result,
+		details: {
+			...result.details,
+			action: "verify",
+			check: check.id,
+			source: { ...check.source },
+			description: check.description,
+			declaredCommand: [...check.command],
+			declaredCwd: check.cwd,
+			declaredTimeoutMs: check.timeoutMs,
+			tags: [...check.tags],
+		},
+	};
+}
+
+export async function runProjectCheck(check: DeclaredCheck, options?: { signal?: AbortSignal }): Promise<ToolResult> {
+	const [file, ...vector] = check.command;
+	if (file === undefined) return { kind: "error", message: `verify: declared check '${check.id}' has empty argv` };
+	const cwd = resolveProjectVerifierExecutionCwd(check.cwd, process.cwd());
+	if (cwd instanceof Error) return { kind: "error", message: `verify: ${cwd.message}` };
+	const result = await runVectorTool("verify", file, vector, { cwd, timeout_ms: check.timeoutMs }, options);
+	return withDeclaredEvidence(result, check);
+}
+
 export async function runScriptCheck(
 	check: string,
 	args: Record<string, unknown>,
@@ -64,12 +162,12 @@ export async function runScriptCheck(
 	let cwd: string;
 	try {
 		cwd = resolveSafeCwd(typeof args.cwd === "string" && args.cwd.length > 0 ? args.cwd : undefined, process.cwd());
-	} catch (err) {
-		return { kind: "error", message: `verify: ${err instanceof Error ? err.message : String(err)}` };
+	} catch (error) {
+		return { kind: "error", message: `verify: ${error instanceof Error ? error.message : String(error)}` };
 	}
-	const pkgPath = path.join(cwd, "package.json");
-	if (!existsSync(pkgPath)) return { kind: "error", message: `verify: package.json not found in ${cwd}` };
-	const pkg = parsePackageJson(pkgPath);
+	const packagePath = path.join(cwd, "package.json");
+	if (!existsSync(packagePath)) return { kind: "error", message: `verify: package.json not found in ${cwd}` };
+	const pkg = parsePackageJson(packagePath);
 	if (!pkg.ok) return { kind: "error", message: `verify: ${pkg.reason}` };
 	if (!Object.hasOwn(pkg.scripts, check)) {
 		const declared = declaredVerificationScripts(pkg.scripts);
@@ -90,10 +188,10 @@ export async function runScriptCheck(
 export { VERIFICATION_SCRIPT_FAMILY_HINT };
 
 function parsePackageJson(
-	pkgPath: string,
+	packagePath: string,
 ): { ok: true; scripts: Record<string, unknown> } | { ok: false; reason: string } {
 	try {
-		const parsed = JSON.parse(readFileSync(pkgPath, "utf8")) as unknown;
+		const parsed = JSON.parse(readFileSync(packagePath, "utf8")) as unknown;
 		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
 			return { ok: false, reason: "package.json root must be an object" };
 		}
@@ -102,7 +200,7 @@ function parsePackageJson(
 			return { ok: false, reason: "package.json has no scripts object" };
 		}
 		return { ok: true, scripts: scripts as Record<string, unknown> };
-	} catch (err) {
-		return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+	} catch (error) {
+		return { ok: false, reason: error instanceof Error ? error.message : String(error) };
 	}
 }

package/src/tools/verify/surface.ts

@@ -24,20 +24,24 @@ export function prepareVerifyArguments(args: Record<string, unknown>): Record<st
 export const verifyToolSurface = {
 	name: ToolNames.Verify,
 	description:
-		'Run a declared verification check: no arguments lists checks, check=<package.json script> runs it, check="frontend" with path validates an HTML/CSS/JS artifact.',
+		'Run a declared verification check: no arguments lists package scripts and .clio-coder/verifiers.yaml entries, check=<id> runs one, and check="frontend" with path validates an HTML/CSS/JS artifact.',
 	parameters: Type.Object({
 		check: Type.Optional(
 			Type.String({
-				description: `Declared script name (${VERIFICATION_SCRIPT_FAMILY_HINT}) or "frontend". Omit to list available checks.`,
+				description: `Declared project check ID, package script (${VERIFICATION_SCRIPT_FAMILY_HINT}), or "frontend". Omit to list available checks.`,
 			}),
 		),
 		path: Type.Optional(Type.String({ description: "check=frontend: artifact file under the workspace root." })),
-		args: Type.Optional(Type.Array(Type.String(), { description: "Extra arguments passed after --." })),
+		args: Type.Optional(
+			Type.Array(Type.String(), { description: "Package scripts only: extra arguments passed after --." }),
+		),
 		browser: Type.Optional(
 			StringEnum(BROWSER_MODES, { description: "check=frontend: headless browser mode (default auto)." }),
 		),
-		cwd: Type.Optional(Type.String({ description: "Working directory." })),
-		timeout_ms: Type.Optional(Type.Number({ description: "Timeout in ms (default 120000)." })),
+		cwd: Type.Optional(Type.String({ description: "Package-script working directory; ignored by project checks." })),
+		timeout_ms: Type.Optional(
+			Type.Number({ description: "Package/frontend timeout in ms; project checks use their declared timeoutMs." }),
+		),
 		max_output_bytes: Type.Optional(Type.Number({ description: "Output cap in bytes (default 600000)." })),
 	}),
 	baseActionClass: "execute",