@rasensio/aidlc 0.1.0

package/dist/commands/transition.js

@@ -0,0 +1,353 @@
+/**
+ * `aidlc transition <instance>` command — evaluate gates and advance phase.
+ *
+ * Behavior:
+ * - Load instance state, phase states, and resolve template.
+ * - Call `evaluateTransition(state, phaseStates, template, actor, findings, override)`.
+ * - Call `nextStep(state, phaseStates, template)` to determine the target phase.
+ * - If transition is allowed:
+ *   - Update current_phase in instance.yaml to the next phase.
+ *   - Update source phase status to 'complete'.
+ *   - Update target phase status to 'in-progress'.
+ *   - Append a TransitionRecord to transitions.log.
+ *   - Fire on-phase-exit and on-phase-enter events.
+ *   - Print success message.
+ * - If blocked: print all violations, exit code 1.
+ *
+ * Options:
+ *   --override    Override ownership gate
+ *   --json        Output result as JSON
+ *
+ * Requirements: 3.6, 6.6, 11.5, 5.5
+ *
+ * @module
+ */
+import { Command } from 'commander';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { evaluateTransition, nextStep } from '../core/lifecycle.js';
+import { loadSnapshot, saveSnapshot } from '../state/snapshot-store.js';
+import { appendTransition } from '../state/transition-log.js';
+import { loadTemplates, resolveTemplate } from '../core/template-resolver.js';
+import { emit, loadActionsConfig } from '../events/event-bus.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the package root directory.
+ */
+function getPackageRoot() {
+    const thisFile = fileURLToPath(import.meta.url);
+    return resolve(thisFile, '..', '..', '..');
+}
+/**
+ * Load all templates: built-in from the package + custom from the project.
+ */
+function loadAllTemplates(packageRoot, projectRoot) {
+    const builtInDir = join(packageRoot, 'templates');
+    const customDir = join(projectRoot, '.aidlc', 'templates');
+    const templates = loadTemplates(builtInDir);
+    if (existsSync(customDir)) {
+        const custom = loadTemplates(customDir);
+        for (const [name, tpl] of custom) {
+            templates.set(name, tpl);
+        }
+    }
+    return templates;
+}
+/**
+ * Load all phase state files for a given instance.
+ */
+function loadPhaseStates(stateDir, instanceName) {
+    const phases = new Map();
+    const instanceDir = join(stateDir, instanceName);
+    let entries;
+    try {
+        entries = readdirSync(instanceDir);
+    }
+    catch {
+        return phases;
+    }
+    const phaseFiles = entries.filter((f) => f.startsWith('phase-') && f.endsWith('.yaml'));
+    for (const file of phaseFiles) {
+        try {
+            const phaseState = loadSnapshot(stateDir, instanceName, file);
+            if (phaseState && phaseState.phase) {
+                phases.set(phaseState.phase, phaseState);
+            }
+        }
+        catch {
+            // Skip corrupt phase files
+        }
+    }
+    return phases;
+}
+/**
+ * Determine the actor identity from environment variables.
+ * Uses USER, USERNAME, or falls back to 'unknown'.
+ */
+function getActorIdentity() {
+    return (process.env.USER ||
+        process.env.USERNAME ||
+        'unknown');
+}
+/**
+ * Parse review findings from `<artifact>.review.md` files in the instance directory.
+ *
+ * Looks for files matching `*.review.md` and parses them into a FindingsIndex.
+ * Each finding is parsed from markdown heading format:
+ *   ## <id>: <title> [<severity>] [<status>]
+ */
+function loadFindings(stateDir, instanceName) {
+    const findings = {};
+    const instanceDir = join(stateDir, instanceName);
+    let entries;
+    try {
+        entries = readdirSync(instanceDir);
+    }
+    catch {
+        return findings;
+    }
+    const reviewFiles = entries.filter((f) => f.endsWith('.review.md'));
+    for (const file of reviewFiles) {
+        const artifactName = file.replace('.review.md', '');
+        const filePath = join(instanceDir, file);
+        try {
+            const content = readFileSync(filePath, 'utf8');
+            const parsed = parseFindingsFromMarkdown(content);
+            if (parsed.length > 0) {
+                findings[artifactName] = parsed;
+            }
+        }
+        catch {
+            // Skip unparseable review files
+        }
+    }
+    return findings;
+}
+/**
+ * Parse findings from markdown content.
+ *
+ * Expected format:
+ *   ## F1: Title [critical] [open]
+ *   - Section: ...
+ *   - Issue: ...
+ *   - Suggested resolution: ...
+ */
+function parseFindingsFromMarkdown(content) {
+    const findings = [];
+    const headingPattern = /^## ([\w-]+): (.+?) \[(critical|major|minor|info)\] \[(open|resolved|accepted-risk|rejected)\]/gm;
+    let match;
+    while ((match = headingPattern.exec(content)) !== null) {
+        findings.push({
+            id: match[1],
+            title: match[2],
+            severity: match[3],
+            status: match[4],
+        });
+    }
+    return findings;
+}
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+/**
+ * Register the `aidlc transition` command on the given commander program.
+ */
+export function registerTransition(program) {
+    program
+        .command('transition')
+        .description('Evaluate gates and advance to the next phase')
+        .argument('<instance>', 'Lifecycle instance name')
+        .option('--override', 'Override ownership gate')
+        .option('--json', 'Output result as JSON')
+        .action((instance, opts) => {
+        runTransition(instance, opts);
+    });
+}
+// ---------------------------------------------------------------------------
+// Core logic
+// ---------------------------------------------------------------------------
+function runTransition(instanceArg, opts) {
+    const packageRoot = getPackageRoot();
+    const projectRoot = process.cwd();
+    const stateDir = join(projectRoot, '.aidlc', 'state');
+    // Check instance exists
+    const instanceDir = join(stateDir, instanceArg);
+    if (!existsSync(instanceDir)) {
+        process.stderr.write(`Error: instance '${instanceArg}' not found.\n`);
+        process.exitCode = 1;
+        return;
+    }
+    // Load instance state
+    let instanceState;
+    try {
+        instanceState = loadSnapshot(stateDir, instanceArg, 'instance.yaml');
+    }
+    catch (err) {
+        process.stderr.write(`Error: failed to load instance state: ${err.message}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    // Load phase states
+    const phaseStates = loadPhaseStates(stateDir, instanceArg);
+    // Resolve template
+    const allTemplates = loadAllTemplates(packageRoot, projectRoot);
+    const rawTemplate = allTemplates.get(instanceState.template);
+    if (!rawTemplate) {
+        process.stderr.write(`Error: template '${instanceState.template}' not found.\n`);
+        process.exitCode = 1;
+        return;
+    }
+    let resolvedTemplate;
+    try {
+        resolvedTemplate = resolveTemplate(rawTemplate, allTemplates);
+    }
+    catch (err) {
+        process.stderr.write(`Error: failed to resolve template: ${err.message}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    // Determine actor identity
+    const actor = getActorIdentity();
+    // Load findings for review gate evaluation
+    const findings = loadFindings(stateDir, instanceArg);
+    // Evaluate transition gates
+    const result = evaluateTransition(instanceState, phaseStates, resolvedTemplate, actor, findings, opts.override);
+    if (!result.allowed) {
+        // Transition blocked — print violations
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({ allowed: false, violations: result.violations }, null, 2) + '\n');
+        }
+        else {
+            process.stdout.write(`✗ Transition blocked for instance "${instanceArg}"\n\n`);
+            process.stdout.write(`  Violations:\n`);
+            for (const v of result.violations) {
+                process.stdout.write(`    [${v.gate}] ${v.reason}\n`);
+            }
+            process.stdout.write('\n');
+        }
+        process.exitCode = 1;
+        return;
+    }
+    // Transition allowed — determine the next phase
+    const next = nextStep(instanceState, phaseStates, resolvedTemplate);
+    if (next.kind === 'complete') {
+        // All phases are done — nothing to transition to
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({ allowed: true, complete: true }, null, 2) + '\n');
+        }
+        else {
+            process.stdout.write(`✓ Instance "${instanceArg}" is already complete — no further transitions.\n`);
+        }
+        return;
+    }
+    // Determine the target phase
+    const sourcePhase = instanceState.current_phase;
+    const targetPhase = next.kind === 'phase' ? next.phase : sourcePhase;
+    // Only perform a phase transition if we're moving to a new phase
+    if (next.kind === 'artifact') {
+        // Still in the same phase — artifacts remain, not a phase-level transition
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({
+                allowed: true,
+                transition: false,
+                reason: `phase "${sourcePhase}" still has incomplete artifacts`,
+                next_artifact: next.artifact,
+            }, null, 2) + '\n');
+        }
+        else {
+            process.stdout.write(`✓ Gates passed for "${instanceArg}" but phase "${sourcePhase}" still has work remaining.\n` +
+                `  Next artifact: ${next.artifact}\n`);
+        }
+        return;
+    }
+    // Phase transition: source → target
+    const now = new Date().toISOString();
+    // Update source phase: mark as 'complete'
+    const sourcePhaseState = phaseStates.get(sourcePhase);
+    if (sourcePhaseState) {
+        sourcePhaseState.status = 'complete';
+        sourcePhaseState.completed_at = now;
+        sourcePhaseState.completed_by = actor;
+        saveSnapshot(stateDir, instanceArg, `phase-${sourcePhase}.yaml`, sourcePhaseState);
+    }
+    // Update target phase: mark as 'in-progress'
+    const targetPhaseState = phaseStates.get(targetPhase);
+    if (targetPhaseState) {
+        targetPhaseState.status = 'in-progress';
+        targetPhaseState.entered_at = now;
+        saveSnapshot(stateDir, instanceArg, `phase-${targetPhase}.yaml`, targetPhaseState);
+    }
+    // Update instance.yaml: advance current_phase
+    instanceState.current_phase = targetPhase;
+    saveSnapshot(stateDir, instanceArg, 'instance.yaml', instanceState);
+    // Append transition record to transitions.log
+    const transitionRecord = {
+        at: now,
+        by: actor,
+        from: sourcePhase,
+        to: targetPhase,
+        type: 'normal',
+        criteria: buildSatisfiedCriteria(sourcePhaseState),
+    };
+    const logPath = join(stateDir, instanceArg, 'transitions.log');
+    appendTransition(logPath, transitionRecord);
+    // Fire on-phase-exit and on-phase-enter events
+    const actionsPath = join(projectRoot, '.aidlc', 'actions.yaml');
+    let actionsConfig = null;
+    try {
+        actionsConfig = loadActionsConfig(actionsPath);
+    }
+    catch {
+        // Non-fatal: proceed without actions
+    }
+    const exitPayload = {
+        event: 'on-phase-exit',
+        instance: instanceArg,
+        phase: sourcePhase,
+        template: instanceState.template,
+    };
+    emit(exitPayload, actionsConfig);
+    const enterPayload = {
+        event: 'on-phase-enter',
+        instance: instanceArg,
+        phase: targetPhase,
+        template: instanceState.template,
+    };
+    emit(enterPayload, actionsConfig);
+    // Output success message
+    if (opts.json) {
+        process.stdout.write(JSON.stringify({
+            allowed: true,
+            transition: true,
+            from: sourcePhase,
+            to: targetPhase,
+            at: now,
+            by: actor,
+        }, null, 2) + '\n');
+    }
+    else {
+        process.stdout.write(`✓ Transitioned "${instanceArg}": ${sourcePhase} → ${targetPhase}\n`);
+    }
+}
+/**
+ * Build a list of satisfied criteria descriptions from the completed phase state.
+ */
+function buildSatisfiedCriteria(phaseState) {
+    if (!phaseState)
+        return [];
+    const criteria = [];
+    // Record completed artifacts as satisfied criteria
+    for (const artifact of phaseState.artifacts) {
+        if (artifact.status === 'complete') {
+            criteria.push(`${artifact.name} complete`);
+        }
+    }
+    if (criteria.length === 0) {
+        criteria.push('all exit criteria satisfied');
+    }
+    return criteria;
+}
+//# sourceMappingURL=transition.js.map

package/dist/commands/transition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transition.js","sourceRoot":"","sources":["../../src/commands/transition.ts"],"names":[],"mappings":"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"}

package/dist/compile/adapters/claude-code.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Claude Code platform adapter.
+ *
+ * Generates an InstallPlan that installs AIDLC skills into Claude Code's native
+ * configuration structure:
+ *
+ * - Canonical skill bodies → `.aidlc/skills/<filename>`
+ * - Per-skill shims → `.claude/skills/aidlc-<name>/SKILL.md`
+ * - State protocol + context-doc references → `merge-block` into `CLAUDE.md`
+ *
+ * Capability map consumption follows the resolution precedence:
+ * 1. `skill.meta.native_mode_hint['claude-code']` → use it
+ * 2. Capability map entry covering the skill's phase → inject activation directive
+ * 3. Otherwise → full structured guidance, no native references
+ *
+ * Malformed/unknown-phase map → stderr warning + adapter proceeds capability-free (Req 18.7)
+ *
+ * Requirements: 1.1, 18.1, 18.7
+ *
+ * @module
+ */
+import type { PlatformAdapter } from '../../core/types.js';
+export declare const claudeCodeAdapter: PlatformAdapter;
+//# sourceMappingURL=claude-code.d.ts.map

package/dist/compile/adapters/claude-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../../src/compile/adapters/claude-code.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EACV,eAAe,EAShB,MAAM,qBAAqB,CAAC;AAoN7B,eAAO,MAAM,iBAAiB,EAAE,eA4G/B,CAAC"}

package/dist/compile/adapters/claude-code.js

@@ -0,0 +1,271 @@
+/**
+ * Claude Code platform adapter.
+ *
+ * Generates an InstallPlan that installs AIDLC skills into Claude Code's native
+ * configuration structure:
+ *
+ * - Canonical skill bodies → `.aidlc/skills/<filename>`
+ * - Per-skill shims → `.claude/skills/aidlc-<name>/SKILL.md`
+ * - State protocol + context-doc references → `merge-block` into `CLAUDE.md`
+ *
+ * Capability map consumption follows the resolution precedence:
+ * 1. `skill.meta.native_mode_hint['claude-code']` → use it
+ * 2. Capability map entry covering the skill's phase → inject activation directive
+ * 3. Otherwise → full structured guidance, no native references
+ *
+ * Malformed/unknown-phase map → stderr warning + adapter proceeds capability-free (Req 18.7)
+ *
+ * Requirements: 1.1, 18.1, 18.7
+ *
+ * @module
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Valid lifecycle phase names for capability map validation. */
+const VALID_PHASES = new Set([
+    'ideation',
+    'requirements',
+    'design',
+    'implementation',
+    'testing',
+    'deployment',
+    'maintenance',
+]);
+/** Maximum length for the skill name in Claude Code format. */
+const MAX_SKILL_NAME_LENGTH = 64;
+/** Pattern: lowercase, hyphens allowed, must match directory name. */
+const SKILL_NAME_RE = /^[a-z][a-z0-9-]*$/;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Validate and sanitize a capability map. Returns a clean map with only valid
+ * entries, or null if the map is entirely unusable. Emits warnings for problems.
+ */
+function validateCapabilityMap(caps, warnings) {
+    const phaseMap = new Map();
+    if (!caps.capabilities || typeof caps.capabilities !== 'object') {
+        warnings.push(`capability map for '${caps.platform}': malformed capabilities object; proceeding capability-free`);
+        return null;
+    }
+    let hasValidEntry = false;
+    for (const [capName, entry] of Object.entries(caps.capabilities)) {
+        if (!entry || typeof entry !== 'object') {
+            warnings.push(`capability map '${caps.platform}': capability '${capName}' is malformed; skipping`);
+            continue;
+        }
+        if (!Array.isArray(entry.phases)) {
+            warnings.push(`capability map '${caps.platform}': capability '${capName}' has invalid phases; skipping`);
+            continue;
+        }
+        if (!entry.activation || typeof entry.activation !== 'string') {
+            warnings.push(`capability map '${caps.platform}': capability '${capName}' missing activation text; skipping`);
+            continue;
+        }
+        for (const phase of entry.phases) {
+            if (!VALID_PHASES.has(phase)) {
+                warnings.push(`capability map '${caps.platform}': unknown phase '${phase}' in capability '${capName}'; skipping phase`);
+                continue;
+            }
+            phaseMap.set(phase, entry);
+            hasValidEntry = true;
+        }
+    }
+    return hasValidEntry ? phaseMap : null;
+}
+/**
+ * Derive the activation directive for a skill given the resolution precedence.
+ */
+function resolveActivation(skill, phaseMap) {
+    // 1. native_mode_hint for claude-code takes precedence
+    const hint = skill.meta.native_mode_hint?.['claude-code'];
+    if (hint) {
+        return hint;
+    }
+    // 2. Capability map entry covering the skill's phase
+    if (phaseMap) {
+        const entry = phaseMap.get(skill.meta.phase);
+        if (entry) {
+            return entry.activation;
+        }
+    }
+    // 3. No native reference — full structured guidance
+    return null;
+}
+/**
+ * Normalize a skill name for the Claude Code directory convention.
+ * Must be lowercase, hyphens allowed, ≤ 64 chars, matching the dir name.
+ */
+function normalizeSkillName(name) {
+    // Strip aidlc- prefix if already present, then re-add
+    let normalized = name.toLowerCase().replace(/[^a-z0-9-]/g, '-');
+    // Remove consecutive hyphens
+    normalized = normalized.replace(/-+/g, '-').replace(/^-|-$/g, '');
+    // Ensure aidlc- prefix
+    if (!normalized.startsWith('aidlc-')) {
+        normalized = `aidlc-${normalized}`;
+    }
+    // Truncate to max length
+    if (normalized.length > MAX_SKILL_NAME_LENGTH) {
+        normalized = normalized.slice(0, MAX_SKILL_NAME_LENGTH);
+    }
+    return normalized;
+}
+/**
+ * Derive the canonical skill filename for `.aidlc/skills/`.
+ */
+function canonicalFilename(skill) {
+    // Use the skill name directly, kebab-case + .md
+    return `${skill.meta.name}.md`;
+}
+/**
+ * Generate the SKILL.md shim content for Claude Code.
+ */
+function generateShimContent(skill, dirName, activation, canonicalPath) {
+    const lines = [];
+    // Frontmatter
+    lines.push('---');
+    lines.push(`name: ${dirName}`);
+    lines.push(`description: ${skill.meta.description}`);
+    lines.push('---');
+    lines.push('');
+    // Activation directive (if any)
+    if (activation) {
+        lines.push(activation);
+        lines.push('');
+    }
+    // Pointer to canonical skill body
+    lines.push(`Read \`.aidlc/skills/${canonicalPath}\` and follow its instructions.`);
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Generate the CLAUDE.md managed block content (state protocol + context refs).
+ */
+function generateClaudeMdBlock(ctx) {
+    const lines = [];
+    lines.push('# AIDLC Lifecycle');
+    lines.push('');
+    lines.push('## State Protocol');
+    lines.push('');
+    lines.push('- Lifecycle state lives in `.aidlc/state/<instance>/`');
+    lines.push('- Before mutating state, claim the instance (check `instance.yaml` claim field)');
+    lines.push('- After completing a phase, update `phase-<name>.yaml` and append to `transitions.log`');
+    lines.push('- Use `aidlc status` to see current progress across all instances');
+    lines.push('');
+    // Context doc references
+    const docNames = Object.keys(ctx.contextDocs);
+    if (docNames.length > 0) {
+        lines.push('## Context Documents');
+        lines.push('');
+        for (const name of docNames.sort()) {
+            lines.push(`- \`.aidlc/context/${ctx.contextDocs[name]}\` — ${name}`);
+        }
+        lines.push('');
+    }
+    // Guidance layer references
+    const layerNames = Object.keys(ctx.guidanceLayers);
+    if (layerNames.length > 0) {
+        lines.push('## Guidance Layers');
+        lines.push('');
+        for (const name of layerNames.sort()) {
+            lines.push(`- \`.aidlc/guidance/${ctx.guidanceLayers[name]}\` — ${name}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Adapter Implementation
+// ---------------------------------------------------------------------------
+export const claudeCodeAdapter = {
+    id: 'claude-code',
+    plan(skills, caps, ctx) {
+        const ops = [];
+        const warnings = [];
+        // Validate capability map
+        let phaseMap = null;
+        if (caps) {
+            phaseMap = validateCapabilityMap(caps, warnings);
+        }
+        // 1. Copy canonical skill bodies to .aidlc/skills/
+        for (const skill of skills) {
+            const filename = canonicalFilename(skill);
+            ops.push({
+                kind: 'create',
+                path: `.aidlc/skills/${filename}`,
+                content: skill.body,
+            });
+        }
+        // 2. Generate .claude/skills/aidlc-<name>/SKILL.md per skill
+        for (const skill of skills) {
+            const dirName = normalizeSkillName(skill.meta.name);
+            const activation = resolveActivation(skill, phaseMap);
+            const canonicalPath = canonicalFilename(skill);
+            const shimContent = generateShimContent(skill, dirName, activation, canonicalPath);
+            ops.push({
+                kind: 'create',
+                path: `.claude/skills/${dirName}/SKILL.md`,
+                content: shimContent,
+            });
+        }
+        // 3. Generate merge-block into CLAUDE.md with state protocol + context refs
+        const claudeMdContent = generateClaudeMdBlock(ctx);
+        ops.push({
+            kind: 'merge-block',
+            path: 'CLAUDE.md',
+            blockId: 'aidlc-lifecycle',
+            content: claudeMdContent,
+        });
+        return { ops, warnings };
+    },
+    validate(op) {
+        const errors = [];
+        const resultWarnings = [];
+        if (op.kind === 'merge-block') {
+            // Merge-block into CLAUDE.md — always valid structurally
+            return { valid: true, errors: [], warnings: [] };
+        }
+        // Validate .claude/skills/*/SKILL.md files
+        if (op.path.startsWith('.claude/skills/') && op.path.endsWith('/SKILL.md')) {
+            // Extract directory name from path
+            const segments = op.path.split('/');
+            const dirName = segments[2]; // .claude/skills/<dirName>/SKILL.md
+            // Validate directory name format
+            if (!dirName || !SKILL_NAME_RE.test(dirName)) {
+                errors.push(`skill directory name '${dirName}' must be lowercase with hyphens only`);
+            }
+            if (dirName && dirName.length > MAX_SKILL_NAME_LENGTH) {
+                errors.push(`skill directory name '${dirName}' exceeds ${MAX_SKILL_NAME_LENGTH} character limit`);
+            }
+            // Validate frontmatter presence and required fields
+            const content = op.content;
+            if (!content.startsWith('---\n')) {
+                errors.push('SKILL.md must begin with YAML frontmatter (---)');
+            }
+            else {
+                const endIdx = content.indexOf('\n---\n', 4);
+                if (endIdx === -1) {
+                    errors.push('SKILL.md has unclosed frontmatter');
+                }
+                else {
+                    const frontmatter = content.slice(4, endIdx);
+                    if (!frontmatter.includes('name:')) {
+                        errors.push("SKILL.md frontmatter missing required field 'name'");
+                    }
+                    if (!frontmatter.includes('description:')) {
+                        errors.push("SKILL.md frontmatter missing required field 'description'");
+                    }
+                    // Validate name matches directory name
+                    const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+                    if (nameMatch && nameMatch[1].trim() !== dirName) {
+                        errors.push(`SKILL.md frontmatter 'name' (${nameMatch[1].trim()}) must match directory name (${dirName})`);
+                    }
+                }
+            }
+        }
+        return { valid: errors.length === 0, errors, warnings: resultWarnings };
+    },
+};
+//# sourceMappingURL=claude-code.js.map