@rasensio/aidlc 0.1.0

package/dist/compile/install-plan.js

@@ -0,0 +1,112 @@
+/**
+ * Install plan executors for the AIDLC install pipeline.
+ *
+ * The plan/execute split ensures `--dry-run` is provably equivalent to a real
+ * install — same plan, different executor (Req 1.5).
+ *
+ * - `executePlan()`: applies a plan to the filesystem (creates dirs, writes files,
+ *   invokes `mergeBlock` for managed blocks).
+ * - `dryRunPlan()`: returns an identical report shape without touching the filesystem.
+ *
+ * Requirements: 1.2, 1.5, 17.2
+ *
+ * @module
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { mergeBlock } from './merger.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the final content for a file operation.
+ * For create/replace: the content itself.
+ * For merge-block: reads existing file (or empty) and calls mergeBlock.
+ */
+function resolveContent(op, rootDir) {
+    if (op.kind === 'merge-block') {
+        const absPath = join(rootDir, op.path);
+        let existing = '';
+        if (existsSync(absPath)) {
+            existing = readFileSync(absPath, 'utf8');
+        }
+        return mergeBlock(existing, op.blockId, op.content);
+    }
+    // op.kind === 'create' | 'replace'
+    return op.content;
+}
+/**
+ * Read existing file content from disk, returning empty string if not found.
+ */
+function readExisting(absPath) {
+    if (existsSync(absPath)) {
+        return readFileSync(absPath, 'utf8');
+    }
+    return '';
+}
+// ---------------------------------------------------------------------------
+// Real Executor
+// ---------------------------------------------------------------------------
+/**
+ * Apply an install plan to the filesystem.
+ *
+ * - `create`/`replace`: write file content, creating directories as needed.
+ * - `merge-block`: read existing file (or empty), call `mergeBlock()`, write result.
+ *
+ * Skips files whose computed content is identical to what's already on disk.
+ *
+ * @param plan - The install plan to execute.
+ * @param rootDir - Absolute path to the project root. All `op.path` entries are relative to this.
+ * @returns Report of what was written, skipped, and warnings.
+ */
+export function executePlan(plan, rootDir) {
+    const filesWritten = [];
+    const filesSkipped = [];
+    for (const op of plan.ops) {
+        const absPath = join(rootDir, op.path);
+        const newContent = resolveContent(op, rootDir);
+        const existingContent = readExisting(absPath);
+        if (existingContent === newContent) {
+            filesSkipped.push(op.path);
+            continue;
+        }
+        // Ensure directory exists
+        const dir = dirname(absPath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        writeFileSync(absPath, newContent, 'utf8');
+        filesWritten.push(op.path);
+    }
+    return { filesWritten, filesSkipped, warnings: [...plan.warnings] };
+}
+// ---------------------------------------------------------------------------
+// Dry-Run Executor
+// ---------------------------------------------------------------------------
+/**
+ * Simulate applying an install plan without writing to the filesystem.
+ *
+ * Computes the same content resolution as `executePlan()` to determine which
+ * files would be written or skipped, but never creates directories or writes files.
+ *
+ * @param plan - The install plan to simulate.
+ * @param rootDir - Absolute path to the project root.
+ * @returns Report of what would be written, skipped, and warnings.
+ */
+export function dryRunPlan(plan, rootDir) {
+    const filesWritten = [];
+    const filesSkipped = [];
+    for (const op of plan.ops) {
+        const absPath = join(rootDir, op.path);
+        const newContent = resolveContent(op, rootDir);
+        const existingContent = readExisting(absPath);
+        if (existingContent === newContent) {
+            filesSkipped.push(op.path);
+        }
+        else {
+            filesWritten.push(op.path);
+        }
+    }
+    return { filesWritten, filesSkipped, warnings: [...plan.warnings] };
+}
+//# sourceMappingURL=install-plan.js.map

package/dist/compile/install-plan.js.map

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

package/dist/compile/loaders.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Skill/guidance loaders with context placeholder resolution.
+ *
+ * - `loadSkills()` loads universal skill definitions from a directory.
+ * - `parseSkillFile()` parses a single skill file (YAML frontmatter + markdown body).
+ * - `resolvePlaceholders()` resolves `{{context:<doc>}}` and `{{guidance:<layer>}}` placeholders.
+ * - `loadGuidanceLayers()` loads guidance layers registered in `index.yaml`.
+ *
+ * Requirements: 2.1, 2.6, 1.8, 16.11
+ */
+import type { Skill, GuidanceLayer } from '../core/types.js';
+/**
+ * Parse a single skill file (YAML frontmatter delimited by `---` + markdown body).
+ *
+ * @param content - Raw file content.
+ * @param filePath - Path to the file (used in error messages).
+ * @returns Parsed `Skill` object.
+ * @throws If frontmatter is missing or invalid.
+ */
+export declare function parseSkillFile(content: string, filePath: string): Skill;
+/**
+ * Load all skill definitions from a directory.
+ *
+ * Reads all `.md` files in the given directory and parses them as skill files.
+ *
+ * @param skillsDir - Absolute path to the skills directory.
+ * @returns Array of parsed `Skill` objects.
+ */
+export declare function loadSkills(skillsDir: string): Skill[];
+/**
+ * Resolve `{{context:<doc-name>}}` placeholders in a string.
+ *
+ * - Small targets (≤ 2KB): inline the content directly.
+ * - Larger targets: emit a read-instruction reference.
+ * - Unresolvable: produce a warning and leave an `<!-- aidlc:unresolved <ref> -->` marker.
+ *
+ * @param body - The string containing placeholders.
+ * @param contextDir - Absolute path to the `.aidlc/context/` directory.
+ * @returns Object with resolved string and any warnings produced.
+ */
+export declare function resolvePlaceholders(body: string, contextDir: string): {
+    resolved: string;
+    warnings: string[];
+};
+/**
+ * Resolve `{{guidance:<layer-name>}}` placeholders in a string using loaded guidance layers.
+ *
+ * @param body - The string containing placeholders.
+ * @param layers - Already-loaded guidance layers to resolve against.
+ * @returns Object with resolved string and any warnings produced.
+ */
+export declare function resolveGuidancePlaceholders(body: string, layers: GuidanceLayer[]): {
+    resolved: string;
+    warnings: string[];
+};
+/** Result of loading guidance layers from disk. */
+export interface LoadedGuidance {
+    layers: GuidanceLayer[];
+    warnings: string[];
+}
+/**
+ * Load guidance layers from `.aidlc/guidance/` using `index.yaml` for registration.
+ *
+ * Loading rules (Req 16.10, 16.11):
+ * - Active = registered in index.yaml AND present on disk.
+ * - Registered but missing → warning, other layers still load.
+ * - Present but unregistered → silently inactive.
+ *
+ * @param guidanceDir - Absolute path to the `.aidlc/guidance/` directory.
+ * @returns Loaded layers and any warnings.
+ */
+export declare function loadGuidanceLayers(guidanceDir: string): LoadedGuidance;
+/**
+ * Parse a guidance layer file (YAML frontmatter + markdown body).
+ *
+ * @param content - Raw file content.
+ * @param filePath - Path for error messages.
+ * @returns Parsed guidance layer, or null on failure.
+ */
+export declare function parseGuidanceFile(content: string, filePath: string): GuidanceLayer | null;
+//# sourceMappingURL=loaders.d.ts.map

package/dist/compile/loaders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loaders.d.ts","sourceRoot":"","sources":["../../src/compile/loaders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,KAAK,EAAa,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAmBxE;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,CA0DvE;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,EAAE,CAerD;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GACjB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAqB1C;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,EAAE,GACtB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAgB1C;AAiCD,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,CA6DtE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CA6CzF"}

package/dist/compile/loaders.js

@@ -0,0 +1,293 @@
+/**
+ * Skill/guidance loaders with context placeholder resolution.
+ *
+ * - `loadSkills()` loads universal skill definitions from a directory.
+ * - `parseSkillFile()` parses a single skill file (YAML frontmatter + markdown body).
+ * - `resolvePlaceholders()` resolves `{{context:<doc>}}` and `{{guidance:<layer>}}` placeholders.
+ * - `loadGuidanceLayers()` loads guidance layers registered in `index.yaml`.
+ *
+ * Requirements: 2.1, 2.6, 1.8, 16.11
+ */
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { join, basename, extname } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Maximum size (bytes) for inline placeholder resolution. Larger files get a read-instruction. */
+const INLINE_THRESHOLD_BYTES = 2048;
+/** Regex matching `{{context:<doc-name>}}` placeholders. */
+const CONTEXT_PLACEHOLDER_RE = /\{\{context:([^}]+)\}\}/g;
+/** Regex matching `{{guidance:<layer-name>}}` placeholders. */
+const GUIDANCE_PLACEHOLDER_RE = /\{\{guidance:([^}]+)\}\}/g;
+// ---------------------------------------------------------------------------
+// Skill loader
+// ---------------------------------------------------------------------------
+/**
+ * Parse a single skill file (YAML frontmatter delimited by `---` + markdown body).
+ *
+ * @param content - Raw file content.
+ * @param filePath - Path to the file (used in error messages).
+ * @returns Parsed `Skill` object.
+ * @throws If frontmatter is missing or invalid.
+ */
+export function parseSkillFile(content, filePath) {
+    const lines = content.split('\n');
+    // Expect first line to be '---'
+    if (lines[0]?.trim() !== '---') {
+        throw new Error(`${filePath}: missing YAML frontmatter delimiter`);
+    }
+    // Find closing '---'
+    let endIndex = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i]?.trim() === '---') {
+            endIndex = i;
+            break;
+        }
+    }
+    if (endIndex === -1) {
+        throw new Error(`${filePath}: unclosed YAML frontmatter`);
+    }
+    const frontmatterRaw = lines.slice(1, endIndex).join('\n');
+    const body = lines.slice(endIndex + 1).join('\n').replace(/^\n/, '');
+    let meta;
+    try {
+        meta = parseYaml(frontmatterRaw);
+    }
+    catch (err) {
+        throw new Error(`${filePath}: invalid YAML frontmatter: ${err.message}`);
+    }
+    if (typeof meta !== 'object' || meta === null) {
+        throw new Error(`${filePath}: frontmatter must be a YAML mapping`);
+    }
+    const m = meta;
+    if (!m.name || typeof m.name !== 'string') {
+        throw new Error(`${filePath}: frontmatter missing required field 'name'`);
+    }
+    if (!m.description || typeof m.description !== 'string') {
+        throw new Error(`${filePath}: frontmatter missing required field 'description'`);
+    }
+    if (!m.phase || typeof m.phase !== 'string') {
+        throw new Error(`${filePath}: frontmatter missing required field 'phase'`);
+    }
+    const skillMeta = {
+        name: m.name,
+        description: m.description,
+        phase: m.phase,
+        ...(m.trigger && typeof m.trigger === 'string' ? { trigger: m.trigger } : {}),
+        ...(m.priority && typeof m.priority === 'number' ? { priority: m.priority } : {}),
+        ...(m.native_mode_hint && typeof m.native_mode_hint === 'object'
+            ? { native_mode_hint: m.native_mode_hint }
+            : {}),
+    };
+    return { meta: skillMeta, body };
+}
+/**
+ * Load all skill definitions from a directory.
+ *
+ * Reads all `.md` files in the given directory and parses them as skill files.
+ *
+ * @param skillsDir - Absolute path to the skills directory.
+ * @returns Array of parsed `Skill` objects.
+ */
+export function loadSkills(skillsDir) {
+    if (!existsSync(skillsDir)) {
+        return [];
+    }
+    const entries = readdirSync(skillsDir).filter((f) => f.endsWith('.md')).sort();
+    const skills = [];
+    for (const entry of entries) {
+        const filePath = join(skillsDir, entry);
+        const content = readFileSync(filePath, 'utf8');
+        skills.push(parseSkillFile(content, filePath));
+    }
+    return skills;
+}
+// ---------------------------------------------------------------------------
+// Context placeholder resolver
+// ---------------------------------------------------------------------------
+/**
+ * Resolve `{{context:<doc-name>}}` placeholders in a string.
+ *
+ * - Small targets (≤ 2KB): inline the content directly.
+ * - Larger targets: emit a read-instruction reference.
+ * - Unresolvable: produce a warning and leave an `<!-- aidlc:unresolved <ref> -->` marker.
+ *
+ * @param body - The string containing placeholders.
+ * @param contextDir - Absolute path to the `.aidlc/context/` directory.
+ * @returns Object with resolved string and any warnings produced.
+ */
+export function resolvePlaceholders(body, contextDir) {
+    const warnings = [];
+    const resolved = body.replace(CONTEXT_PLACEHOLDER_RE, (_match, docName) => {
+        const filePath = resolveContextFile(contextDir, docName);
+        if (!filePath) {
+            warnings.push(`unresolved context placeholder: {{context:${docName}}}`);
+            return `<!-- aidlc:unresolved context:${docName} -->`;
+        }
+        const stat = statSync(filePath);
+        if (stat.size <= INLINE_THRESHOLD_BYTES) {
+            return readFileSync(filePath, 'utf8');
+        }
+        // Larger files: emit a read-instruction reference
+        return `<!-- aidlc:read ${filePath} -->`;
+    });
+    return { resolved, warnings };
+}
+/**
+ * Resolve `{{guidance:<layer-name>}}` placeholders in a string using loaded guidance layers.
+ *
+ * @param body - The string containing placeholders.
+ * @param layers - Already-loaded guidance layers to resolve against.
+ * @returns Object with resolved string and any warnings produced.
+ */
+export function resolveGuidancePlaceholders(body, layers) {
+    const warnings = [];
+    const layerMap = new Map(layers.map((l) => [l.name, l]));
+    const resolved = body.replace(GUIDANCE_PLACEHOLDER_RE, (_match, layerName) => {
+        const layer = layerMap.get(layerName);
+        if (!layer) {
+            warnings.push(`unresolved guidance placeholder: {{guidance:${layerName}}}`);
+            return `<!-- aidlc:unresolved guidance:${layerName} -->`;
+        }
+        return layer.body;
+    });
+    return { resolved, warnings };
+}
+/**
+ * Resolve a context doc name to a file path.
+ * Tries exact match first, then with common extensions.
+ */
+function resolveContextFile(contextDir, docName) {
+    if (!existsSync(contextDir)) {
+        return null;
+    }
+    // Try exact match
+    const exactPath = join(contextDir, docName);
+    if (existsSync(exactPath) && statSync(exactPath).isFile()) {
+        return exactPath;
+    }
+    // Try with common extensions
+    const extensions = ['.md', '.yaml', '.yml', '.txt', '.json'];
+    for (const ext of extensions) {
+        const withExt = join(contextDir, docName + ext);
+        if (existsSync(withExt) && statSync(withExt).isFile()) {
+            return withExt;
+        }
+    }
+    return null;
+}
+/**
+ * Load guidance layers from `.aidlc/guidance/` using `index.yaml` for registration.
+ *
+ * Loading rules (Req 16.10, 16.11):
+ * - Active = registered in index.yaml AND present on disk.
+ * - Registered but missing → warning, other layers still load.
+ * - Present but unregistered → silently inactive.
+ *
+ * @param guidanceDir - Absolute path to the `.aidlc/guidance/` directory.
+ * @returns Loaded layers and any warnings.
+ */
+export function loadGuidanceLayers(guidanceDir) {
+    const warnings = [];
+    const layers = [];
+    const indexPath = join(guidanceDir, 'index.yaml');
+    if (!existsSync(indexPath)) {
+        return { layers, warnings };
+    }
+    let indexRaw;
+    try {
+        indexRaw = readFileSync(indexPath, 'utf8');
+    }
+    catch {
+        warnings.push(`unable to read guidance index: ${indexPath}`);
+        return { layers, warnings };
+    }
+    let index;
+    try {
+        index = parseYaml(indexRaw);
+    }
+    catch {
+        warnings.push(`invalid YAML in guidance index: ${indexPath}`);
+        return { layers, warnings };
+    }
+    if (typeof index !== 'object' || index === null || !('layers' in index)) {
+        warnings.push(`guidance index missing 'layers' field: ${indexPath}`);
+        return { layers, warnings };
+    }
+    const entries = index.layers;
+    if (!Array.isArray(entries)) {
+        warnings.push(`guidance index 'layers' must be an array: ${indexPath}`);
+        return { layers, warnings };
+    }
+    for (const entry of entries) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const e = entry;
+        const name = typeof e.name === 'string' ? e.name : null;
+        const file = typeof e.file === 'string' ? e.file : null;
+        if (!name || !file)
+            continue;
+        const filePath = join(guidanceDir, file);
+        if (!existsSync(filePath)) {
+            warnings.push(`registered guidance layer '${name}' not found: ${filePath}`);
+            continue;
+        }
+        const content = readFileSync(filePath, 'utf8');
+        const parsed = parseGuidanceFile(content, filePath);
+        if (parsed) {
+            layers.push(parsed);
+        }
+        else {
+            warnings.push(`failed to parse guidance layer: ${filePath}`);
+        }
+    }
+    return { layers, warnings };
+}
+/**
+ * Parse a guidance layer file (YAML frontmatter + markdown body).
+ *
+ * @param content - Raw file content.
+ * @param filePath - Path for error messages.
+ * @returns Parsed guidance layer, or null on failure.
+ */
+export function parseGuidanceFile(content, filePath) {
+    const lines = content.split('\n');
+    // Check for frontmatter
+    if (lines[0]?.trim() !== '---') {
+        // No frontmatter — try to use filename as name
+        return {
+            name: basename(filePath, extname(filePath)),
+            description: '',
+            body: content,
+        };
+    }
+    // Find closing '---'
+    let endIndex = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i]?.trim() === '---') {
+            endIndex = i;
+            break;
+        }
+    }
+    if (endIndex === -1) {
+        return null;
+    }
+    const frontmatterRaw = lines.slice(1, endIndex).join('\n');
+    const body = lines.slice(endIndex + 1).join('\n').replace(/^\n/, '');
+    let meta;
+    try {
+        meta = parseYaml(frontmatterRaw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof meta !== 'object' || meta === null) {
+        return null;
+    }
+    const m = meta;
+    const name = typeof m.name === 'string' ? m.name : basename(filePath, extname(filePath));
+    const description = typeof m.description === 'string' ? m.description : '';
+    return { name, description, body };
+}
+//# sourceMappingURL=loaders.js.map

package/dist/compile/loaders.js.map

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

package/dist/compile/merger.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Managed-block merger for AIDLC install pipeline.
+ *
+ * Merges content into a file using delimited blocks:
+ *   <!-- aidlc:begin <blockId> -->
+ *   ...content...
+ *   <!-- aidlc:end <blockId> -->
+ *
+ * Preserves all bytes outside managed blocks. Idempotent — applying
+ * the same content twice yields the same result. Exactly one block
+ * per blockId in the output; never duplicates.
+ *
+ * @module
+ */
+/**
+ * Build the begin delimiter for a given block ID.
+ */
+export declare function beginDelimiter(blockId: string): string;
+/**
+ * Build the end delimiter for a given block ID.
+ */
+export declare function endDelimiter(blockId: string): string;
+/**
+ * Merge a managed block into file content.
+ *
+ * @param existing - Current file content (or empty string if file doesn't exist)
+ * @param blockId - Unique block identifier
+ * @param content - New content to place between delimiters
+ * @returns The merged file content
+ */
+export declare function mergeBlock(existing: string, blockId: string, content: string): string;
+//# sourceMappingURL=merger.d.ts.map

package/dist/compile/merger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merger.d.ts","sourceRoot":"","sources":["../../src/compile/merger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA8BrF"}

package/dist/compile/merger.js

@@ -0,0 +1,60 @@
+/**
+ * Managed-block merger for AIDLC install pipeline.
+ *
+ * Merges content into a file using delimited blocks:
+ *   <!-- aidlc:begin <blockId> -->
+ *   ...content...
+ *   <!-- aidlc:end <blockId> -->
+ *
+ * Preserves all bytes outside managed blocks. Idempotent — applying
+ * the same content twice yields the same result. Exactly one block
+ * per blockId in the output; never duplicates.
+ *
+ * @module
+ */
+/**
+ * Build the begin delimiter for a given block ID.
+ */
+export function beginDelimiter(blockId) {
+    return `<!-- aidlc:begin ${blockId} -->`;
+}
+/**
+ * Build the end delimiter for a given block ID.
+ */
+export function endDelimiter(blockId) {
+    return `<!-- aidlc:end ${blockId} -->`;
+}
+/**
+ * Merge a managed block into file content.
+ *
+ * @param existing - Current file content (or empty string if file doesn't exist)
+ * @param blockId - Unique block identifier
+ * @param content - New content to place between delimiters
+ * @returns The merged file content
+ */
+export function mergeBlock(existing, blockId, content) {
+    const begin = beginDelimiter(blockId);
+    const end = endDelimiter(blockId);
+    // Build the full delimited block
+    const block = `${begin}\n${content}\n${end}`;
+    // Look for existing block markers
+    const beginIdx = existing.indexOf(begin);
+    const endIdx = existing.indexOf(end);
+    if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
+        // Replace the existing block (inclusive of delimiters)
+        const endOfEndMarker = endIdx + end.length;
+        const before = existing.slice(0, beginIdx);
+        const after = existing.slice(endOfEndMarker);
+        return before + block + after;
+    }
+    // Block not found — append
+    if (existing === '') {
+        return block;
+    }
+    // Ensure a newline separator before appending
+    if (existing.endsWith('\n')) {
+        return existing + '\n' + block;
+    }
+    return existing + '\n\n' + block;
+}
+//# sourceMappingURL=merger.js.map

package/dist/compile/merger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merger.js","sourceRoot":"","sources":["../../src/compile/merger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,OAAO,oBAAoB,OAAO,MAAM,CAAC;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,kBAAkB,OAAO,MAAM,CAAC;AACzC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,QAAgB,EAAE,OAAe,EAAE,OAAe;IAC3E,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IAElC,iCAAiC;IACjC,MAAM,KAAK,GAAG,GAAG,KAAK,KAAK,OAAO,KAAK,GAAG,EAAE,CAAC;IAE7C,kCAAkC;IAClC,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAErC,IAAI,QAAQ,KAAK,CAAC,CAAC,IAAI,MAAM,KAAK,CAAC,CAAC,IAAI,MAAM,GAAG,QAAQ,EAAE,CAAC;QAC1D,uDAAuD;QACvD,MAAM,cAAc,GAAG,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;QAC3C,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;QAC3C,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QAC7C,OAAO,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC;IAChC,CAAC;IAED,2BAA2B;IAC3B,IAAI,QAAQ,KAAK,EAAE,EAAE,CAAC;QACpB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,8CAA8C;IAC9C,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5B,OAAO,QAAQ,GAAG,IAAI,GAAG,KAAK,CAAC;IACjC,CAAC;IAED,OAAO,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;AACnC,CAAC"}

package/dist/core/gate.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Gate evaluation with exit-code semantics for CI/CD integration.
+ *
+ * `evaluateGate()` checks whether a phase passes its gate:
+ * - Exit 0 (pass: true) iff phase status is 'complete'.
+ * - Otherwise, returns structured data naming missing artifacts and unsatisfied criteria.
+ *
+ * Requirements: 9.1, 9.6
+ */
+import type { PhaseState, WorkflowTemplate } from './types.js';
+/**
+ * Gate check result for CI/CD integration.
+ */
+export interface GateCheckResult {
+    /** True if the phase is complete (exit code 0). */
+    pass: boolean;
+    /** Phase name checked. */
+    phase: string;
+    /** Missing artifacts (empty if pass). */
+    missingArtifacts: string[];
+    /** Unsatisfied exit criteria descriptions (empty if pass). */
+    unsatisfiedCriteria: string[];
+}
+/**
+ * Evaluate whether a phase passes its gate check.
+ *
+ * Exit 0 (pass: true) iff the phase status is 'complete'.
+ * Otherwise, returns structured data naming what's missing (Req 9.6).
+ *
+ * @param phaseName - Name of the phase to check.
+ * @param phaseStates - Map of phase name → PhaseState for the instance.
+ * @param template - The resolved workflow template defining required artifacts.
+ * @returns A GateCheckResult indicating pass/fail with structured details.
+ */
+export declare function evaluateGate(phaseName: string, phaseStates: Map<string, PhaseState>, template: WorkflowTemplate): GateCheckResult;
+//# sourceMappingURL=gate.d.ts.map

package/dist/core/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/core/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAiB,MAAM,YAAY,CAAC;AAM9E;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,IAAI,EAAE,OAAO,CAAC;IACd,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,8DAA8D;IAC9D,mBAAmB,EAAE,MAAM,EAAE,CAAC;CAC/B;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EACpC,QAAQ,EAAE,gBAAgB,GACzB,eAAe,CAiCjB"}