@nusoft/nuos-build-catalogue 0.10.0 → 0.10.1

package/dist/regenerate/check.js

@@ -0,0 +1,97 @@
+/**
+ * Drift detection: walk the workflow store, compare each record's
+ * stored `rawMarkdown` to its source file, report differences.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { countLineDiff } from './diff.js';
+const ZERO_PER_REGISTER = () => ({
+    total: 0,
+    identical: 0,
+    differs: 0,
+    missing: 0,
+    unreadable: 0,
+});
+export async function runRegenerate(config) {
+    const startedAt = Date.now();
+    const records = config.store.list();
+    const filtered = config.registerFilter
+        ? records.filter((r) => r.register === config.registerFilter)
+        : records;
+    const byRegister = {
+        work_unit: ZERO_PER_REGISTER(),
+        decision: ZERO_PER_REGISTER(),
+        open_question: ZERO_PER_REGISTER(),
+        persona: ZERO_PER_REGISTER(),
+    };
+    let identical = 0;
+    let differs = 0;
+    let missing = 0;
+    let unreadable = 0;
+    const drifted = [];
+    for (const record of filtered) {
+        const sourceAbsolute = path.join(config.catalogueRoot, record.sourcePath);
+        byRegister[record.register].total += 1;
+        if (!existsSync(sourceAbsolute)) {
+            missing += 1;
+            byRegister[record.register].missing += 1;
+            drifted.push({
+                handle: record.handle,
+                register: record.register,
+                sourcePath: record.sourcePath,
+                kind: 'missing-source',
+                errorMessage: `source file does not exist at ${sourceAbsolute}`,
+            });
+            continue;
+        }
+        let onDisk;
+        try {
+            onDisk = await readFile(sourceAbsolute, 'utf8');
+        }
+        catch (err) {
+            unreadable += 1;
+            byRegister[record.register].unreadable += 1;
+            drifted.push({
+                handle: record.handle,
+                register: record.register,
+                sourcePath: record.sourcePath,
+                kind: 'unreadable-source',
+                errorMessage: err instanceof Error ? err.message : String(err),
+            });
+            continue;
+        }
+        if (onDisk === record.rawMarkdown) {
+            identical += 1;
+            byRegister[record.register].identical += 1;
+            continue;
+        }
+        if (config.write) {
+            // Mode 2 cutover — overwrite the source with the stored canonical
+            // form. Recorded as drift but resolved-by-write.
+            await writeFile(sourceAbsolute, record.rawMarkdown, 'utf8');
+        }
+        const counts = countLineDiff(record.rawMarkdown, onDisk);
+        differs += 1;
+        byRegister[record.register].differs += 1;
+        drifted.push({
+            handle: record.handle,
+            register: record.register,
+            sourcePath: record.sourcePath,
+            kind: 'differs',
+            byteDelta: Math.abs(onDisk.length - record.rawMarkdown.length),
+            linesAdded: counts.added,
+            linesRemoved: counts.removed,
+        });
+    }
+    return {
+        total: filtered.length,
+        identical,
+        differs,
+        missing,
+        unreadable,
+        byRegister,
+        drifted,
+        durationMs: Date.now() - startedAt,
+    };
+}

package/dist/regenerate/diff.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Minimal line-counting diff helper.
+ *
+ * Phase I only needs to know "did the file change, and by roughly how
+ * much". Full unified-diff output is a future enhancement; today the
+ * drift report names the file and the magnitude.
+ */
+export interface LineCounts {
+    added: number;
+    removed: number;
+}
+/**
+ * Counts lines that differ between `before` and `after` using a basic
+ * Myers-style diff. For the catalogue's small files this is fast
+ * enough; if we ever need to diff multi-MB files we'd swap in `diff`
+ * from npm.
+ */
+export declare function countLineDiff(before: string, after: string): LineCounts;

package/dist/regenerate/diff.js

@@ -0,0 +1,38 @@
+/**
+ * Minimal line-counting diff helper.
+ *
+ * Phase I only needs to know "did the file change, and by roughly how
+ * much". Full unified-diff output is a future enhancement; today the
+ * drift report names the file and the magnitude.
+ */
+/**
+ * Counts lines that differ between `before` and `after` using a basic
+ * Myers-style diff. For the catalogue's small files this is fast
+ * enough; if we ever need to diff multi-MB files we'd swap in `diff`
+ * from npm.
+ */
+export function countLineDiff(before, after) {
+    if (before === after)
+        return { added: 0, removed: 0 };
+    const beforeLines = before.split('\n');
+    const afterLines = after.split('\n');
+    // Build LCS table — small files, O(n*m) is fine.
+    const m = beforeLines.length;
+    const n = afterLines.length;
+    const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = m - 1; i >= 0; i--) {
+        for (let j = n - 1; j >= 0; j--) {
+            if (beforeLines[i] === afterLines[j]) {
+                dp[i][j] = dp[i + 1][j + 1] + 1;
+            }
+            else {
+                dp[i][j] = Math.max(dp[i + 1][j], dp[i][j + 1]);
+            }
+        }
+    }
+    const lcsLength = dp[0][0];
+    return {
+        removed: m - lcsLength,
+        added: n - lcsLength,
+    };
+}

package/dist/regenerate/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Phase I — markdown regeneration + drift report (WU 111).
+ *
+ * **Mode 1 (today):** markdown is canonical; this module is a
+ * verification gate. For each record in the workflow store, compare
+ * the stored `rawMarkdown` to the file at `record.sourcePath`. Any
+ * difference is reported as drift.
+ *
+ * **Mode 2 (post-WU-113):** workflow state is canonical; this module
+ * regenerates markdown from rich field-level data (which we don't have
+ * yet — Phase G stopped at count parity, not field-level fidelity).
+ * Mode 2 is out of scope until WU 113.
+ */
+import type { Register } from '../migrate/types.js';
+export type DriftKind = 'identical' | 'differs' | 'missing-source' | 'unreadable-source';
+export interface DriftEntry {
+    handle: string;
+    register: Register;
+    sourcePath: string;
+    kind: DriftKind;
+    /** Set when kind === 'differs'. Number of bytes the two contents differ by (rough magnitude). */
+    byteDelta?: number;
+    /** Set when kind === 'differs'. Lines added vs the stored record. */
+    linesAdded?: number;
+    /** Set when kind === 'differs'. Lines removed vs the stored record. */
+    linesRemoved?: number;
+    /** Set when kind === 'missing-source' or 'unreadable-source'. */
+    errorMessage?: string;
+}
+export interface DriftReport {
+    total: number;
+    identical: number;
+    differs: number;
+    missing: number;
+    unreadable: number;
+    byRegister: Record<Register, {
+        total: number;
+        identical: number;
+        differs: number;
+        missing: number;
+        unreadable: number;
+    }>;
+    /** Only the non-identical entries; the identical ones are summarised by counts. */
+    drifted: DriftEntry[];
+    durationMs: number;
+}
+export interface RegenerateConfig {
+    /** Filter to a single register; default scans all four. */
+    registerFilter?: Register;
+    /** When true, overwrite source files with stored `rawMarkdown` (Mode 2 cutover). Off by default. */
+    write?: boolean;
+}

package/dist/regenerate/types.js

@@ -0,0 +1,14 @@
+/**
+ * Phase I — markdown regeneration + drift report (WU 111).
+ *
+ * **Mode 1 (today):** markdown is canonical; this module is a
+ * verification gate. For each record in the workflow store, compare
+ * the stored `rawMarkdown` to the file at `record.sourcePath`. Any
+ * difference is reported as drift.
+ *
+ * **Mode 2 (post-WU-113):** workflow state is canonical; this module
+ * regenerates markdown from rich field-level data (which we don't have
+ * yet — Phase G stopped at count parity, not field-level fidelity).
+ * Mode 2 is out of scope until WU 113.
+ */
+export {};

package/dist/runtime/ac-parse.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Acceptance-criteria parser + tickr.
+ *
+ * Two shapes are recognised, matching what the live catalogue uses:
+ *
+ *   1. Checkbox: `- [ ] text` (unticked) or `- [x] text` (ticked)
+ *   2. Numbered + emoji: `1. ✅ text` (ticked) or `1. text` (unticked)
+ *
+ * Files that don't match either shape produce an empty AC list — the
+ * maintainer falls back to hand-editing for those. WU 073 is the only
+ * known WU that uses neither shape.
+ *
+ * The parser scans only inside the `## Acceptance criteria` section
+ * (case-insensitive; tolerates the ` (= verification)` suffix per
+ * D046). Lines outside that section are ignored even if they happen
+ * to look like AC.
+ */
+import type { AcceptanceCriterion } from '@nusoft/nuflow-pack-nuos-build-catalogue';
+/** Internal extended shape that retains the source line for byte-accurate replacement. */
+export interface ParsedAcceptanceCriterion {
+    /** Zero-based index in the AC list as parsed. */
+    index: number;
+    /** AC text without the bullet/checkbox/number/emoji prefix. */
+    text: string;
+    /** True if the source markdown has the ticked form. */
+    met: boolean;
+    /** The original full line as it appeared in the markdown — used by `tickAcceptanceCriterion` for in-place replacement. */
+    rawLine: string;
+    /** Bullet style detected for this entry — used to render the ticked form in the same shape. */
+    style: 'checkbox' | 'numbered-emoji';
+    /** Numeric prefix preserved (e.g. "1") for numbered entries; empty string for checkbox. */
+    numberPrefix: string;
+}
+/**
+ * Parse the AC list from a WU markdown body.
+ *
+ * Returns an empty list if no `## Acceptance criteria` heading exists,
+ * if the section has no recognisable AC entries, or if the section is
+ * empty.
+ */
+export declare function parseAcceptanceCriteria(rawMarkdown: string): ParsedAcceptanceCriterion[];
+/**
+ * Flip the AC at `targetIndex` from unticked to ticked, preserving the
+ * original style. If the AC is already ticked, the markdown is
+ * returned unchanged. If the index is out of range or no AC list is
+ * found, throws.
+ */
+export declare function tickAcceptanceCriterion(rawMarkdown: string, targetIndex: number): string;
+/**
+ * Extract AC list in the shape the build-catalogue pack's
+ * `work_unit.advance_status` workflow expects in
+ * `metadata.acceptanceCriteria` for the completion gate.
+ *
+ * Evidence inference:
+ *   - If the AC is ticked in markdown AND there's a Build catalogue
+ *     history entry naming this AC index, evidence comes from the
+ *     history entry.
+ *   - If the AC is ticked in markdown with no history entry, evidence
+ *     defaults to "Ticked in source markdown."
+ *   - If the AC is unticked, evidence is undefined and the completion
+ *     gate will reject.
+ */
+export declare function extractForCompletion(rawMarkdown: string): AcceptanceCriterion[];

package/dist/runtime/ac-parse.js

@@ -0,0 +1,196 @@
+/**
+ * Acceptance-criteria parser + tickr.
+ *
+ * Two shapes are recognised, matching what the live catalogue uses:
+ *
+ *   1. Checkbox: `- [ ] text` (unticked) or `- [x] text` (ticked)
+ *   2. Numbered + emoji: `1. ✅ text` (ticked) or `1. text` (unticked)
+ *
+ * Files that don't match either shape produce an empty AC list — the
+ * maintainer falls back to hand-editing for those. WU 073 is the only
+ * known WU that uses neither shape.
+ *
+ * The parser scans only inside the `## Acceptance criteria` section
+ * (case-insensitive; tolerates the ` (= verification)` suffix per
+ * D046). Lines outside that section are ignored even if they happen
+ * to look like AC.
+ */
+const HEADING_RE = /^##\s+Acceptance\s+criteria(\s*\(=\s*verification\))?\s*$/im;
+const CHECKBOX_RE = /^(\s*-\s+\[)([ xX])(\]\s+)(.+)$/;
+const NUMBERED_TICKED_RE = /^(\s*)(\d+)(\.\s+)(✅\s+)(.+)$/u;
+const NUMBERED_UNTICKED_RE = /^(\s*)(\d+)(\.\s+)(?!✅|⏳|⚠|❌|🔴)([^*-].*)$/u;
+/**
+ * Parse the AC list from a WU markdown body.
+ *
+ * Returns an empty list if no `## Acceptance criteria` heading exists,
+ * if the section has no recognisable AC entries, or if the section is
+ * empty.
+ */
+export function parseAcceptanceCriteria(rawMarkdown) {
+    const headingMatch = HEADING_RE.exec(rawMarkdown);
+    if (!headingMatch)
+        return [];
+    const sectionStart = headingMatch.index + headingMatch[0].length;
+    // Find the next ## or # heading (or EOF) to bound the section
+    const tail = rawMarkdown.slice(sectionStart);
+    const nextHeadingMatch = /^#{1,2}\s+\S/m.exec(tail);
+    const sectionEnd = nextHeadingMatch ? sectionStart + nextHeadingMatch.index : rawMarkdown.length;
+    const section = rawMarkdown.slice(sectionStart, sectionEnd);
+    const lines = section.split('\n');
+    const result = [];
+    let index = 0;
+    for (const line of lines) {
+        // Try checkbox first
+        const cb = CHECKBOX_RE.exec(line);
+        if (cb) {
+            result.push({
+                index,
+                text: cb[4].trim(),
+                met: cb[2].toLowerCase() === 'x',
+                rawLine: line,
+                style: 'checkbox',
+                numberPrefix: '',
+            });
+            index += 1;
+            continue;
+        }
+        // Then numbered + ✅
+        const nt = NUMBERED_TICKED_RE.exec(line);
+        if (nt) {
+            result.push({
+                index,
+                text: nt[5].trim(),
+                met: true,
+                rawLine: line,
+                style: 'numbered-emoji',
+                numberPrefix: nt[2],
+            });
+            index += 1;
+            continue;
+        }
+        // Then numbered without leading emoji (treated as unticked)
+        const nu = NUMBERED_UNTICKED_RE.exec(line);
+        if (nu) {
+            result.push({
+                index,
+                text: nu[4].trim(),
+                met: false,
+                rawLine: line,
+                style: 'numbered-emoji', // round-trips back as numbered+emoji when ticked
+                numberPrefix: nu[2],
+            });
+            index += 1;
+            continue;
+        }
+    }
+    return result;
+}
+/**
+ * Flip the AC at `targetIndex` from unticked to ticked, preserving the
+ * original style. If the AC is already ticked, the markdown is
+ * returned unchanged. If the index is out of range or no AC list is
+ * found, throws.
+ */
+export function tickAcceptanceCriterion(rawMarkdown, targetIndex) {
+    const acs = parseAcceptanceCriteria(rawMarkdown);
+    if (acs.length === 0) {
+        throw new Error('tickAcceptanceCriterion: no acceptance-criteria section found in this markdown');
+    }
+    if (targetIndex < 0 || targetIndex >= acs.length) {
+        throw new Error(`tickAcceptanceCriterion: index ${targetIndex} out of range (AC list has ${acs.length} entries)`);
+    }
+    const target = acs[targetIndex];
+    if (target.met) {
+        return rawMarkdown; // already ticked; no-op
+    }
+    const tickedLine = renderTickedLine(target);
+    // Replace the FIRST occurrence of the raw line (we expect uniqueness
+    // because the same line text appearing twice in the AC section would
+    // already be a catalogue-discipline issue).
+    return rawMarkdown.replace(target.rawLine, tickedLine);
+}
+function renderTickedLine(ac) {
+    switch (ac.style) {
+        case 'checkbox':
+            return ac.rawLine.replace(CHECKBOX_RE, '$1x$3$4');
+        case 'numbered-emoji':
+            // Two cases: was numbered-ticked already (caller shouldn't hit this
+            // because met==true returns early), or was numbered-unticked.
+            if (ac.rawLine.includes('✅')) {
+                return ac.rawLine; // defensive: shouldn't happen
+            }
+            return ac.rawLine.replace(NUMBERED_UNTICKED_RE, '$1$2$3✅ $4');
+    }
+}
+/**
+ * Extract AC list in the shape the build-catalogue pack's
+ * `work_unit.advance_status` workflow expects in
+ * `metadata.acceptanceCriteria` for the completion gate.
+ *
+ * Evidence inference:
+ *   - If the AC is ticked in markdown AND there's a Build catalogue
+ *     history entry naming this AC index, evidence comes from the
+ *     history entry.
+ *   - If the AC is ticked in markdown with no history entry, evidence
+ *     defaults to "Ticked in source markdown."
+ *   - If the AC is unticked, evidence is undefined and the completion
+ *     gate will reject.
+ */
+export function extractForCompletion(rawMarkdown) {
+    const parsed = parseAcceptanceCriteria(rawMarkdown);
+    const historyEvidence = parseHistoryEvidence(rawMarkdown);
+    return parsed.map((ac) => ({
+        text: ac.text,
+        met: ac.met,
+        evidence: ac.met
+            ? historyEvidence.get(ac.index) ?? 'Ticked in source markdown.'
+            : undefined,
+    }));
+}
+/**
+ * Parse the `## Build catalogue history` section for tick entries
+ * matching `Acceptance criterion <N> ticked` and pull the
+ * `Evidence: ...` line from the same entry. Returns a map from AC
+ * index (zero-based, matching `parseAcceptanceCriteria` output) to
+ * the evidence string.
+ *
+ * The history log uses 1-based AC numbering in its summary line
+ * ("Acceptance criterion 3 ticked: ..."), but we map to 0-based
+ * indexing here for consistency with the rest of the pipeline.
+ */
+function parseHistoryEvidence(rawMarkdown) {
+    const result = new Map();
+    const historyHeadingIndex = rawMarkdown.indexOf('## Build catalogue history');
+    if (historyHeadingIndex === -1)
+        return result;
+    const sectionTail = rawMarkdown.slice(historyHeadingIndex);
+    // Bound the history section at the next ## heading (if any).
+    const nextSectionMatch = /\n## \S/.exec(sectionTail.slice('## Build catalogue history'.length));
+    const sectionEnd = nextSectionMatch
+        ? '## Build catalogue history'.length + nextSectionMatch.index
+        : sectionTail.length;
+    const section = sectionTail.slice(0, sectionEnd);
+    // Split into entries on the top-level `- **<timestamp>**` bullets.
+    // Each entry runs until the next top-level bullet or end-of-section.
+    const blocks = section.split(/\n(?=- \*\*)/);
+    for (const block of blocks) {
+        if (!/^- \*\*/.test(block))
+            continue;
+        const summaryMatch = /Acceptance criterion (?:at index )?(\d+)/i.exec(block);
+        if (!summaryMatch)
+            continue;
+        const evidenceMatch = /^\s*-\s*Evidence:\s*(.+?)$/m.exec(block);
+        let index = parseInt(summaryMatch[1], 10);
+        if (/at index/i.test(block)) {
+            // already 0-based
+        }
+        else {
+            index = index - 1;
+        }
+        if (index < 0)
+            continue;
+        const evidence = evidenceMatch ? evidenceMatch[1].trim() : 'Ticked via workflow.';
+        result.set(index, evidence);
+    }
+    return result;
+}

package/dist/runtime/markdown-edit.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Minimal markdown editors for the Phase H part 2 write commands.
+ *
+ * The catalogue's existing files use two status formats:
+ *   - bold:        `**Status:** <text>`
+ *   - pipe-table:  `| Status | <text> |`
+ *
+ * Both are rewritten in place by `replaceStatusLine`. If neither is
+ * found, the helper inserts a `**Status:**` line near the file's H1.
+ *
+ * For AC ticking we deliberately do NOT parse the AC list (different
+ * files use different shapes — `- [ ] text`, numbered lists, prose
+ * bullets, sub-headings). Instead, `appendChangeLog` writes a
+ * structured footer entry naming the change. The maintainer can then
+ * hand-tighten the AC list itself if they want; the workflow record
+ * + audit chain are the canonical statements either way.
+ */
+/**
+ * Replace the file's status line in place.
+ *
+ * Returns `{ updated: string, replaced: boolean }`. If `replaced` is
+ * false, the file did not have a status line in either supported
+ * format; the caller decides whether to insert one (`insertStatusLine`).
+ */
+export declare function replaceStatusLine(rawMarkdown: string, newStatus: string): {
+    updated: string;
+    replaced: boolean;
+};
+/**
+ * Insert a `**Status:** <newStatus>` line immediately after the file's
+ * first H1 heading (with a blank line separator). If there is no H1,
+ * prepend the status line at the top.
+ */
+export declare function insertStatusLine(rawMarkdown: string, newStatus: string): string;
+export interface ChangeLogEntry {
+    isoTimestamp: string;
+    summary: string;
+    details?: string;
+    /** Optional source pointer — commit ref, evidence URL, etc. */
+    reference?: string;
+}
+/**
+ * Append a structured entry to a markdown file's `## Build catalogue
+ * history` section (creating it if missing). This is the audit-trail
+ * surface for write operations whose effect on the markdown is
+ * non-trivial to express by structural edit alone (e.g. AC ticks,
+ * status change rationales).
+ *
+ * Idempotence: each call appends; running the same workflow twice
+ * appends twice. The audit chain in the workflow store is the
+ * deduplicating source of truth.
+ */
+export declare function appendChangeLog(rawMarkdown: string, entry: ChangeLogEntry): string;

package/dist/runtime/markdown-edit.js

@@ -0,0 +1,101 @@
+/**
+ * Minimal markdown editors for the Phase H part 2 write commands.
+ *
+ * The catalogue's existing files use two status formats:
+ *   - bold:        `**Status:** <text>`
+ *   - pipe-table:  `| Status | <text> |`
+ *
+ * Both are rewritten in place by `replaceStatusLine`. If neither is
+ * found, the helper inserts a `**Status:**` line near the file's H1.
+ *
+ * For AC ticking we deliberately do NOT parse the AC list (different
+ * files use different shapes — `- [ ] text`, numbered lists, prose
+ * bullets, sub-headings). Instead, `appendChangeLog` writes a
+ * structured footer entry naming the change. The maintainer can then
+ * hand-tighten the AC list itself if they want; the workflow record
+ * + audit chain are the canonical statements either way.
+ */
+const BOLD_STATUS_RE = /^(\*\*Status:\*\*\s*)(.+?)(\s*)$/m;
+const TABLE_STATUS_RE = /^(\|\s*Status\s*\|\s*)(.+?)(\s*\|\s*)$/m;
+/**
+ * Replace the file's status line in place.
+ *
+ * Returns `{ updated: string, replaced: boolean }`. If `replaced` is
+ * false, the file did not have a status line in either supported
+ * format; the caller decides whether to insert one (`insertStatusLine`).
+ */
+export function replaceStatusLine(rawMarkdown, newStatus) {
+    if (BOLD_STATUS_RE.test(rawMarkdown)) {
+        return {
+            updated: rawMarkdown.replace(BOLD_STATUS_RE, `$1${newStatus}$3`),
+            replaced: true,
+        };
+    }
+    if (TABLE_STATUS_RE.test(rawMarkdown)) {
+        return {
+            updated: rawMarkdown.replace(TABLE_STATUS_RE, `$1${newStatus}$3`),
+            replaced: true,
+        };
+    }
+    return { updated: rawMarkdown, replaced: false };
+}
+/**
+ * Insert a `**Status:** <newStatus>` line immediately after the file's
+ * first H1 heading (with a blank line separator). If there is no H1,
+ * prepend the status line at the top.
+ */
+export function insertStatusLine(rawMarkdown, newStatus) {
+    const h1Match = /^#\s+.+$/m.exec(rawMarkdown);
+    if (!h1Match) {
+        return `**Status:** ${newStatus}\n\n${rawMarkdown}`;
+    }
+    const insertAt = h1Match.index + h1Match[0].length;
+    const before = rawMarkdown.slice(0, insertAt);
+    const after = rawMarkdown.slice(insertAt);
+    return `${before}\n\n**Status:** ${newStatus}${after}`;
+}
+/**
+ * Append a structured entry to a markdown file's `## Build catalogue
+ * history` section (creating it if missing). This is the audit-trail
+ * surface for write operations whose effect on the markdown is
+ * non-trivial to express by structural edit alone (e.g. AC ticks,
+ * status change rationales).
+ *
+ * Idempotence: each call appends; running the same workflow twice
+ * appends twice. The audit chain in the workflow store is the
+ * deduplicating source of truth.
+ */
+export function appendChangeLog(rawMarkdown, entry) {
+    const heading = '## Build catalogue history';
+    const headingIndex = rawMarkdown.indexOf(heading);
+    const detailLines = [];
+    if (entry.details)
+        detailLines.push(`  - ${entry.details}`);
+    if (entry.reference)
+        detailLines.push(`  - Reference: ${entry.reference}`);
+    const block = [
+        `- **${entry.isoTimestamp}** — ${entry.summary}`,
+        ...detailLines,
+    ].join('\n');
+    if (headingIndex === -1) {
+        const sep = rawMarkdown.endsWith('\n') ? '' : '\n';
+        return `${rawMarkdown}${sep}\n${heading}\n\n${block}\n`;
+    }
+    // Find the end of the file (or the next section) and insert before that.
+    // Simplest: append the block immediately after the existing section's
+    // current content. We treat everything from `headingIndex` to the
+    // next H1/H2 boundary (or EOF) as the section.
+    const tail = rawMarkdown.slice(headingIndex);
+    const nextHeadingMatch = /\n##? \S/.exec(tail.slice(heading.length));
+    if (!nextHeadingMatch) {
+        // History is the last section — append at end of file.
+        const sep = rawMarkdown.endsWith('\n') ? '' : '\n';
+        return `${rawMarkdown}${sep}${block}\n`;
+    }
+    const splitAt = headingIndex + heading.length + nextHeadingMatch.index;
+    const before = rawMarkdown.slice(0, splitAt);
+    const after = rawMarkdown.slice(splitAt);
+    const beforeHasTrailingNewline = before.endsWith('\n');
+    const sep = beforeHasTrailingNewline ? '' : '\n';
+    return `${before}${sep}${block}\n${after}`;
+}

package/dist/runtime/markdown-render.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Per-register markdown renderers — Phase H part 3.
+ *
+ * Each renderer takes a typed workflow payload (from the build-catalogue
+ * pack) and produces a markdown body in the catalogue's house style.
+ * The renderers match the conventions used in the live catalogue:
+ *
+ *   - WU files: `# WU NNN — Title` + `**Status:** ...` + sections for
+ *     outcome / dependencies / contracts produced/consumed / acceptance
+ *     criteria / etc.
+ *   - Decision files: `# DNNN — Title` + `**Status:** ...` +
+ *     Context / Decision / Rationale / Alternatives / Consequences.
+ *   - Open question files: `# QNNN — Title` + `**Status:** ...` +
+ *     Why it matters / Options / Evidence needed / Blocks.
+ *   - Persona files: `# PNNN — Title` + seven dimensions + acid-test.
+ *
+ * The renderers are deliberately conservative: they produce markdown
+ * that matches the live convention closely so future hand-edits don't
+ * collide with the renderer's output. Round-trip with the migration
+ * runner: render → write → migrate → store record's rawMarkdown ==
+ * what we just rendered.
+ */
+import type { WorkUnitCreatePayload, DecisionCreatePayload, OpenQuestionCreatePayload, PersonaCreatePayload } from '@nusoft/nuflow-pack-nuos-build-catalogue';
+export declare function renderWorkUnit(payload: WorkUnitCreatePayload): string;
+export declare function renderDecision(payload: DecisionCreatePayload): string;
+export declare function renderOpenQuestion(payload: OpenQuestionCreatePayload): string;
+export declare function renderPersona(payload: PersonaCreatePayload): string;