orizu 0.5.21 → 0.5.23

package/src/instruction-sets-cli.ts

@@ -43,13 +43,30 @@ const SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/u
 export interface SyncComponent { body?: string; repoPath?: string; contentSha?: string; commitSha?: string }
 export interface SyncMaterial { profileVersionId: string; versionNumber: number; modelConfigIdentity: string; resolvedFrom: string; components: Record<string, SyncComponent> }
 export interface SyncProfile { modelConfigIdentity: string; resolvedFrom: string; production: SyncMaterial | null }
-export interface SyncSet { name: string; slug?: string; description?: string | null; shape: string[]; default: SyncMaterial; profiles: SyncProfile[]; filteredTo?: string[] }
+export interface SyncSet {
+  projectId?: string
+  instructionSetId?: string
+  name: string
+  slug?: string
+  description?: string | null
+  shape: string[]
+  default: SyncMaterial
+  profiles: SyncProfile[]
+  filteredTo?: string[]
+}
 function safeSegment(value: string) { if (!SAFE_SEGMENT.test(value) || value === '.' || value === '..' || value.startsWith('.')) throw new Error('instruction_set_path_unsafe') }
+function isSafeSegment(value: string) {
+  try { safeSegment(value); return true } catch { return false }
+}
 function slug(identity: string) { return identity.replaceAll('/', '__').replace(/[^A-Za-z0-9._-]/gu, '_') }
 function stable(value: unknown): string { return `${JSON.stringify(value, null, 2)}\n` }
 function sha256(value: string): string { return createHash('sha256').update(value, 'utf8').digest('hex') }
 
-export interface SyncFileOps { writeFileSync: typeof writeFileSync; renameSync?: typeof renameSync }
+export interface SyncFileOps {
+  writeFileSync: typeof writeFileSync
+  renameSync?: typeof renameSync
+  rmSync?: typeof rmSync
+}
 
 function writeMaterial(root: string, material: SyncMaterial, shape: string[], manifestRoot: string, fileOps: SyncFileOps = { writeFileSync }) {
   const files: Record<string, string> = {}
@@ -77,16 +94,76 @@ function removeOwnScratch(paths: Array<string | null>) {
   for (const path of paths) if (path && existsSync(path)) rmSync(path, { recursive: true, force: true })
 }
 
-function existingDestinationIsSynced(destination: string, name: string) {
+function existingDestinationIsSynced(
+  destination: string,
+  set: Pick<SyncSet, 'projectId' | 'instructionSetId' | 'name' | 'slug'>
+) {
+  if (
+    set.slug &&
+    set.projectId === undefined &&
+    set.instructionSetId === undefined
+  ) {
+    return existingDestinationIsLegacySynced(destination, set.name, set.slug)
+  }
+  try {
+    if (!statSync(destination).isDirectory()) return false
+    const manifest = JSON.parse(readFileSync(join(destination, 'manifest.json'), 'utf8')) as {
+      manifestVersion?: number
+      projectId?: string
+      instructionSetId?: string
+      name?: string
+      slug?: string
+    }
+    return manifest.manifestVersion === 1 && (set.slug
+      ? manifest.slug === set.slug &&
+        manifest.projectId === set.projectId &&
+        manifest.instructionSetId === set.instructionSetId
+      : manifest.name === set.name)
+  } catch { return false }
+}
+
+function existingDestinationIsLegacySynced(
+  destination: string,
+  name: string,
+  slug?: string
+) {
   try {
     if (!statSync(destination).isDirectory()) return false
-    const manifest = JSON.parse(readFileSync(join(destination, 'manifest.json'), 'utf8')) as { manifestVersion?: number; name?: string }
-    return manifest.manifestVersion === 1 && manifest.name === name
+    const manifest = JSON.parse(readFileSync(join(destination, 'manifest.json'), 'utf8')) as {
+      manifestVersion?: number
+      name?: string
+      slug?: string
+    }
+    return manifest.manifestVersion === 1 &&
+      manifest.name === name &&
+      manifest.slug === slug
   } catch { return false }
 }
 
+function removePublishedBackups(
+  paths: string[],
+  remove: typeof rmSync
+) {
+  let firstError: unknown = null
+  for (const path of paths) {
+    if (!existsSync(path)) continue
+    try {
+      remove(path, { recursive: true, force: true })
+    } catch (error) {
+      firstError ??= error
+    }
+  }
+  if (firstError) throw new Error('instruction_set_sync_cleanup_failed')
+}
+
 export function syncToDisk(out: string, set: SyncSet, fileOps: SyncFileOps = { writeFileSync }) {
-  safeSegment(set.name)
+  const directoryName = set.slug || set.name
+  safeSegment(directoryName)
+  const hasProjectId = set.projectId !== undefined
+  const hasInstructionSetId = set.instructionSetId !== undefined
+  if (set.slug && hasProjectId !== hasInstructionSetId) {
+    throw new Error('instruction_set_sync_identity_missing')
+  }
   for (const key of set.shape) safeSegment(key)
   const profileSlugs = new Set<string>()
   for (const profile of set.profiles) {
@@ -96,11 +173,28 @@ export function syncToDisk(out: string, set: SyncSet, fileOps: SyncFileOps = { w
     profileSlugs.add(value)
   }
   mkdirSync(out, { recursive: true })
-  const destination = join(out, set.name)
-  if (existsSync(destination) && !existingDestinationIsSynced(destination, set.name)) throw new Error('instruction_set_sync_destination_not_synced')
-  const temp = join(out, `.${set.name}.${randomUUID()}.tmp`)
+  const destination = join(out, directoryName)
+  const legacyDestination = set.slug && set.name !== set.slug && isSafeSegment(set.name)
+    ? join(out, set.name)
+    : null
+  if (existsSync(destination)) {
+    if (set.slug && existingDestinationIsLegacySynced(destination, set.name)) {
+      throw new Error('instruction_set_sync_legacy_identity_required')
+    }
+    if (!existingDestinationIsSynced(destination, set)) {
+      throw new Error('instruction_set_sync_destination_not_synced')
+    }
+  }
+  if (legacyDestination && existsSync(legacyDestination)) {
+    if (existingDestinationIsLegacySynced(legacyDestination, set.name)) {
+      throw new Error('instruction_set_sync_legacy_identity_required')
+    }
+    throw new Error('instruction_set_sync_destination_not_synced')
+  }
+  const priorDestinations = [destination]
+  const temp = join(out, `.${directoryName}.${randomUUID()}.tmp`)
   const move = fileOps.renameSync || renameSync
-  let backup: string | null = null
+  const backups: Array<{ original: string; backup: string }> = []
   mkdirSync(temp)
   try {
     const defaultMaterial = writeMaterial(temp, set.default, set.shape, 'default', fileOps)
@@ -114,18 +208,40 @@ export function syncToDisk(out: string, set: SyncSet, fileOps: SyncFileOps = { w
         ? Object.entries(profile.production.files).map(([key, path]) => ({ key, modelConfig: profile.modelConfigIdentity, path, syncedContentSha256: profile.production!.syncedContentSha256[key] }))
         : []),
     ]
-    const manifest = { manifestVersion: 1, name: set.name, ...(Object.hasOwn(set, 'description') ? { description: set.description ?? null } : {}), shape: set.shape, components, default: defaultMaterial, profiles, ...(set.filteredTo ? { filteredTo: [...set.filteredTo].sort() } : {}) }
+    const manifest = {
+      manifestVersion: 1,
+      ...(set.projectId ? { projectId: set.projectId } : {}),
+      ...(set.instructionSetId ? { instructionSetId: set.instructionSetId } : {}),
+      name: set.name,
+      ...(set.slug ? { slug: set.slug } : {}),
+      ...(Object.hasOwn(set, 'description') ? { description: set.description ?? null } : {}),
+      shape: set.shape,
+      components,
+      default: defaultMaterial,
+      profiles,
+      ...(set.filteredTo ? { filteredTo: [...set.filteredTo].sort() } : {}),
+    }
     fileOps.writeFileSync(join(temp, 'manifest.json'), stable(manifest))
-    backup = join(out, `.${set.name}.${randomUUID()}.bak`)
-    if (existsSync(destination)) move(destination, backup)
-    try { move(temp, destination) } catch (error) { if (existsSync(backup)) move(backup, destination); throw error }
-    removeOwnScratch([backup])
+    for (const prior of priorDestinations) {
+      if (!existsSync(prior)) continue
+      const backup = join(out, `.${directoryName}.${randomUUID()}.bak`)
+      move(prior, backup)
+      backups.push({ original: prior, backup })
+    }
+    move(temp, destination)
   } catch (error) {
     removeOwnScratch([temp])
-    if (backup && existsSync(backup) && !existsSync(destination)) move(backup, destination)
-    removeOwnScratch([backup])
+    for (const { original, backup } of [...backups].reverse()) {
+      if (existsSync(backup) && !existsSync(original)) move(backup, original)
+    }
+    removeOwnScratch(backups.map(entry => entry.backup))
     throw error
   }
+  removePublishedBackups(
+    backups.map(entry => entry.backup),
+    fileOps.rmSync || rmSync
+  )
+  return destination
 }
 
 export async function instructionSetsCommand(args: string[], io: InstructionSetsCommandIo): Promise<number> {
@@ -143,6 +259,44 @@ export async function instructionSetsCommand(args: string[], io: InstructionSets
     writeManifest = loadInstructionSetManifest(reference)
   }
   const project = await io.resolveProjectSlug(argValue(args, '--project'))
+  if (subcommand === 'scorers') {
+    const action = reference
+    const set = positionals[2]
+    const componentKey = argValue(args, '--key')
+    const scorerVersionId = argValue(args, '--scorer-version')
+    if (
+      (action !== 'set-headline' && action !== 'add') ||
+      !set ||
+      !componentKey ||
+      !scorerVersionId
+    ) {
+      throw new Error(
+        'Usage: orizu instructions scorers set-headline|add <set> --key <component-key> --scorer-version <id> --project <team/project> [--dataset-version <id> --split-set <id> --split <name>] [--json]'
+      )
+    }
+    const payload = await responsePayload(await authedFetch(
+      `/api/cli/instruction-sets/${encodeURIComponent(set)}/scorers?project=${encodeURIComponent(project)}`,
+      {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          componentKey,
+          scorerVersionId,
+          role: action === 'set-headline' ? 'headline' : 'tracked',
+          datasetVersionId: argValue(args, '--dataset-version') || undefined,
+          splitSetId: argValue(args, '--split-set') || undefined,
+          splitName: argValue(args, '--split') || undefined,
+        }),
+      }
+    ), `Instruction sets scorers ${action}`)
+    if (io.json) io.print(JSON.stringify(payload))
+    else {
+      io.print(
+        `${action === 'set-headline' ? 'Set headline' : 'Added'} scorer ${sanitizeTerminalText(scorerVersionId)} for ${sanitizeTerminalText(set)} / ${sanitizeTerminalText(componentKey)}`
+      )
+    }
+    return 0
+  }
   if (subcommand === 'default') {
     const operation = reference; const set = positionals[2]; const identity = argValue(args, '--model-config'); const version = argValue(args, '--version')
     if ((operation !== 'show' && operation !== 'move') || !set) throw new Error('Usage: orizu instructions default show|move <set> --project <team/project> [--model-config <identity> --version <n>] [--json]')
@@ -270,8 +424,8 @@ export async function instructionSetsCommand(args: string[], io: InstructionSets
     if (!set || (set.slug !== reference && set.name !== reference) || (modelConfig && (!Array.isArray(set.filteredTo) || set.filteredTo.length !== 1 || set.filteredTo[0] !== modelConfig))) {
       throw new Error('instruction_set_sync_response_mismatch')
     }
-    syncToDisk(output, set)
-    if (io.json) io.print(JSON.stringify(payload)); else io.print(`Synced ${set.name} to ${join(output, set.name)}`)
+    const destination = syncToDisk(output, set)
+    if (io.json) io.print(JSON.stringify(payload)); else io.print(`Synced ${set.name} to ${destination}`)
     return 0
   }
   if (subcommand === 'show' && (!reference || reference.startsWith('--'))) throw new Error('Instruction set name is required')

package/src/optimizations-promote-cli.ts

@@ -1,9 +1,12 @@
 import { extractErrorMessage } from './error-response.js'
-import { sanitizeTerminalText } from './json-response.js'
+import { sanitizeHumanInlineText, sanitizeTerminalText } from './json-response.js'
+import type { GlobalFlags } from './global-flags.js'
 
 export interface OptimizationsPromoteIo {
   json: boolean
+  origin: GlobalFlags
   print: (line: string) => void
+  printErr: (line: string) => void
   resolveProjectSlug: (projectArg: string | null) => Promise<string>
   fetcher: (path: string, init?: RequestInit) => Promise<Response>
 }
@@ -13,6 +16,57 @@ function option(args: readonly string[], name: string): string | null {
   return index === -1 || !args[index + 1] || args[index + 1].startsWith('--') ? null : args[index + 1]
 }
 
+function shellArgument(value: string): string {
+  if (/^[A-Za-z0-9._/:@-]+$/.test(value)) return value
+  if (/[\u0000-\u001F\u007F-\u009F\u2028\u2029]/.test(value)) {
+    let escaped = ''
+    for (const character of value) {
+      if (character === '\\') escaped += '\\\\'
+      else if (character === "'") escaped += "\\'"
+      else if (character === '\n') escaped += '\\n'
+      else if (character === '\r') escaped += '\\r'
+      else if (character === '\t') escaped += '\\t'
+      else {
+        const codePoint = character.codePointAt(0)!
+        if (codePoint <= 0x1f || codePoint === 0x7f) {
+          escaped += `\\x${codePoint.toString(16).padStart(2, '0')}`
+        } else if ((codePoint >= 0x80 && codePoint <= 0x9f) || codePoint === 0x2028 || codePoint === 0x2029) {
+          for (const byte of new TextEncoder().encode(character)) {
+            escaped += `\\x${byte.toString(16).padStart(2, '0')}`
+          }
+        } else {
+          escaped += character
+        }
+      }
+    }
+    return `$'${escaped}'`
+  }
+  const safeValue = sanitizeTerminalText(value)
+  return `'${safeValue.replace(/'/g, `'\\''`)}'`
+}
+
+function inlineTerminalText(value: string): string {
+  return sanitizeHumanInlineText(sanitizeTerminalText, value)
+    .replaceAll('\u2028', '\\u2028')
+    .replaceAll('\u2029', '\\u2029')
+}
+
+const APPLIED_LABEL_VERSION_SKEW_NOTE = 'Server response predates the appliedLabel discriminator; printing the production-promotion follow-up as a fail-safe.'
+
+function productionPromotionReplay(
+  runId: string,
+  candidateId: string,
+  project: string,
+  origin: GlobalFlags
+): string {
+  const originArguments = origin.local
+    ? ' --local'
+    : origin.server
+      ? ` --server ${shellArgument(origin.server)}`
+      : ''
+  return `Promote this profile with: orizu${originArguments} optimizations promote ${shellArgument(runId)} --candidate ${shellArgument(candidateId)} --label production --project ${shellArgument(project)}`
+}
+
 export async function promoteOptimizationCommand(args: string[], io: OptimizationsPromoteIo): Promise<void> {
   const runId = args.find(arg => !arg.startsWith('--') && arg !== option(args, '--candidate') && arg !== option(args, '--label') && arg !== option(args, '--project'))
   const candidateId = option(args, '--candidate')
@@ -25,17 +79,41 @@ export async function promoteOptimizationCommand(args: string[], io: Optimizatio
     method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ candidateId, label }),
   })
   if (!response.ok) throw new Error(`Failed to promote optimization candidate: ${await extractErrorMessage(response)}`)
-  const data = await response.json() as { promptVersionId?: string; profileVersionId?: string; components?: Array<{ key: string; status: string }> }
+  const data = await response.json() as
+    | { promptVersionId: string }
+    | {
+      profileVersionId: string
+      versionNumber: number
+      appliedLabel?: string | null
+      components: Array<{ key: string; status: string }>
+    }
+  const isProfilePromotion = 'profileVersionId' in data
+  const replay = isProfilePromotion && data.appliedLabel !== 'production'
+    ? productionPromotionReplay(runId, candidateId, project, io.origin)
+    : null
   if (io.json) {
-    io.print(JSON.stringify(data.profileVersionId
-      ? { profileVersionId: data.profileVersionId, components: data.components ?? [] }
+    io.print(JSON.stringify(isProfilePromotion
+      ? {
+          profileVersionId: data.profileVersionId,
+          versionNumber: data.versionNumber,
+          appliedLabel: data.appliedLabel,
+          components: data.components,
+        }
       : { promptVersionId: data.promptVersionId }))
+    if (isProfilePromotion && data.appliedLabel === undefined) {
+      io.printErr(APPLIED_LABEL_VERSION_SKEW_NOTE)
+      io.printErr(replay!)
+    }
     return
   }
-  if (data.profileVersionId) {
+  if (isProfilePromotion) {
     io.print(`Promoted profile version ${sanitizeTerminalText(data.profileVersionId)}`)
-    for (const component of data.components ?? []) io.print(`${sanitizeTerminalText(component.key)}: ${sanitizeTerminalText(component.status)}`)
+    if (data.appliedLabel === undefined) {
+      io.printErr(APPLIED_LABEL_VERSION_SKEW_NOTE)
+    }
+    if (replay) io.print(replay)
+    for (const component of data.components) io.print(`${inlineTerminalText(component.key)}: ${inlineTerminalText(component.status)}`)
     return
   }
-  io.print(`Promoted prompt version ${sanitizeTerminalText(data.promptVersionId ?? '')}`)
+  io.print(`Promoted prompt version ${sanitizeTerminalText(data.promptVersionId)}`)
 }

package/src/runner-dir-verify.ts

@@ -9,6 +9,7 @@ import {
   shouldExcludeArtifactPath,
 } from './artifact-archive.js'
 import { authedFetch } from './http.js'
+import { cleanupAll, throwWithCleanup } from './cleanup.js'
 
 /**
  * ALI-1159 (ADR-007): ad-hoc `--runner-dir` bytes may only execute when they
@@ -159,7 +160,7 @@ export async function verifyRunnerDirRegistered(input: VerifyRunnerDirInput): Pr
 
   if (registeredSha.toLowerCase() !== localSha.toLowerCase()) {
     throw new Error(
-      `Local runner bytes at ${dir} are not registered runner version ${input.runnerVersionId} ` +
+      `runner_version_bytes_mismatch: Local runner bytes at ${dir} are not registered runner version ${input.runnerVersionId} ` +
       `(content sha ${localSha} != ${registeredSha}). Runs may only execute registered runner bytes ` +
       '(ADR-007): register the directory first with `orizu runners push` ' +
       '(use --session <session-id> inside a workspace session) and re-run against the new version, ' +
@@ -979,9 +980,10 @@ export async function verifyGepaRunnerDirsFromArgs(
   let rewritten = [...args]
   const verifiedDirs: string[] = []
   const cleanups: Array<() => void> = []
-  const cleanup = () => {
-    for (const dispose of cleanups) dispose()
-  }
+  const cleanup = () => cleanupAll(
+    cleanups,
+    'Failed to clean verified runner snapshots'
+  )
 
   try {
     for (const pair of GEPA_RUNNER_FLAG_PAIRS) {
@@ -1021,8 +1023,11 @@ export async function verifyGepaRunnerDirsFromArgs(
       rewritten = rewriteFlagValue(rewritten, pair.dirFlag, verified.snapshotDir)
     }
   } catch (error) {
-    cleanup()
-    throw error
+    throwWithCleanup(
+      error,
+      cleanups,
+      'Runner verification failed and snapshot cleanup also failed'
+    )
   }
 
   return { args: rewritten, verifiedDirs, cleanup }

package/src/skilled-proposer-bake-report.ts

@@ -0,0 +1 @@
+export const SKILLED_PROPOSER_BAKE_REPORT_FIELDS = ['venv', 'publishKey', 'publishedVenv', 'waitedForPublishLock', 'pythonPathEntries', 'executedPipArgv', 'sslCertFile', 'warnings', 'marker', 'python', 'packageRoot', 'manager', 'lock', 'vendoredGepaPath', 'launcherVenv', 'launcherSslCertFile'] as const

package/src/skilled-proposer-config.ts

@@ -0,0 +1,191 @@
+import { createHash } from 'node:crypto'
+import { readFileSync, statSync } from 'node:fs'
+import { basename, dirname, extname, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+interface NormalizedTextSource { source: string, content: string, sha256: string, byteLength: number }
+interface NormalizedSkill extends NormalizedTextSource { name: string, description: string | null }
+
+const CONFIG_KEYS = new Set(['schemaVersion', 'skills', 'additionalInstructionsFile', 'baseInstructionsFile',
+  'maxWords', 'maxTokens', 'maxExamples', 'onError',
+])
+const PATH_SKILL_KEYS = new Set(['path', 'name', 'description'])
+const INLINE_SKILL_KEYS = new Set(['name', 'description', 'inline'])
+
+function configError(field: string, detail: string): never { throw new Error(`--candidate-proposer-config ${field} ${detail}`) }
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+function rejectUnknownKeys(value: Record<string, unknown>, allowed: Set<string>, field = ''): void {
+  const unknown = Object.keys(value).find(key => !allowed.has(key))
+  if (unknown) configError(field ? `${field}.${unknown}` : unknown, 'is not supported')
+}
+function sha256(bytes: Uint8Array): string { return createHash('sha256').update(bytes).digest('hex') }
+function decodeUtf8(bytes: Uint8Array, field: string): string {
+  try {
+    return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes)
+  } catch {
+    configError(field, 'must contain valid UTF-8 text')
+  }
+}
+function readRegularFile(path: string, field: string): Buffer {
+  try {
+    if (!statSync(path).isFile()) configError(field, 'must resolve to a file')
+    return readFileSync(path)
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith('--candidate-proposer-config')) throw error
+    configError(field, `is missing or unreadable: ${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+function logicalSource(configDirectory: string, path: string): string {
+  return relative(configDirectory, path).split(sep).join('/') || basename(path)
+}
+function normalizedText(bytes: Buffer, source: string, field: string): NormalizedTextSource {
+  const content = decodeUtf8(bytes, field)
+  if (!content.trim()) configError(field, 'must not be empty')
+  return { source, content, sha256: sha256(bytes), byteLength: bytes.byteLength }
+}
+function parseFrontmatter(content: string, field: string): { name?: string, description?: string, body: string } {
+  const lines = content.split(/\r?\n/)
+  if (lines[0]?.replace(/^\uFEFF/, '').trim() !== '---') return { body: content }
+  const end = lines.slice(1).findIndex(line => line.trim() === '---')
+  if (end < 0) configError(field, 'has malformed frontmatter without a closing ---')
+  const metadata: Record<string, string> = {}
+  for (const raw of lines.slice(1, end + 1)) {
+    if (/^[ \t]/.test(raw) || !raw.includes(':')) continue
+    const colon = raw.indexOf(':')
+    metadata[raw.slice(0, colon).trim()] = raw.slice(colon + 1).trim().replace(/^(['"])(.*)\1$/, '$2')
+  }
+  return {
+    name: metadata.name || undefined,
+    description: metadata.description || undefined,
+    body: lines.slice(end + 2).join('\n'),
+  }
+}
+function wellFormedString(value: string, field: string): string {
+  if (!(value as string & { isWellFormed(): boolean }).isWellFormed()) {
+    configError(field, 'must contain well-formed Unicode text')
+  }
+  return value
+}
+function nonEmptyString(value: unknown, field: string): string {
+  if (typeof value !== 'string' || !value.trim()) configError(field, 'must be a non-empty string')
+  return wellFormedString(value, field)
+}
+function nullableDescription(value: unknown, field: string): string | null {
+  if (value === null) return null
+  if (typeof value !== 'string') configError(field, 'must be a string or null')
+  return wellFormedString(value, field) || null
+}
+function normalizePathSkill(entry: Record<string, unknown>, index: number, configDirectory: string): NormalizedSkill {
+  const field = `skills[${index}]`
+  rejectUnknownKeys(entry, PATH_SKILL_KEYS, field)
+  const configuredPath = nonEmptyString(entry.path, `${field}.path`)
+  let resolvedPath = resolve(configDirectory, configuredPath)
+  try {
+    if (statSync(resolvedPath).isDirectory()) {
+      resolvedPath = resolve(resolvedPath, 'SKILL.md')
+      try {
+        if (!statSync(resolvedPath).isFile()) configError(`${field}.path`, 'directory must contain SKILL.md')
+      } catch (error) {
+        if (error instanceof Error && error.message.startsWith('--candidate-proposer-config')) throw error
+        configError(`${field}.path`, 'directory must contain SKILL.md')
+      }
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith('--candidate-proposer-config')) throw error
+    configError(`${field}.path`, 'is missing or unreadable')
+  }
+  const text = normalizedText(readRegularFile(resolvedPath, `${field}.path`),
+    logicalSource(configDirectory, resolvedPath), `${field}.path`)
+  const frontmatter = parseFrontmatter(text.content, `${field}.path`)
+  if (!frontmatter.body.trim()) configError(`${field}.path`, 'must contain non-empty skill content')
+  const fallbackName = extname(resolvedPath)
+    ? basename(resolvedPath, extname(resolvedPath))
+    : basename(resolvedPath)
+  const name = entry.name === undefined
+    ? frontmatter.name ?? (basename(resolvedPath) === 'SKILL.md' ? basename(dirname(resolvedPath)) : fallbackName)
+    : nonEmptyString(entry.name, `${field}.name`)
+  const description = entry.description === undefined
+    ? frontmatter.description ?? null
+    : nullableDescription(entry.description, `${field}.description`)
+  return { name, description, ...text }
+}
+function normalizeInlineSkill(entry: Record<string, unknown>, index: number): NormalizedSkill {
+  const field = `skills[${index}]`
+  rejectUnknownKeys(entry, INLINE_SKILL_KEYS, field)
+  const name = nonEmptyString(entry.name, `${field}.name`)
+  const description = nonEmptyString(entry.description, `${field}.description`)
+  const content = nonEmptyString(entry.inline, `${field}.inline`)
+  const bytes = Buffer.from(content, 'utf8')
+  return { name, description, source: `inline:${name}`, content,
+    sha256: sha256(bytes), byteLength: bytes.byteLength }
+}
+function normalizeSkill(value: unknown, index: number, configDirectory: string): NormalizedSkill {
+  const field = `skills[${index}]`
+  if (!isRecord(value)) configError(field, 'must be an object')
+  const hasPath = Object.hasOwn(value, 'path')
+  const hasInline = Object.hasOwn(value, 'inline')
+  if (hasPath === hasInline) configError(field, 'must contain exactly one of path or inline')
+  return hasPath ? normalizePathSkill(value, index, configDirectory) : normalizeInlineSkill(value, index)
+}
+function optionalPositiveInteger(value: unknown, field: string): number | null {
+  if (value === undefined || value === null) return null
+  if (!Number.isSafeInteger(value) || (value as number) <= 0) configError(field, 'must be a positive integer or null')
+  return value as number
+}
+function normalizeInstructionFile(value: unknown, field: string, configDirectory: string): NormalizedTextSource | null {
+  if (value === undefined || value === null) return null
+  const configuredPath = nonEmptyString(value, field)
+  const resolvedPath = resolve(configDirectory, configuredPath)
+  return normalizedText(readRegularFile(resolvedPath, field), logicalSource(configDirectory, resolvedPath), field)
+}
+function lockedPackageVersion(): string {
+  const lockPath = fileURLToPath(new URL('../requirements/skilled-proposer.lock', import.meta.url))
+  const match = /^skilled-proposer==([^\s\\]+)/m.exec(readFileSync(lockPath, 'utf8'))
+  if (!match) throw new Error('ALI_1505_SKILLED_PROPOSER_LOCK_VERSION_MISSING')
+  return match[1]
+}
+export function normalizedSkilledProposerConfig(value: string): string {
+  const suppliedPath = nonEmptyString(value.startsWith('@') ? value.slice(1) : value, 'path')
+  const configPath = resolve(suppliedPath)
+  const configBytes = readRegularFile(configPath, 'path')
+  const raw = decodeUtf8(configBytes, 'path').replace(/^\uFEFF/, '')
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    configError('path', `must contain valid JSON: ${error instanceof Error ? error.message : String(error)}`)
+  }
+  if (!isRecord(parsed)) configError('path', 'must contain a JSON object')
+  rejectUnknownKeys(parsed, CONFIG_KEYS)
+  if (parsed.schemaVersion !== 1) configError('schemaVersion', 'must be 1')
+  if (!Array.isArray(parsed.skills)) configError('skills', 'must be an array')
+
+  const configDirectory = dirname(configPath)
+  const skills = parsed.skills.map((skill, index) => normalizeSkill(skill, index, configDirectory))
+  const names = new Set<string>()
+  for (const skill of skills) {
+    if (names.has(skill.name)) configError('skills', `contains duplicate resolved name ${skill.name}`)
+    names.add(skill.name)
+  }
+  const onError = parsed.onError ?? 'keep'
+  if (onError !== 'keep' && onError !== 'raise') configError('onError', 'must be keep or raise')
+
+  const normalized = {
+    schemaVersion: 1,
+    implementation: 'cmpnd-ai/skilled-proposer',
+    packageVersion: lockedPackageVersion(),
+    skills,
+    additionalInstructions: normalizeInstructionFile(parsed.additionalInstructionsFile,
+      'additionalInstructionsFile', configDirectory),
+    baseInstructions: normalizeInstructionFile(parsed.baseInstructionsFile, 'baseInstructionsFile', configDirectory),
+    maxWords: optionalPositiveInteger(parsed.maxWords, 'maxWords'),
+    maxTokens: optionalPositiveInteger(parsed.maxTokens, 'maxTokens'),
+    maxExamples: optionalPositiveInteger(parsed.maxExamples, 'maxExamples'),
+    onError,
+  }
+  const configFileSha256 = sha256(configBytes)
+  const configSha256 = sha256(Buffer.from(JSON.stringify({ configFileSha256, ...normalized }), 'utf8'))
+  return JSON.stringify({ ...normalized, configFileSha256, configSha256 })
+}