cognitive-core 0.2.5 → 0.3.1

package/dist/memory/procedural-skill.js

@@ -0,0 +1,846 @@
+/**
+ * Filesystem-canonical procedural memory.
+ *
+ * This module defines the round-trip format for storing a cognitive-core
+ * Playbook as a portable SKILL.md file. Generic skill consumers can read the
+ * top-level fields/body; cognitive-core reindexes from the namespaced `ccore`
+ * frontmatter block.
+ */
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { z } from 'zod';
+const FRONTMATTER_REGEX = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
+const CCORE_SCHEMA_VERSION = 1;
+const IGNORED_SKILL_SCAN_DIRS = new Set(['node_modules', '.git', '.candidates']);
+const PROCEDURAL_PLAYBOOK_ROOT = 'playbooks';
+const AtlasMemoryManifestSchema = z
+    .object({
+    schemaVersion: z.number().int().positive().default(1),
+    canonicalStores: z
+        .object({
+        knowledge: z.enum(['filesystem', 'sqlite']).optional(),
+        procedural: z.enum(['filesystem', 'sqlite']).optional(),
+        episodes: z.enum(['filesystem', 'sqlite']).optional(),
+    })
+        .passthrough()
+        .optional(),
+    procedural: z
+        .object({
+        dir: z.string().min(1).optional(),
+        strictStartup: z.boolean().optional(),
+        pruneSqliteOnly: z.boolean().optional(),
+    })
+        .passthrough()
+        .optional(),
+})
+    .passthrough();
+export function resolveScopedProceduralPlaybookDir(baseDir, dir = PROCEDURAL_PLAYBOOK_ROOT) {
+    if (isAbsolute(dir)) {
+        throw new Error(`Procedural playbook directory must be relative to Atlas storage root: ${dir}`);
+    }
+    const root = resolve(baseDir, PROCEDURAL_PLAYBOOK_ROOT);
+    const candidate = resolve(baseDir, dir);
+    const rel = relative(root, candidate);
+    if (candidate !== root && (rel.startsWith('..') || isAbsolute(rel))) {
+        throw new Error(`Procedural playbook directory must stay under ${root}: ${dir}`);
+    }
+    return candidate;
+}
+export class ProceduralMemoryFileStore {
+    rootDir;
+    constructor(rootDir) {
+        this.rootDir = rootDir;
+    }
+    async write(playbook, options = {}) {
+        const dirName = canonicalPlaybookDirName(playbook);
+        const skillDir = join(this.rootDir, dirName);
+        const path = join(skillDir, 'SKILL.md');
+        let baseFrontmatter = options.baseFrontmatter;
+        if (!baseFrontmatter && existsSync(path)) {
+            const existing = parsePlaybookSkillMarkdown(await readFile(path, 'utf-8'));
+            if (existing.playbook.id !== playbook.id) {
+                throw new Error(`Canonical skill directory collision: ${dirName} already contains playbook ${existing.playbook.id}`);
+            }
+            baseFrontmatter = existing.frontmatter;
+        }
+        const content = playbookToSkillMarkdown(playbook, {
+            ...options,
+            baseFrontmatter,
+            includeOperationalState: options.includeOperationalState ?? false,
+        });
+        await mkdir(skillDir, { recursive: true });
+        const tmpPath = join(skillDir, `.SKILL.md.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
+        await writeFile(tmpPath, content, 'utf-8');
+        await rename(tmpPath, path);
+        return path;
+    }
+    async delete(playbook) {
+        const skillDir = join(this.rootDir, canonicalPlaybookDirName(playbook));
+        const path = join(skillDir, 'SKILL.md');
+        if (existsSync(path)) {
+            try {
+                const existing = parsePlaybookSkillMarkdown(await readFile(path, 'utf-8'));
+                if (existing.playbook.id !== playbook.id)
+                    return;
+            }
+            catch {
+                return;
+            }
+        }
+        await rm(skillDir, {
+            recursive: true,
+            force: true,
+        });
+    }
+    /**
+     * Write the rebuildable operational-state sidecar (.ccore/state.json) next to
+     * the playbook's SKILL.md. Operational fields (confidence, counters,
+     * consolidation strength, lastUsed) are intentionally NOT in the stable
+     * SKILL.md, so this snapshot is what lets a from-files reindex restore them —
+     * making SQLite a pure rebuildable cache. Atomic (tmp + rename). No-op when the
+     * SKILL.md doesn't exist (nothing canonical to attach state to).
+     */
+    async writeState(playbook) {
+        const skillDir = join(this.rootDir, canonicalPlaybookDirName(playbook));
+        if (!existsSync(join(skillDir, 'SKILL.md')))
+            return;
+        const ccoreDir = join(skillDir, '.ccore');
+        const path = join(ccoreDir, 'state.json');
+        const state = {
+            id: playbook.id,
+            confidence: playbook.confidence,
+            successCount: playbook.evolution.successCount,
+            failureCount: playbook.evolution.failureCount,
+            consolidationStrength: playbook.evolution.consolidationStrength ?? 0,
+            domainBreadth: playbook.evolution.domainBreadth ?? 0,
+            lastUsed: playbook.evolution.lastUsed
+                ? new Date(playbook.evolution.lastUsed).toISOString()
+                : null,
+            updatedAt: playbook.updatedAt ? new Date(playbook.updatedAt).toISOString() : null,
+        };
+        await mkdir(ccoreDir, { recursive: true });
+        const tmpPath = join(ccoreDir, `.state.json.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
+        await writeFile(tmpPath, JSON.stringify(state, null, 2), 'utf-8');
+        await rename(tmpPath, path);
+    }
+}
+export async function readAtlasMemoryManifest(baseDir) {
+    const manifestPath = join(baseDir, 'manifest.json');
+    if (!existsSync(manifestPath))
+        return null;
+    const parsed = JSON.parse(await readFile(manifestPath, 'utf-8'));
+    const result = AtlasMemoryManifestSchema.safeParse(parsed);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const path = issue.path.length > 0 ? issue.path.join('.') : '<root>';
+        throw new Error(`${manifestPath} is invalid at ${path}: ${issue.message}`);
+    }
+    return result.data;
+}
+export async function writeAtlasMemoryManifest(baseDir, manifest) {
+    const result = AtlasMemoryManifestSchema.safeParse(manifest);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const path = issue.path.length > 0 ? issue.path.join('.') : '<root>';
+        throw new Error(`manifest is invalid at ${path}: ${issue.message}`);
+    }
+    await mkdir(baseDir, { recursive: true });
+    const manifestPath = join(baseDir, 'manifest.json');
+    const content = `${JSON.stringify(result.data, null, 2)}\n`;
+    const tmpPath = join(baseDir, `.manifest.json.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
+    await writeFile(tmpPath, content, 'utf-8');
+    await rename(tmpPath, manifestPath);
+    return manifestPath;
+}
+export async function pruneSqliteOnlyPlaybooks(library, canonicalPlaybookIds) {
+    const canonical = new Set(canonicalPlaybookIds);
+    const all = await library.getAll();
+    const sqliteOnly = all.filter((playbook) => !canonical.has(playbook.id));
+    for (const playbook of sqliteOnly) {
+        await library.delete(playbook.id);
+    }
+    return {
+        pruned: sqliteOnly.length,
+        retained: all.length - sqliteOnly.length,
+        ids: sqliteOnly.map((playbook) => playbook.id),
+    };
+}
+export function playbookToSkillMarkdown(playbook, options = {}) {
+    const frontmatter = buildSkillFrontmatter(playbook, options);
+    const yaml = stringifyYaml(frontmatter, {
+        lineWidth: 120,
+        defaultKeyType: 'PLAIN',
+        defaultStringType: 'PLAIN',
+    });
+    return `---\n${yaml}---\n\n${buildSkillBody(playbook)}`;
+}
+export function skillMarkdownToPlaybook(markdown) {
+    return parsePlaybookSkillMarkdown(markdown).playbook;
+}
+export function parsePlaybookSkillMarkdown(markdown) {
+    const match = markdown.match(FRONTMATTER_REGEX);
+    if (!match) {
+        throw new Error('SKILL.md is missing YAML frontmatter');
+    }
+    const [, yamlBlock, body] = match;
+    const parsed = parseYaml(yamlBlock);
+    if (!isRecord(parsed)) {
+        throw new Error('SKILL.md frontmatter must be a YAML object');
+    }
+    const ccore = parsed.ccore;
+    if (!isRecord(ccore)) {
+        throw new Error('SKILL.md frontmatter is missing required ccore block');
+    }
+    if (ccore.kind !== 'procedural') {
+        throw new Error('SKILL.md ccore.kind must be "procedural"');
+    }
+    return {
+        playbook: playbookFromFrontmatter(parsed, ccore),
+        frontmatter: parsed,
+        body: body.trim(),
+    };
+}
+export async function exportPlaybookAsCanonicalSkill(playbook, outputDir, options = {}) {
+    const content = playbookToSkillMarkdown(playbook, options);
+    const dirName = canonicalPlaybookDirName(playbook);
+    const skillDir = join(outputDir, dirName);
+    if (!existsSync(skillDir)) {
+        await mkdir(skillDir, { recursive: true });
+    }
+    const path = join(skillDir, 'SKILL.md');
+    if (existsSync(path)) {
+        const existing = skillMarkdownToPlaybook(await readFile(path, 'utf-8'));
+        if (existing.id !== playbook.id) {
+            throw new Error(`Canonical skill directory collision: ${dirName} already contains playbook ${existing.id}`);
+        }
+    }
+    await writeFile(path, content, 'utf-8');
+    return {
+        playbookId: playbook.id,
+        dirName,
+        path,
+        content,
+    };
+}
+export async function exportPlaybooksAsCanonicalSkills(library, outputDir, options = {}) {
+    const result = {
+        exported: 0,
+        errors: [],
+        skills: [],
+    };
+    if (!existsSync(outputDir)) {
+        await mkdir(outputDir, { recursive: true });
+    }
+    const playbooks = await library.getAll();
+    const idsByDir = new Map();
+    for (const playbook of playbooks) {
+        const dirName = canonicalPlaybookDirName(playbook);
+        const ids = idsByDir.get(dirName) ?? [];
+        ids.push(playbook.id);
+        idsByDir.set(dirName, ids);
+    }
+    for (const playbook of playbooks) {
+        try {
+            const dirName = canonicalPlaybookDirName(playbook);
+            const collidingIds = idsByDir.get(dirName) ?? [];
+            if (new Set(collidingIds).size > 1) {
+                throw new Error(`Canonical skill directory collision: ${dirName} maps ids ${collidingIds.join(', ')}`);
+            }
+            const exported = await exportPlaybookAsCanonicalSkill(playbook, outputDir, options);
+            result.skills.push(exported);
+            result.exported++;
+        }
+        catch (error) {
+            result.errors.push({
+                playbook: playbook.id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return result;
+}
+export async function validateCanonicalPlaybookFiles(rootDir) {
+    const result = {
+        rootDir,
+        valid: 0,
+        invalid: [],
+        duplicateIds: [],
+        playbooks: [],
+    };
+    if (!existsSync(rootDir)) {
+        result.invalid.push({ path: rootDir, message: 'Directory does not exist' });
+        return result;
+    }
+    const skillPaths = await findSkillMarkdownFiles(rootDir);
+    const pathsById = new Map();
+    for (const path of skillPaths) {
+        try {
+            const content = await readFile(path, 'utf-8');
+            const parsed = parsePlaybookSkillMarkdown(content);
+            result.valid++;
+            result.playbooks.push({
+                id: parsed.playbook.id,
+                name: parsed.playbook.name,
+                path,
+            });
+            const existing = pathsById.get(parsed.playbook.id) ?? [];
+            existing.push(path);
+            pathsById.set(parsed.playbook.id, existing);
+        }
+        catch (error) {
+            result.invalid.push({
+                path,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    for (const [id, paths] of pathsById.entries()) {
+        if (paths.length > 1) {
+            result.duplicateIds.push({ id, paths });
+        }
+    }
+    return result;
+}
+/**
+ * Overlay the rebuildable operational-state sidecar (.ccore/state.json, written
+ * by ProceduralMemoryFileStore.writeState) onto a playbook parsed from SKILL.md.
+ * The stable SKILL.md omits confidence/counters, so without this a reindex resets
+ * them to defaults; with it, SQLite operational state is fully reconstructable
+ * from files ("delete the DB, lose nothing").
+ */
+async function applyStateSidecar(playbook, skillMdPath) {
+    const statePath = join(dirname(skillMdPath), '.ccore', 'state.json');
+    if (!existsSync(statePath))
+        return;
+    try {
+        const raw = JSON.parse(await readFile(statePath, 'utf-8'));
+        if (typeof raw.id === 'string' && raw.id !== playbook.id)
+            return; // dir/id mismatch guard
+        if (typeof raw.confidence === 'number')
+            playbook.confidence = raw.confidence;
+        if (typeof raw.successCount === 'number')
+            playbook.evolution.successCount = raw.successCount;
+        if (typeof raw.failureCount === 'number')
+            playbook.evolution.failureCount = raw.failureCount;
+        if (typeof raw.consolidationStrength === 'number') {
+            playbook.evolution.consolidationStrength = raw.consolidationStrength;
+        }
+        if (typeof raw.domainBreadth === 'number')
+            playbook.evolution.domainBreadth = raw.domainBreadth;
+        if (typeof raw.lastUsed === 'string')
+            playbook.evolution.lastUsed = new Date(raw.lastUsed);
+    }
+    catch {
+        // Corrupt/unreadable sidecar — keep the SKILL.md-parsed defaults.
+    }
+}
+export async function reindexCanonicalPlaybookFiles(library, rootDir) {
+    const result = {
+        rootDir,
+        indexed: 0,
+        skipped: [],
+        duplicateIds: [],
+        playbooks: [],
+        rootMissing: false,
+    };
+    if (!existsSync(rootDir)) {
+        // Cold store: nothing written yet. Not a warning — flagged for a debug log.
+        result.rootMissing = true;
+        return result;
+    }
+    const skillPaths = await findSkillMarkdownFiles(rootDir);
+    const parsed = [];
+    const pathsById = new Map();
+    for (const path of skillPaths) {
+        try {
+            const content = await readFile(path, 'utf-8');
+            const playbook = skillMarkdownToPlaybook(content);
+            await applyStateSidecar(playbook, path);
+            parsed.push({ path, playbook });
+            const paths = pathsById.get(playbook.id) ?? [];
+            paths.push(path);
+            pathsById.set(playbook.id, paths);
+        }
+        catch (error) {
+            result.skipped.push({
+                path,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    const duplicateIds = new Set();
+    for (const [id, paths] of pathsById.entries()) {
+        if (paths.length > 1) {
+            duplicateIds.add(id);
+            result.duplicateIds.push({ id, paths });
+            for (const path of paths) {
+                result.skipped.push({ path, id, message: `Duplicate playbook id: ${id}` });
+            }
+        }
+    }
+    const candidates = parsed.filter(({ playbook }) => !duplicateIds.has(playbook.id));
+    const candidateIds = new Set(candidates.map(({ playbook }) => playbook.id));
+    const sorted = sortPlaybooksForParents(candidates);
+    for (const item of sorted) {
+        const parentId = item.playbook.parentPlaybookId;
+        if (parentId && !candidateIds.has(parentId) && !(await library.get(parentId))) {
+            result.skipped.push({
+                path: item.path,
+                id: item.playbook.id,
+                message: `Missing parent playbook id: ${parentId}`,
+            });
+            continue;
+        }
+        try {
+            await library.upsertCanonical(item.playbook);
+            result.indexed++;
+            result.playbooks.push({
+                id: item.playbook.id,
+                name: item.playbook.name,
+                path: item.path,
+            });
+        }
+        catch (error) {
+            result.skipped.push({
+                path: item.path,
+                id: item.playbook.id,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return result;
+}
+/**
+ * Reindex a single canonical SKILL.md into the derived cache — the file-granular
+ * counterpart of {@link reindexCanonicalPlaybookFiles}, used by the filesystem
+ * cascade when a watcher reports one file changed. Parses the file, overlays the
+ * operational-state sidecar, and upserts the derived row (no structural write, so
+ * it never re-triggers the watcher). Throws on a malformed file so the caller can
+ * park the queue entry; returns the indexed playbook on success.
+ */
+export async function reindexCanonicalPlaybookFile(library, path) {
+    const content = await readFile(path, 'utf-8');
+    const playbook = skillMarkdownToPlaybook(content);
+    await applyStateSidecar(playbook, path);
+    await library.upsertCanonical(playbook);
+    return playbook;
+}
+export function canonicalPlaybookDirName(playbook) {
+    return slugify(playbook.name || playbook.id);
+}
+function buildSkillFrontmatter(playbook, options) {
+    const baseFrontmatter = options.baseFrontmatter ?? {};
+    const baseCcore = isRecord(baseFrontmatter.ccore) ? baseFrontmatter.ccore : {};
+    const merged = {
+        ...baseFrontmatter,
+        id: playbook.id,
+        name: playbook.name,
+        version: playbook.evolution.version,
+        description: buildDescription(playbook),
+        status: 'active',
+        tags: playbook.applicability.domains,
+        ccore: {
+            ...baseCcore,
+            ...toCcoreFrontmatter(playbook, options.includeOperationalState ?? false),
+        },
+    };
+    if (playbook.userInvocable !== undefined) {
+        merged['user-invocable'] = playbook.userInvocable;
+    }
+    return omitUndefined(merged);
+}
+function sortPlaybooksForParents(items) {
+    const byId = new Map(items.map((item) => [item.playbook.id, item]));
+    const visited = new Set();
+    const visiting = new Set();
+    const sorted = [];
+    const visit = (item) => {
+        if (visited.has(item.playbook.id))
+            return;
+        if (visiting.has(item.playbook.id)) {
+            sorted.push(item);
+            visited.add(item.playbook.id);
+            return;
+        }
+        visiting.add(item.playbook.id);
+        const parentId = item.playbook.parentPlaybookId;
+        const parent = parentId ? byId.get(parentId) : undefined;
+        if (parent)
+            visit(parent);
+        visiting.delete(item.playbook.id);
+        if (!visited.has(item.playbook.id)) {
+            visited.add(item.playbook.id);
+            sorted.push(item);
+        }
+    };
+    for (const item of items)
+        visit(item);
+    return sorted;
+}
+async function findSkillMarkdownFiles(rootDir) {
+    const found = [];
+    const entries = await readdir(rootDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const path = join(rootDir, entry.name);
+        if (entry.isDirectory()) {
+            if (IGNORED_SKILL_SCAN_DIRS.has(entry.name))
+                continue;
+            found.push(...(await findSkillMarkdownFiles(path)));
+            continue;
+        }
+        if (entry.isFile() && entry.name === 'SKILL.md') {
+            const s = await stat(path);
+            if (s.isFile())
+                found.push(path);
+        }
+    }
+    return found.sort();
+}
+function toCcoreFrontmatter(playbook, includeOperationalState) {
+    const evolution = includeOperationalState
+        ? {
+            version: playbook.evolution.version,
+            createdFrom: playbook.evolution.createdFrom,
+            failures: (playbook.evolution.failures ?? []).map((failure) => ({
+                ...failure,
+                timestamp: toIso(failure.timestamp),
+            })),
+            refinements: (playbook.evolution.refinements ?? []).map((refinement) => ({
+                ...refinement,
+                addedAt: toIso(refinement.addedAt),
+            })),
+            successCount: playbook.evolution.successCount,
+            failureCount: playbook.evolution.failureCount,
+            lastUsed: playbook.evolution.lastUsed ? toIso(playbook.evolution.lastUsed) : undefined,
+            consolidationStrength: playbook.evolution.consolidationStrength,
+            domainBreadth: playbook.evolution.domainBreadth,
+        }
+        : {
+            version: playbook.evolution.version,
+            createdFrom: playbook.evolution.createdFrom,
+            refinements: (playbook.evolution.refinements ?? []).map((refinement) => ({
+                ...refinement,
+                addedAt: toIso(refinement.addedAt),
+            })),
+        };
+    return omitUndefined({
+        kind: 'procedural',
+        schemaVersion: CCORE_SCHEMA_VERSION,
+        id: playbook.id,
+        applicability: playbook.applicability,
+        guidance: playbook.guidance,
+        verification: playbook.verification,
+        evolution,
+        provenance: playbook.provenance
+            ? {
+                ...playbook.provenance,
+                recordedAt: toIso(playbook.provenance.recordedAt),
+            }
+            : undefined,
+        confidence: includeOperationalState ? playbook.confidence : undefined,
+        complexity: playbook.complexity,
+        estimatedEffort: playbook.estimatedEffort,
+        createdAt: toIso(playbook.createdAt),
+        updatedAt: toIso(playbook.updatedAt),
+        parentPlaybookId: playbook.parentPlaybookId,
+        userInvocable: playbook.userInvocable,
+        publishMetadata: playbook.publishMetadata,
+        skillLevel: playbook.skillLevel,
+    });
+}
+function buildSkillBody(playbook) {
+    const sections = [];
+    sections.push(`# ${titleCase(playbook.name)}`);
+    sections.push('');
+    if (playbook.applicability.situations.length > 0) {
+        sections.push('## When To Use');
+        sections.push('');
+        sections.push(...playbook.applicability.situations.map((s) => `- ${s}`));
+        sections.push('');
+    }
+    if (playbook.applicability.antiPatterns.length > 0) {
+        sections.push('## When Not To Use');
+        sections.push('');
+        sections.push(...playbook.applicability.antiPatterns.map((s) => `- ${s}`));
+        sections.push('');
+    }
+    sections.push('## Procedure');
+    sections.push('');
+    sections.push(playbook.guidance.strategy);
+    if (playbook.guidance.tactics.length > 0) {
+        sections.push('');
+        sections.push(...playbook.guidance.tactics.map((t) => `- ${t}`));
+    }
+    if (playbook.guidance.steps && playbook.guidance.steps.length > 0) {
+        sections.push('');
+        sections.push(...playbook.guidance.steps.map((s, i) => `${i + 1}. ${s}`));
+    }
+    sections.push('');
+    if (playbook.guidance.codeExample) {
+        sections.push('## Example');
+        sections.push('');
+        sections.push('```');
+        sections.push(playbook.guidance.codeExample);
+        sections.push('```');
+        sections.push('');
+    }
+    sections.push('## Verification');
+    sections.push('');
+    if (playbook.verification.successIndicators.length > 0) {
+        sections.push('Success:');
+        sections.push(...playbook.verification.successIndicators.map((s) => `- ${s}`));
+        sections.push('');
+    }
+    if (playbook.verification.failureIndicators.length > 0) {
+        sections.push('Failure:');
+        sections.push(...playbook.verification.failureIndicators.map((s) => `- ${s}`));
+        sections.push('');
+    }
+    if (playbook.verification.rollbackStrategy) {
+        sections.push(`Rollback: ${playbook.verification.rollbackStrategy}`);
+        sections.push('');
+    }
+    if ((playbook.evolution.refinements ?? []).length > 0) {
+        sections.push('## Notes');
+        sections.push('');
+        for (const refinement of playbook.evolution.refinements ?? []) {
+            sections.push(`- ${refinement.context}: ${refinement.addition}`);
+        }
+        sections.push('');
+    }
+    return sections.join('\n').trimEnd() + '\n';
+}
+function playbookFromFrontmatter(frontmatter, ccore) {
+    const id = requireString(ccore.id ?? frontmatter.id, 'ccore.id');
+    const name = requireString(frontmatter.name ?? id, 'name');
+    const createdAt = parseDate(ccore.createdAt, 'ccore.createdAt');
+    const updatedAt = parseDate(ccore.updatedAt, 'ccore.updatedAt');
+    const evolution = parseEvolution(ccore.evolution, frontmatter.version);
+    return omitUndefined({
+        id,
+        name,
+        applicability: requireRecord(ccore.applicability, 'ccore.applicability'),
+        guidance: requireRecord(ccore.guidance, 'ccore.guidance'),
+        verification: requireRecord(ccore.verification, 'ccore.verification'),
+        evolution,
+        provenance: parseProvenance(ccore.provenance),
+        confidence: optionalNumber(ccore.confidence) ?? 0.3,
+        complexity: parseComplexity(ccore.complexity),
+        estimatedEffort: requireNumber(ccore.estimatedEffort, 'ccore.estimatedEffort'),
+        createdAt,
+        updatedAt,
+        parentPlaybookId: optionalString(ccore.parentPlaybookId),
+        userInvocable: optionalBoolean(ccore.userInvocable ?? frontmatter['user-invocable']),
+        publishMetadata: isRecord(ccore.publishMetadata) ? ccore.publishMetadata : undefined,
+        skillLevel: parseSkillLevel(ccore.skillLevel),
+    });
+}
+function parseEvolution(value, fallbackVersion) {
+    const evolution = requireRecord(value, 'ccore.evolution');
+    const failures = optionalArray(evolution.failures).map((failure, index) => {
+        const row = requireRecord(failure, `ccore.evolution.failures[${index}]`);
+        return {
+            trajectoryId: requireString(row.trajectoryId, `ccore.evolution.failures[${index}].trajectoryId`),
+            context: requireString(row.context, `ccore.evolution.failures[${index}].context`),
+            failureMode: requireString(row.failureMode, `ccore.evolution.failures[${index}].failureMode`),
+            timestamp: parseDate(row.timestamp, `ccore.evolution.failures[${index}].timestamp`),
+        };
+    });
+    const refinements = optionalArray(evolution.refinements).map((refinement, index) => {
+        const row = requireRecord(refinement, `ccore.evolution.refinements[${index}]`);
+        return {
+            context: requireString(row.context, `ccore.evolution.refinements[${index}].context`),
+            addition: requireString(row.addition, `ccore.evolution.refinements[${index}].addition`),
+            source: parseRefinementSource(row.source),
+            addedAt: parseDate(row.addedAt, `ccore.evolution.refinements[${index}].addedAt`),
+        };
+    });
+    return omitUndefined({
+        version: requireString(evolution.version ?? fallbackVersion, 'ccore.evolution.version'),
+        createdFrom: optionalStringArray(evolution.createdFrom, 'ccore.evolution.createdFrom'),
+        failures,
+        refinements,
+        successCount: optionalNumber(evolution.successCount) ?? 0,
+        failureCount: optionalNumber(evolution.failureCount) ?? 0,
+        lastUsed: evolution.lastUsed
+            ? parseDate(evolution.lastUsed, 'ccore.evolution.lastUsed')
+            : undefined,
+        consolidationStrength: optionalNumber(evolution.consolidationStrength),
+        domainBreadth: optionalNumber(evolution.domainBreadth),
+    });
+}
+function parseProvenance(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const provenance = requireRecord(value, 'ccore.provenance');
+    return omitUndefined({
+        origin: parseOrigin(provenance.origin),
+        extractionMethod: parseExtractionMethod(provenance.extractionMethod),
+        fallbackReason: optionalString(provenance.fallbackReason),
+        template: optionalString(provenance.template),
+        templateVersion: optionalString(provenance.templateVersion),
+        sourceFile: optionalString(provenance.sourceFile),
+        importedFrom: optionalString(provenance.importedFrom),
+        curatedBy: optionalString(provenance.curatedBy),
+        recordedAt: parseDate(provenance.recordedAt, 'ccore.provenance.recordedAt'),
+        creationCostUsd: optionalNumber(provenance.creationCostUsd),
+    });
+}
+function buildDescription(playbook) {
+    const lead = playbook.applicability.situations[0] ?? playbook.guidance.strategy;
+    const triggers = playbook.applicability.triggers.slice(0, 5);
+    const triggerText = triggers.length > 0 ? ` Use when ${triggers.map((t) => `"${t}"`).join(', ')}.` : '';
+    const domains = playbook.applicability.domains.length > 0
+        ? ` Domains: ${playbook.applicability.domains.join(', ')}.`
+        : '';
+    const full = `${lead}${triggerText}${domains}`;
+    return full.length <= 1024 ? full : `${full.slice(0, 1021)}...`;
+}
+function slugify(value) {
+    return (value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'playbook');
+}
+function titleCase(value) {
+    return value
+        .split(/[-_\s]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(' ');
+}
+function toIso(value) {
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new Error('Cannot serialize invalid date to SKILL.md');
+    }
+    return date.toISOString();
+}
+function parseDate(value, path) {
+    if (value instanceof Date)
+        return value;
+    if (typeof value !== 'string' && typeof value !== 'number') {
+        throw new Error(`${path} must be a date string`);
+    }
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime())) {
+        throw new Error(`${path} must be a valid date`);
+    }
+    return parsed;
+}
+function parseComplexity(value) {
+    if (value === 'simple' || value === 'moderate' || value === 'complex')
+        return value;
+    throw new Error('ccore.complexity must be simple, moderate, or complex');
+}
+function parseSkillLevel(value) {
+    if (value === 'planning' ||
+        value === 'functional' ||
+        value === 'atomic-check' ||
+        value === 'executable-bundle') {
+        return value;
+    }
+    if (value === undefined || value === null)
+        return undefined;
+    throw new Error('ccore.skillLevel has an unsupported value');
+}
+function parseOrigin(value) {
+    if (value === 'extracted' || value === 'curated' || value === 'imported' || value === 'manual') {
+        return value;
+    }
+    throw new Error('ccore.provenance.origin has an unsupported value');
+}
+function parseExtractionMethod(value) {
+    if (value === 'heuristic' ||
+        value === 'trajectory-distiller' ||
+        value === 'workspace-agent' ||
+        value === 'gepa') {
+        return value;
+    }
+    if (value === undefined || value === null)
+        return undefined;
+    throw new Error('ccore.provenance.extractionMethod has an unsupported value');
+}
+function parseRefinementSource(value) {
+    if (value === 'failure' || value === 'success' || value === 'manual')
+        return value;
+    throw new Error('refinement.source has an unsupported value');
+}
+function stringArray(value, path) {
+    const array = requireArray(value, path);
+    for (const item of array) {
+        if (typeof item !== 'string')
+            throw new Error(`${path} must contain only strings`);
+    }
+    return array;
+}
+function optionalStringArray(value, path) {
+    if (value === undefined || value === null)
+        return [];
+    return stringArray(value, path);
+}
+function optionalArray(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error('optional array field must be an array');
+    return value;
+}
+function requireArray(value, path) {
+    if (!Array.isArray(value))
+        throw new Error(`${path} must be an array`);
+    return value;
+}
+function requireRecord(value, path) {
+    if (!isRecord(value))
+        throw new Error(`${path} must be an object`);
+    return value;
+}
+function requireString(value, path) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`${path} must be a non-empty string`);
+    }
+    return value;
+}
+function optionalString(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new Error('optional string field must be a string');
+    return value;
+}
+function requireNumber(value, path) {
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+        throw new Error(`${path} must be a number`);
+    }
+    return value;
+}
+function optionalNumber(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+        throw new Error('optional number field must be a number');
+    }
+    return value;
+}
+function optionalBoolean(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'boolean')
+        throw new Error('optional boolean field must be a boolean');
+    return value;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function omitUndefined(obj) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (value !== undefined)
+            result[key] = value;
+    }
+    return result;
+}
+//# sourceMappingURL=procedural-skill.js.map