specweave 1.0.593 → 2.0.3

package/dist/src/cli/helpers/init/instruction-file-merger.js

@@ -1,272 +1,711 @@
 /**
- * Instruction File Merger - Smart CLAUDE.md/AGENTS.md merge
- * Updates SW sections, preserves user content
+ * Instruction File Merger (2.0) - CLAUDE.md / AGENTS.md
+ *
+ * parse → classify → render.
+ *
+ * File layout produced:
+ *   [user content that was above the META line]
+ *   <!-- SW:META template=".." version=".." sections=".." -->
+ *   <!-- SW:SECTION:id version=".." --> … <!-- SW:END:id -->   (template order)
+ *   [user-owned tail: ## Commands / ## Project notes]        (added once)
+ *   [all other user content, in original order]
+ *
+ * Guarantees:
+ * - user content (anything outside SW markers) is never dropped
+ * - sections removed from the template are deleted, ids reported
+ * - a section's version attr changes only when its body changed
+ * - idempotent: a second run over the output is byte-identical
+ * - broken markers are repaired (body kept as user content), never abort
+ * - legacy 1.x files (no markers, or "↓ ORIGINAL ↓" stacks) are stripped of
+ *   known 1.x template blocks by heading and de-duplicated
  */
 import * as fs from '../../../utils/fs-native.js';
 import * as path from 'path';
 import { createRequire } from 'module';
-const META_RE = /<!-- SW:META template="(\w+)" version="([\d.]+)" sections="([^"]*)" -->/;
-const START_RE = /<!-- SW:SECTION:([\w-]+) version="([\d.]+)" -->/;
-const END_RE = /<!-- SW:END:([\w-]+) -->/;
-function parseFile(content) {
-    const lines = content.split('\n');
+import { fileURLToPath } from 'url';
+/** Major version of the managed-block schema. Files below it are migrated. */
+export const TEMPLATE_SCHEMA_MAJOR = 2;
+// ---------------------------------------------------------------------------
+// Marker grammar
+// ---------------------------------------------------------------------------
+const META_RE = /<!-- SW:META\b([^>]*)-->/;
+const START_RE = /^\s*<!-- SW:SECTION:([\w-]+)(?:\s+version="([^"]*)")?\s*-->\s*$/;
+const END_RE = /^\s*<!-- SW:END:([\w-]+)\s*-->\s*$/;
+const LEGACY_MARKER_RE = /^\s*<!--\s*↓\s*(?:ORIGINAL|PROJECT-SPECIFIC)[^>]*-->\s*$/;
+const TEMPLATE_START_RE = /^\s*<!-- SECTION:([\w-]+)((?:\s+[\w-]+(?:="[^"]*")?)*)\s*-->\s*$/;
+const TEMPLATE_END_RE = /^\s*<!-- \/SECTION -->\s*$/;
+const HR_RE = /^\s*---\s*$/;
+const H2_RE = /^## /;
+const H1_RE = /^# /;
+const FENCE_RE = /^\s*(```|~~~)/;
+/** Lines that were part of 1.x templates but carry no heading. */
+const LEGACY_LINE_RES = [
+    /^# .+ - SpecWeave Reference\s*$/,
+    /^\*\*Framework\*\*: SpecWeave\b/,
+    /^<!-- API: Enable `apiDocs`/,
+    /^\*\*Generated by SpecWeave\*\*/,
+    /^\*\*Compatible with\*\*: Claude Code/,
+    /^\*\*Last Updated\*\*: \{TIMESTAMP\}/,
+    /^<!-- Auto-generated by SpecWeave/,
+];
+/**
+ * Known 1.x template H2 headings per template type. A block is stripped when
+ * its heading matches AND (no signatures are listed OR the body contains one
+ * of them). Signatures protect user-written sections that reuse a generic
+ * heading such as "## Rules" or "## Structure".
+ */
+const LEGACY_HEADINGS = {
+    claude: {
+        'Hook Instructions Override Everything': [],
+        'Skills & Plugins': ['Skill chaining', 'Complexity gate', 'Skill({ skill:'],
+        'LSP (Code Intelligence)': [],
+        'Getting Started': ['Your first increment starts at'],
+        'Auto-Detection': ['auto-route', 'Opt-out phrases'],
+        'Workflow Orchestration': ['Plan Mode Default', 'Subagent Strategy', 'Verification Before Done', 'Think-Before-Act'],
+        'Rules': ['.specweave/increments/####-name/', 'Unique IDs', 'emergency mode', 'Initialization guard'],
+        'Workflow': ['| Cmd | Action |', 'Ship while sleeping'],
+        'Nested Repos': ['for d in repositories', 'Before git operations'],
+        'Context': ['Check ADRs at', '/sw:docs <topic>'],
+        'Structure': ['Increment root', 'Everything else → subfolders'],
+        'Task Format': ['Satisfies ACs', '**User Story**: US-001'],
+        'Secrets': ['grep -q'],
+        'External Sync': ['Feature→Milestone', 'progress-sync'],
+        'Testing Pipeline (MANDATORY)': [],
+        'TDD': ['defaultTestMode', 'RED→GREEN→REFACTOR'],
+        'Limits': ['Max 1500 lines/file'],
+        'Troubleshooting': ['Skills missing', 'refresh-plugins', 'Restart Claude Code'],
+        'Plugin Auto-Loading': [],
+        'Principles': ['Spec-first', 'No Laziness'],
+        'Bidirectional Linking': [],
+        'External Services': ['CLI tools first'],
+        'Auto Mode': ['/sw:auto', 'IMPLEMENT → TEST'],
+        'Docs': ['verified-skill.com', 'spec-weave.com'],
+        'Using SpecWeave with Other AI Tools': [],
+        // older 1.x headings (unambiguous)
+        'Meta-Rule: Think-Before-Act': [],
+        'Lazy Plugin Loading': [],
+        'SpecWeave Auto-Routing (CRITICAL)': [],
+        'Self-Improving Skills (Reflect)': [],
+        'Non-Claude AI Tools': [],
+        'Secrets Check': ['grep -q'],
+        'Quick Commands': ['sw:increment'],
+        'Living Docs Context': [],
+        'Claude Code Concepts (2.1.3+)': [],
+        'Auto-Execute Rule (CRITICAL)': [],
+    },
+    agents: {
+        'Essential Rules': ['NEVER pollute project root', 'ONLY 4 files in increment root'],
+        'Workflow Orchestration': [
+            'Plan Before Code',
+            'Verify Before Done',
+            'Dependencies First',
+            'Claude Code has built-in orchestration',
+            'EnterPlanMode',
+        ],
+        'Core Principles (Quality)': [],
+        'Commands Reference': ['sw:increment', '| Tool | Invocation |'],
+        'Non-Claude Tools (Cursor, Copilot, etc.)': [],
+        'Sync Workflow': ['sw:progress-sync', 'Source of Truth'],
+        'Context Loading': ['Token-Efficient', 'Read only what'],
+        'Project Structure': ['Every workspace uses `repositories/`', 'Feature increments (0001-9999)', 'Living docs (extracted user stories)'],
+        'Agents (Roles)': ['{AGENTS_SECTION}', 'Adopt role perspective'],
+        'Skills (Capabilities)': ['{SKILLS_SECTION}', 'Skills auto-activate', '.cursor/skills/'],
+        'Task Format': ['Satisfies ACs', '**User Story**: US-001', 'Test Plan'],
+        'User Story Format (CRITICAL for spec.md)': [],
+        'Workflows': ['specweave context projects', 'sw:grill', 'Creating Increment'],
+        'Troubleshooting': ['non-Claude', 'sw:progress-sync', 'Missing **Project**'],
+        'Documentation': ['| Resource | Purpose |', 'verified-skill.com'],
+        // older 1.x headings (unambiguous)
+        '🚨 CRITICAL: How to Use This File (Non-Claude Code Tools)': [],
+        '📑 SECTION INDEX (Your Navigation Menu)': [],
+        'Section Index (Use Ctrl+F to Navigate)': [],
+        '🎯 CRITICAL: Skills Are Your Expert Manuals (Read First!)': [],
+        '🚀 SpecWeave Commands (Executable Workflows)': [],
+        '🔌 Plugin Architecture (IMPORTANT FOR NON-CLAUDE TOOLS)': [],
+        '🔗 External Tracker Sync (CRITICAL FOR NON-CLAUDE TOOLS)': [],
+        '📝 Documentation Updates (CRITICAL FOR NON-CLAUDE TOOLS)': [],
+        'Available Agents (Specialized Roles)': [],
+        'Available Skills (Specialized Capabilities)': [],
+        'Finding the Right Agent or Skill': [],
+        'Quick Start': ['specweave context projects', '/sw:increment', 'Create Your First Increment'],
+        'Plugin Commands': ['| Command | Plugin |', 'sw-github:sync'],
+    },
+};
+/** "## Skill Memories": template boilerplate is dropped, user bullets are kept. */
+const SKILL_MEMORIES_HEADING = 'Skill Memories';
+const SKILL_MEMORIES_BOILERPLATE = [
+    /^SpecWeave learns from corrections\./,
+    /^\*\*Disable\*\*: Set `"reflect"/,
+];
+// ---------------------------------------------------------------------------
+// Template parsing
+// ---------------------------------------------------------------------------
+export function parseTemplate(content) {
+    const lines = content.replace(/\r\n/g, '\n').split('\n');
+    const sections = [];
+    let cur = null;
+    let lastEnd = -1;
+    const flush = () => {
+        if (!cur)
+            return;
+        sections.push({
+            id: cur.id,
+            order: sections.length,
+            required: cur.req,
+            ...(cur.when ? { when: cur.when } : {}),
+            content: cur.lines.join('\n').trim(),
+        });
+        cur = null;
+    };
+    lines.forEach((l, i) => {
+        const start = l.match(TEMPLATE_START_RE);
+        if (start) {
+            flush();
+            const flags = start[2] ?? '';
+            cur = {
+                id: start[1],
+                req: /(^|\s)required(\s|$)/.test(flags),
+                when: flags.match(/\bwhen="([^"]*)"/)?.[1],
+                lines: [],
+            };
+            return;
+        }
+        if (TEMPLATE_END_RE.test(l)) {
+            flush();
+            lastEnd = i;
+            return;
+        }
+        if (cur)
+            cur.lines.push(l);
+    });
+    flush();
+    const tail = lastEnd >= 0 && sections.length > 0 ? lines.slice(lastEnd + 1).join('\n').trim() : '';
+    return { sections, tail };
+}
+export function parseTemplateSections(content) {
+    return parseTemplate(content).sections;
+}
+function parseMetaAttrs(attrs) {
+    const out = {};
+    for (const m of attrs.matchAll(/(\w+)="([^"]*)"/g))
+        out[m[1]] = m[2];
+    return out;
+}
+function parseFile(raw) {
+    const bom = raw.charCodeAt(0) === 0xfeff;
+    const content = bom ? raw.slice(1) : raw;
+    const eol = content.includes('\r\n') ? '\r\n' : '\n';
+    const lines = content.replace(/\r\n/g, '\n').split('\n');
     const result = {
+        eol,
+        bom,
         meta: null,
-        swSections: new Map(),
-        userSegments: [],
-        isLegacy: true,
-        errors: []
+        sections: [],
+        preMeta: [],
+        segments: [],
+        warnings: [],
     };
-    const m = content.match(META_RE);
-    if (m) {
+    const metaIndex = lines.findIndex(l => META_RE.test(l));
+    if (metaIndex >= 0) {
+        const attrs = parseMetaAttrs(lines[metaIndex].match(META_RE)[1]);
         result.meta = {
-            template: m[1],
-            version: m[2],
-            sections: m[3].split(',').filter(Boolean)
+            template: attrs.template ?? null,
+            version: attrs.version ?? 'unknown',
+            sections: (attrs.sections ?? '').split(',').map(s => s.trim()).filter(Boolean),
         };
-        result.isLegacy = false;
     }
-    const starts = new Map();
-    const ends = new Map();
-    lines.forEach((l, i) => {
-        const s = l.match(START_RE);
-        if (s) {
-            starts.set(s[1], i);
-            result.isLegacy = false;
+    const seen = new Set();
+    let buffer = [];
+    let bufferStart = 0;
+    let lastId = null;
+    const flush = (beforeId) => {
+        const text = buffer.join('\n').trim();
+        if (text) {
+            if (metaIndex >= 0 && bufferStart < metaIndex)
+                result.preMeta.push(text);
+            else
+                result.segments.push({ content: text, afterId: lastId, beforeId });
         }
-        const e = l.match(END_RE);
-        if (e)
-            ends.set(e[1], i);
-    });
-    const ranges = [];
-    for (const [id, start] of starts) {
-        const end = ends.get(id);
-        if (!end || end < start) {
-            result.errors.push(`${id}: bad markers`);
+        buffer = [];
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (META_RE.test(line)) {
+            if (i === metaIndex) {
+                flush(null);
+                bufferStart = i + 1;
+            }
+            else {
+                result.warnings.push('Removed duplicate SW:META line');
+            }
             continue;
         }
-        result.swSections.set(id, { id, startLine: start, endLine: end });
-        ranges.push({ id, start, end });
-    }
-    ranges.sort((a, b) => a.start - b.start);
-    if (!result.isLegacy && ranges.length) {
-        const metaLine = lines.findIndex(l => META_RE.test(l));
-        let cur = metaLine >= 0 ? metaLine + 1 : 0;
-        for (let i = 0; i < ranges.length; i++) {
-            if (cur < ranges[i].start) {
-                const seg = lines.slice(cur, ranges[i].start).join('\n').trim();
-                if (seg) {
-                    result.userSegments.push({
-                        content: seg,
-                        afterSection: i > 0 ? ranges[i - 1].id : null,
-                        beforeSection: ranges[i].id
-                    });
+        const start = line.match(START_RE);
+        if (start) {
+            const id = start[1];
+            let end = -1;
+            for (let j = i + 1; j < lines.length; j++) {
+                if (START_RE.test(lines[j]))
+                    break;
+                const e = lines[j].match(END_RE);
+                if (e && e[1] === id) {
+                    end = j;
+                    break;
                 }
             }
-            cur = ranges[i].end + 1;
-        }
-        if (cur < lines.length) {
-            const seg = lines.slice(cur).join('\n').trim();
-            if (seg) {
-                result.userSegments.push({
-                    content: seg,
-                    afterSection: ranges[ranges.length - 1].id,
-                    beforeSection: null
-                });
+            if (end < 0) {
+                result.warnings.push(`Repaired unterminated marker for section "${id}" (its text was kept as user content)`);
+                continue; // drop the marker line, keep the body as user content
             }
+            if (seen.has(id)) {
+                result.warnings.push(`Removed duplicate section "${id}"`);
+                i = end;
+                continue;
+            }
+            seen.add(id);
+            flush(id);
+            result.sections.push({ id, version: start[2] ?? '', body: lines.slice(i + 1, end).join('\n').trim() });
+            lastId = id;
+            i = end;
+            bufferStart = i + 1;
+            continue;
+        }
+        if (END_RE.test(line)) {
+            result.warnings.push(`Removed stray end marker "${line.trim()}"`);
+            continue;
         }
+        if (buffer.length === 0)
+            bufferStart = i;
+        buffer.push(line);
     }
+    flush(null);
     return result;
 }
-function wrap(id, c, v) {
-    return `<!-- SW:SECTION:${id} version="${v}" -->\n${c}\n<!-- SW:END:${id} -->`;
+/**
+ * Split an instruction file into managed vs user-owned content, using the very
+ * same marker parser the merger uses to preserve user content (`parseFile`), so
+ * there is exactly one implementation of the SW marker grammar.
+ *
+ * A file with no markers (a legacy 1.x file `update` has not touched yet) is
+ * entirely user-owned.
+ */
+export function splitManagedRegions(raw) {
+    const parsed = parseFile(raw);
+    const hasMarkers = parsed.meta !== null || parsed.sections.length > 0;
+    if (!hasMarkers)
+        return { hasMarkers: false, managed: '', user: raw };
+    return {
+        hasMarkers: true,
+        managed: parsed.sections.map(s => s.body).join('\n'),
+        user: [...parsed.preMeta, ...parsed.segments.map(s => s.content)].join('\n'),
+    };
 }
-function genMeta(t, v, s) {
-    return `<!-- SW:META template="${t}" version="${v}" sections="${s.join(',')}" -->`;
+// ---------------------------------------------------------------------------
+// User-content cleanup
+// ---------------------------------------------------------------------------
+/** Remove "↓ ORIGINAL ↓" / "↓ PROJECT-SPECIFIC ↓" markers and their leading rules. */
+function stripLegacyMarkers(text) {
+    const lines = text.split('\n');
+    const out = [];
+    let found = false;
+    for (const line of lines) {
+        if (LEGACY_MARKER_RE.test(line)) {
+            found = true;
+            while (out.length && (HR_RE.test(out[out.length - 1]) || out[out.length - 1].trim() === ''))
+                out.pop();
+            continue;
+        }
+        out.push(line);
+    }
+    return { text: out.join('\n').trim(), found };
 }
-function fresh(secs, t, v, name) {
-    const sorted = [...secs].sort((a, b) => a.order - b.order);
-    const parts = [genMeta(t, v, sorted.map(s => s.id)), ''];
-    for (const s of sorted) {
-        parts.push(wrap(s.id, s.content.replace(/\{PROJECT_NAME\}/g, name), v));
-        parts.push('');
+/**
+ * Split markdown into heading blocks. BOTH `#` and `##` start a new block, so a
+ * user's own H1 that follows a 1.x template section is never swallowed when
+ * that section is stripped.
+ */
+function splitBlocks(text) {
+    const blocks = [];
+    let cur = { heading: null, level: 2, lines: [] };
+    let inFence = false;
+    for (const line of text.split('\n')) {
+        if (FENCE_RE.test(line))
+            inFence = !inFence;
+        if (!inFence && (H2_RE.test(line) || H1_RE.test(line))) {
+            const level = H2_RE.test(line) ? 2 : 1;
+            blocks.push(cur);
+            cur = {
+                heading: line.slice(level + 1).replace(/\s*\{#[^}]*\}\s*$/, '').trim(),
+                level,
+                lines: [],
+            };
+            continue;
+        }
+        cur.lines.push(line);
     }
-    return parts.join('\n').trim() + '\n';
+    blocks.push(cur);
+    return blocks.filter(b => b.heading !== null || b.lines.some(l => l.trim()));
 }
-export function mergeInstructionFile(existing, secs, type, ver, name) {
-    if (!existing) {
-        return {
-            content: fresh(secs, type, ver, name),
-            action: 'created',
-            updated: [],
-            added: secs.map(s => s.id),
-            preserved: 0,
-            warnings: []
-        };
+function joinBlocks(blocks) {
+    return blocks
+        .map(b => (b.heading === null
+        ? b.lines.join('\n')
+        : ['#'.repeat(b.level) + ' ' + b.heading, ...b.lines].join('\n')).trim())
+        .filter(Boolean)
+        .join('\n\n');
+}
+/** Drop raw template copies (`<!-- SECTION:x --> … <!-- /SECTION -->`) and 1.x no-heading lines. */
+function stripLegacyLines(text, projectName) {
+    const out = [];
+    let inTemplate = false;
+    let inFence = false;
+    for (const line of text.split('\n')) {
+        if (FENCE_RE.test(line))
+            inFence = !inFence;
+        if (inFence) {
+            if (!inTemplate)
+                out.push(line);
+            continue;
+        }
+        if (TEMPLATE_START_RE.test(line)) {
+            inTemplate = true;
+            continue;
+        }
+        if (TEMPLATE_END_RE.test(line)) {
+            inTemplate = false;
+            continue;
+        }
+        if (inTemplate)
+            continue;
+        if (LEGACY_LINE_RES.some(re => re.test(line)))
+            continue;
+        if (H1_RE.test(line)) {
+            const title = line.slice(2).trim();
+            if (title === projectName || title === '{PROJECT_NAME}')
+                continue;
+        }
+        out.push(line);
     }
-    const p = parseFile(existing);
-    if (p.isLegacy) {
-        const f = fresh(secs, type, ver, name);
-        return {
-            content: `${f}\n---\n<!-- ↓ ORIGINAL ↓ -->\n\n${existing}\n`,
-            action: 'merged',
-            updated: [],
-            added: secs.map(s => s.id),
-            preserved: 1,
-            warnings: ['Legacy preserved below']
-        };
+    return out.join('\n');
+}
+/** Strip known 1.x template H2 blocks; keep everything else verbatim. */
+function stripLegacyBlocks(text, type, projectName) {
+    const known = LEGACY_HEADINGS[type];
+    const blocks = splitBlocks(stripLegacyLines(text, projectName));
+    const kept = [];
+    for (const b of blocks) {
+        if (b.heading === null || b.level !== 2) {
+            kept.push(b);
+            continue;
+        }
+        if (b.heading === SKILL_MEMORIES_HEADING) {
+            const lines = b.lines.filter(l => !SKILL_MEMORIES_BOILERPLATE.some(re => re.test(l)));
+            const hasContent = lines.some(l => l.trim() && !l.trim().startsWith('<!--'));
+            if (hasContent)
+                kept.push({ heading: b.heading, level: b.level, lines });
+            continue;
+        }
+        const sigs = known[b.heading];
+        if (sigs) {
+            const body = b.lines.join('\n');
+            if (sigs.length === 0 || sigs.some(s => body.includes(s)))
+                continue;
+        }
+        kept.push(b);
     }
-    if (p.errors.length) {
+    return tidyRules(joinBlocks(kept));
+}
+/** Collapse rules left behind by removed blocks: no leading/trailing/consecutive `---`. */
+function tidyRules(text) {
+    const lines = text.split('\n');
+    const out = [];
+    for (const line of lines) {
+        if (HR_RE.test(line)) {
+            const prev = [...out].reverse().find(l => l.trim() !== '');
+            if (prev === undefined || HR_RE.test(prev))
+                continue;
+        }
+        out.push(line);
+    }
+    while (out.length && (HR_RE.test(out[out.length - 1]) || out[out.length - 1].trim() === ''))
+        out.pop();
+    return out.join('\n').trim();
+}
+function normalizeKey(text) {
+    return text.replace(/\s+/g, ' ').trim().toLowerCase();
+}
+/**
+ * Drop H2 blocks that repeat an earlier identical block (ORIGINAL stacking
+ * artifact). Returns one entry per input (possibly empty) so callers keep
+ * their positional metadata.
+ */
+function dedupeBlocks(texts) {
+    const seen = new Set();
+    return texts.map(text => {
+        const kept = [];
+        for (const b of splitBlocks(text)) {
+            const key = normalizeKey(joinBlocks([b]));
+            if (!key || seen.has(key))
+                continue;
+            seen.add(key);
+            kept.push(b);
+        }
+        return joinBlocks(kept);
+    });
+}
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+function wrap(id, body, version) {
+    return `<!-- SW:SECTION:${id} version="${version}" -->\n${body}\n<!-- SW:END:${id} -->`;
+}
+function genMeta(type, version, ids) {
+    return `<!-- SW:META template="${type}" version="${version}" sections="${ids.join(',')}" -->`;
+}
+function fillName(text, name) {
+    return text.replace(/\{PROJECT_NAME\}/g, name);
+}
+const PLACEHOLDERS = [
+    { key: 'BUILD_CMD', label: 'build', pick: c => c.build },
+    { key: 'TEST_CMD', label: 'test', pick: c => c.test },
+    { key: 'LINT_CMD', label: 'lint', pick: c => c.lint },
+];
+/**
+ * Visible marker for a command the stack detector could not find. An HTML
+ * comment would render as an empty table cell, so agents never saw it.
+ * The label keeps each row's marker distinct, so filling one in later does not
+ * overwrite the others.
+ */
+function todoComment(label) {
+    return `TODO: not detected \u2014 fill in the ${label} command`;
+}
+/**
+ * Fill `{{BUILD_CMD}}` / `{{TEST_CMD}}` / `{{LINT_CMD}}` (and the TODO marker a
+ * previous run may have left) only where they are still present. Guarantees no
+ * `{{…}}` placeholder survives into a written instruction file.
+ */
+export function fillCommandPlaceholders(text, commands) {
+    let out = text;
+    for (const p of PLACEHOLDERS) {
+        const value = commands ? p.pick(commands) : undefined;
+        const token = `{{${p.key}}}`;
+        const todo = todoComment(p.label);
+        if (!out.includes(token) && !out.includes(todo))
+            continue;
+        const replacement = value ? '`' + value + '`' : todo;
+        out = out.split('`' + token + '`').join(replacement);
+        out = out.split(token).join(value ?? todo);
+        if (value)
+            out = out.split(todo).join('`' + value + '`');
+    }
+    return out;
+}
+function majorOf(version) {
+    const m = version.match(/^(\d+)/);
+    return m ? Number(m[1]) : 0;
+}
+function normalizeTemplate(secs, opts) {
+    if (Array.isArray(secs)) {
+        return { sections: [...secs].sort((a, b) => a.order - b.order), tail: opts?.tail ?? '' };
+    }
+    return { sections: [...secs.sections].sort((a, b) => a.order - b.order), tail: secs.tail };
+}
+function finish(text, p) {
+    let out = text.trim() + '\n';
+    if (p?.eol === '\r\n')
+        out = out.replace(/\n/g, '\r\n');
+    if (p?.bom)
+        out = '\uFEFF' + out;
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export function mergeInstructionFile(existing, secs, type, ver, name, opts = {}) {
+    const tpl = normalizeTemplate(secs, opts);
+    // `when="flag"` sections are rendered only while their flag is on; when it
+    // turns off they are treated exactly like a section dropped from the template.
+    const active = tpl.sections.filter(s => !s.when || opts.flags?.[s.when] === true);
+    const ids = active.map(s => s.id);
+    if (!existing || !existing.trim()) {
+        const parts = [genMeta(type, ver, ids)];
+        for (const s of active)
+            parts.push(wrap(s.id, fillName(s.content, name), ver));
+        if (tpl.tail)
+            parts.push(fillName(tpl.tail, name));
         return {
-            content: existing,
-            action: 'preserved',
+            content: finish(fillCommandPlaceholders(parts.join('\n\n'), opts.commands), null),
+            action: 'created',
             updated: [],
-            added: [],
+            added: ids,
+            removed: [],
             preserved: 0,
-            warnings: ['Fix manually', ...p.errors]
+            warnings: [],
+            migration: null,
         };
     }
-    const prev = new Set(p.meta?.sections || []);
-    const exist = new Set(p.swSections.keys());
-    const upd = [];
-    const add = [];
-    const skip = [];
-    for (const s of secs) {
-        if (exist.has(s.id)) {
-            upd.push(s);
+    const p = parseFile(existing);
+    const warnings = [...p.warnings];
+    const legacy = p.meta === null && p.sections.length === 0;
+    const fromVersion = p.meta?.version ?? p.sections[0]?.version ?? 'unknown';
+    const migrating = legacy || majorOf(fromVersion) < TEMPLATE_SCHEMA_MAJOR;
+    // --- classify sections -------------------------------------------------
+    const fileById = new Map(p.sections.map(s => [s.id, s]));
+    const listed = new Set(p.meta?.sections ?? p.sections.map(s => s.id));
+    const rendered = [];
+    const updated = [];
+    const added = [];
+    const skipped = [];
+    for (const s of active) {
+        const body = fillName(s.content, name);
+        const cur = fileById.get(s.id);
+        if (cur) {
+            if (cur.body === body)
+                rendered.push({ id: s.id, version: cur.version || ver, body });
+            else {
+                rendered.push({ id: s.id, version: ver, body });
+                updated.push(s.id);
+            }
         }
-        else if (prev.has(s.id)) {
-            if (s.required)
-                add.push(s);
-            else
-                skip.push(s.id);
+        else if (listed.has(s.id) && !s.required) {
+            skipped.push(s.id);
         }
         else {
-            add.push(s);
+            rendered.push({ id: s.id, version: ver, body });
+            added.push(s.id);
         }
     }
-    const all = [...upd, ...add].sort((a, b) => a.order - b.order);
-    const els = [];
-    els.push({ c: genMeta(type, ver, all.map(s => s.id)), o: -1000 });
-    for (const s of all) {
-        els.push({
-            c: wrap(s.id, s.content.replace(/\{PROJECT_NAME\}/g, name), ver),
-            o: s.order
-        });
+    const tplIds = new Set(ids);
+    const removed = p.sections.map(s => s.id).filter(id => !tplIds.has(id));
+    const renderedIds = rendered.map(r => r.id);
+    const sectionsChanged = updated.length > 0 ||
+        added.length > 0 ||
+        removed.length > 0 ||
+        renderedIds.join(',') !== (p.meta?.sections ?? []).join(',');
+    const metaVersion = !p.meta || sectionsChanged || migrating ? ver : p.meta.version;
+    // --- classify user content ----------------------------------------------
+    let legacyMarkers = false;
+    const clean = (text) => {
+        const r = stripLegacyMarkers(text);
+        legacyMarkers = legacyMarkers || r.found;
+        return r.text;
+    };
+    let pre = p.preMeta.map(clean).filter(Boolean);
+    let segs = p.segments.map(s => ({ ...s, content: clean(s.content) })).filter(s => s.content);
+    if (migrating) {
+        pre = pre.map(t => stripLegacyBlocks(t, type, name)).filter(Boolean);
+        segs = segs.map(s => ({ ...s, content: stripLegacyBlocks(s.content, type, name) })).filter(s => s.content);
     }
-    for (const seg of p.userSegments) {
-        let o;
-        if (seg.afterSection) {
-            const ts = secs.find(s => s.id === seg.afterSection);
-            o = ts ? ts.order + 0.5 : 9999;
-        }
-        else if (seg.beforeSection) {
-            const ts = secs.find(s => s.id === seg.beforeSection);
-            o = ts ? ts.order - 0.5 : -999;
+    if (migrating || legacyMarkers) {
+        const deduped = dedupeBlocks([...pre, ...segs.map(s => s.content)]);
+        const preCount = pre.length;
+        pre = deduped.slice(0, preCount).filter(Boolean);
+        segs = segs.map((s, i) => ({ ...s, content: deduped[preCount + i] })).filter(s => s.content);
+    }
+    const attached = new Map();
+    const post = [];
+    const surviving = new Set(renderedIds);
+    for (const s of segs) {
+        if (!migrating && s.afterId && surviving.has(s.afterId)) {
+            const list = attached.get(s.afterId) ?? [];
+            list.push(s.content);
+            attached.set(s.afterId, list);
         }
         else {
-            o = 9999;
+            post.push(s.content);
         }
-        els.push({ c: seg.content, o });
     }
-    els.sort((a, b) => a.o - b.o);
-    return {
-        content: els.map(e => e.c).join('\n\n').trim() + '\n',
-        action: 'merged',
-        updated: upd.map(s => s.id),
-        added: add.map(s => s.id),
-        preserved: p.userSegments.length,
-        warnings: skip.length ? [`Skipped: ${skip.join(', ')}`] : []
-    };
+    const userText = [...pre, ...segs.map(s => s.content)].join('\n');
+    const hasCommands = /^## Commands\s*$/m.test(userText);
+    const addTail = migrating && Boolean(tpl.tail) && !hasCommands;
+    // --- render --------------------------------------------------------------
+    const parts = [];
+    if (pre.length)
+        parts.push(pre.join('\n\n'));
+    parts.push(genMeta(type, metaVersion, renderedIds));
+    for (const r of rendered) {
+        parts.push(wrap(r.id, r.body, r.version));
+        for (const a of attached.get(r.id) ?? [])
+            parts.push(a);
+    }
+    if (addTail)
+        parts.push(fillName(tpl.tail, name));
+    parts.push(...post);
+    const content = finish(fillCommandPlaceholders(parts.join('\n\n'), opts.commands), p);
+    const preserved = pre.length + segs.length;
+    if (skipped.length)
+        warnings.push(`Skipped optional sections you removed earlier: ${skipped.join(', ')}`);
+    let migration = null;
+    if (migrating && (legacy || removed.length > 0)) {
+        migration = { fromVersion: legacy ? 'legacy (no markers)' : fromVersion, removed };
+        warnings.push(`Upgraded instructions from ${migration.fromVersion} to ${ver}: ` +
+            (removed.length ? `removed 1.x sections ${removed.join(', ')}; ` : 'stripped 1.x template blocks; ') +
+            'your own notes were kept below the managed block.');
+    }
+    if (content === existing) {
+        return { content, action: 'unchanged', updated: [], added: [], removed: [], preserved, warnings, migration: null };
+    }
+    return { content, action: 'merged', updated, added, removed, preserved, warnings, migration };
 }
 /**
- * Strip all SW-managed sections from an instruction file, returning only user content.
- * Returns null if no user content remains (file was 100% SW-managed or empty).
+ * Strip all SW-managed content from an instruction file, returning only user
+ * content (null when nothing is left). Used by `specweave uninstall`.
  */
 export function stripSwSections(content) {
     if (!content || !content.trim())
         return null;
-    const parsed = parseFile(content);
-    // Legacy file or file with no SW markers — it's all user content
-    if (parsed.isLegacy && parsed.swSections.size === 0) {
+    const p = parseFile(content);
+    if (p.meta === null && p.sections.length === 0)
         return content.trim() || null;
-    }
-    // Has SW sections — extract only user segments
-    if (parsed.userSegments.length === 0)
-        return null;
-    const userContent = parsed.userSegments.map(s => s.content).join('\n\n').trim();
-    return userContent || null;
-}
-export function parseTemplateSections(content) {
-    const secs = [];
-    const lines = content.split('\n');
-    let cur = null;
-    let ord = 0;
-    for (const l of lines) {
-        const d = l.match(/<!-- SECTION:([\w-]+)(?:\s+(required))? -->/);
-        if (d) {
-            if (cur) {
-                secs.push({
-                    id: cur.id,
-                    order: cur.ord,
-                    required: cur.req,
-                    content: cur.lines.join('\n').trim()
-                });
-            }
-            cur = { id: d[1], ord: ord++, req: d[2] === 'required', lines: [] };
-            continue;
-        }
-        if (l.match(/<!-- \/SECTION -->/)) {
-            if (cur) {
-                secs.push({
-                    id: cur.id,
-                    order: cur.ord,
-                    required: cur.req,
-                    content: cur.lines.join('\n').trim()
-                });
-            }
-            cur = null;
-            continue;
-        }
-        if (cur)
-            cur.lines.push(l);
-    }
-    if (cur) {
-        secs.push({
-            id: cur.id,
-            order: cur.ord,
-            required: cur.req,
-            content: cur.lines.join('\n').trim()
-        });
-    }
-    return secs;
+    const parts = [...p.preMeta, ...p.segments.map(s => s.content)]
+        .map(t => stripLegacyMarkers(t).text)
+        .filter(Boolean);
+    return parts.length ? parts.join('\n\n') : null;
 }
-export function getPackageVersion() {
-    // Use createRequire to resolve specweave's package.json reliably,
-    // even with symlinked installs (nvm, pnpm, npm link)
+/**
+ * Read specweave's own package.json (not the user's project).
+ * Resolves reliably with symlinked installs (nvm, pnpm, npm link); falls back to a directory walk.
+ */
+export function readSpecweavePackageJson() {
     try {
         const require = createRequire(import.meta.url);
         const pkgPath = require.resolve('specweave/package.json');
-        return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
+        return JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
     }
     catch {
-        // createRequire failed — fall back to directory walk
+        // fall back to a directory walk (npm link, running from a checkout)
     }
     try {
-        let d = path.dirname(new URL(import.meta.url).pathname);
+        let d = path.dirname(fileURLToPath(import.meta.url));
         for (let i = 0; i < 10; i++) {
             const p = path.join(d, 'package.json');
             if (fs.existsSync(p)) {
                 const j = JSON.parse(fs.readFileSync(p, 'utf-8'));
                 if (j.name === 'specweave')
-                    return j.version;
+                    return j;
             }
-            d = path.dirname(d);
+            const parent = path.dirname(d);
+            if (parent === d)
+                break;
+            d = parent;
         }
     }
     catch {
         // ignore
     }
-    return '0.0.0';
+    return {};
+}
+export function getPackageVersion() {
+    return readSpecweavePackageJson().version ?? '0.0.0';
+}
+/**
+ * Minimum Node.js version from specweave's package.json `engines.node` (e.g. ">=20.12.0" → "20.12.0").
+ */
+export function getMinNodeVersion() {
+    const engines = readSpecweavePackageJson().engines?.node;
+    const m = typeof engines === 'string' ? engines.match(/(\d+)(?:\.(\d+))?(?:\.(\d+))?/) : null;
+    if (!m)
+        return '20.0.0';
+    return `${m[1]}.${m[2] ?? '0'}.${m[3] ?? '0'}`;
 }
 //# sourceMappingURL=instruction-file-merger.js.map