@nusoft/nuos-build-catalogue 0.25.0 → 0.27.0

package/dist/render/maps.js

@@ -0,0 +1,67 @@
+/**
+ * Render the `maps/` register as a single companion HTML page.
+ *
+ * Each map file (`01-the-horizon.md`, `02-phases.md`, `03-near-term.md`, etc.)
+ * is parsed by its `## Section` structure and rendered as a card with the
+ * section contents underneath. Multiple maps become a vertical timeline so the
+ * operator sees them in their intended order (numeric prefix).
+ */
+import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { parseSections, isPlaceholder } from './parser.js';
+import { pageWrapper, card, emptyState, escapeHtml, renderProse, } from './html.js';
+const TEMPLATE_PATTERN = /-template\.md$/i;
+export async function renderMaps(opts) {
+    const dir = path.join(opts.buildRoot, 'maps');
+    const outPath = path.join(dir, '_view.html');
+    if (!existsSync(dir)) {
+        return { written: false, outPath, mapCount: 0 };
+    }
+    const entries = await readdir(dir, { withFileTypes: true });
+    const maps = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        if (entry.name === '_index.md' || TEMPLATE_PATTERN.test(entry.name))
+            continue;
+        const md = await readFile(path.join(dir, entry.name), 'utf8');
+        if (isPlaceholder(md))
+            continue;
+        const titleMatch = md.match(/^#\s+(.+)$/m);
+        maps.push({
+            file: entry.name,
+            title: titleMatch ? titleMatch[1].trim() : entry.name,
+            sections: parseSections(md),
+        });
+    }
+    maps.sort((a, b) => a.file.localeCompare(b.file));
+    const body = maps.length === 0
+        ? card('No maps filed yet', emptyState('Phases A and D of planning produce this content.'))
+        : `<div class="timeline">${maps.map(renderMapCard).join('')}</div>`;
+    const html = pageWrapper({
+        title: 'Maps & journey',
+        projectName: opts.projectName,
+        generatedAt: opts.generatedAt,
+        sourceNote: '<code>docs/build/maps/</code>',
+        body,
+    });
+    await mkdir(dir, { recursive: true });
+    await writeFile(outPath, html, 'utf8');
+    return { written: true, outPath, mapCount: maps.length };
+}
+function renderMapCard(m) {
+    const sectionBlocks = [];
+    for (const [heading, body] of m.sections) {
+        if (heading === '' || heading.toLowerCase() === 'how this map changes')
+            continue;
+        const rendered = body.trim() ? renderProse(body) : '';
+        if (!rendered)
+            continue;
+        sectionBlocks.push(`<h4>${escapeHtml(heading)}</h4>${rendered}`);
+    }
+    return `<section class="card">
+    <h3>${escapeHtml(m.title)}</h3>
+    <div class="card__body">${sectionBlocks.join('')}</div>
+  </section>`;
+}

package/dist/render/parser.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared markdown parsing helpers for the render module.
+ *
+ * The register markdown files in `templates/starter-kit/docs/build/` follow
+ * a few consistent shapes:
+ *   - `## Section` headings with prose underneath (maps, surfaces, modules)
+ *   - GFM tables with a header row, separator row, and data rows (design-system tokens)
+ *   - Inline code in backticks for token names and hex values
+ *
+ * The parsers here are deliberately small and forgiving. If a file diverges
+ * from the template the renderer degrades to plain prose rather than throwing.
+ */
+export interface ParsedTable {
+    headers: string[];
+    rows: string[][];
+}
+/**
+ * Split a markdown document into a map of `## Section` → body text.
+ * Content before the first H2 is filed under the empty string key.
+ * Body text is trimmed and includes any nested headings underneath the H2.
+ */
+export declare function parseSections(md: string): Map<string, string>;
+/**
+ * Parse the first GFM table in a markdown block. Returns null if none found.
+ * Cells with inline code/markdown are kept as-is; the renderer handles inline formatting.
+ */
+export declare function parseTable(md: string): ParsedTable | null;
+/**
+ * Extract every inline-code substring from a markdown blob (e.g. `colour.brand.primary`).
+ */
+export declare function extractInlineCode(md: string): string[];
+/**
+ * Extract every hex colour (`#rgb`, `#rrggbb`, `#rrggbbaa`) from a markdown blob.
+ * Filters out the all-zero `#000000` placeholder *if* the file still looks unfilled,
+ * because the starter-kit template seeds tokens with `#000000` to signal "TBD".
+ */
+export declare function extractHexColours(md: string): string[];
+/**
+ * Return the first non-blank, non-hint paragraph of a markdown block.
+ * "Hint" blockquotes (lines starting with `> *italics*`) are skipped because
+ * they're template scaffolding the operator forgot to delete.
+ */
+export declare function firstParagraph(md: string): string;
+/**
+ * Detect placeholder-only files. A file that still contains the literal
+ * "Replace bracketed placeholders" hint, or whose body is mostly `[bracketed]`
+ * scaffolding, hasn't been filled in yet and shouldn't be rendered as if it had.
+ */
+export declare function isPlaceholder(md: string): boolean;
+/**
+ * Strip the front-matter-y top of a register file: the `>` hint blockquotes and any
+ * **Status:** / **Last updated:** metadata. Leaves the actual content sections intact.
+ */
+export declare function stripPreamble(md: string): string;

package/dist/render/parser.js

@@ -0,0 +1,162 @@
+/**
+ * Shared markdown parsing helpers for the render module.
+ *
+ * The register markdown files in `templates/starter-kit/docs/build/` follow
+ * a few consistent shapes:
+ *   - `## Section` headings with prose underneath (maps, surfaces, modules)
+ *   - GFM tables with a header row, separator row, and data rows (design-system tokens)
+ *   - Inline code in backticks for token names and hex values
+ *
+ * The parsers here are deliberately small and forgiving. If a file diverges
+ * from the template the renderer degrades to plain prose rather than throwing.
+ */
+const HEADING_LINE = /^##\s+(.+?)\s*$/;
+const TABLE_SEPARATOR = /^\|?\s*:?-+:?(\s*\|\s*:?-+:?)+\s*\|?\s*$/;
+const HEX_COLOUR = /#(?:[0-9a-fA-F]{3,8})\b/g;
+const INLINE_CODE = /`([^`]+)`/g;
+const HINT_BLOCKQUOTE = /^>\s*\*[^*]+\*\s*$/;
+/**
+ * Split a markdown document into a map of `## Section` → body text.
+ * Content before the first H2 is filed under the empty string key.
+ * Body text is trimmed and includes any nested headings underneath the H2.
+ */
+export function parseSections(md) {
+    const sections = new Map();
+    const lines = md.split('\n');
+    let currentHeading = '';
+    let currentBody = [];
+    const flush = () => {
+        const body = currentBody.join('\n').trim();
+        if (currentHeading || body)
+            sections.set(currentHeading, body);
+    };
+    for (const line of lines) {
+        const match = HEADING_LINE.exec(line);
+        if (match) {
+            flush();
+            currentHeading = match[1];
+            currentBody = [];
+        }
+        else {
+            currentBody.push(line);
+        }
+    }
+    flush();
+    return sections;
+}
+/**
+ * Parse the first GFM table in a markdown block. Returns null if none found.
+ * Cells with inline code/markdown are kept as-is; the renderer handles inline formatting.
+ */
+export function parseTable(md) {
+    const lines = md.split('\n');
+    for (let i = 0; i < lines.length - 1; i++) {
+        const header = lines[i].trim();
+        const separator = lines[i + 1].trim();
+        if (!header.includes('|') || !TABLE_SEPARATOR.test(separator))
+            continue;
+        const headers = splitTableRow(header);
+        const rows = [];
+        for (let j = i + 2; j < lines.length; j++) {
+            const row = lines[j].trim();
+            if (!row.includes('|'))
+                break;
+            rows.push(splitTableRow(row));
+        }
+        return { headers, rows };
+    }
+    return null;
+}
+function splitTableRow(line) {
+    // Trim leading/trailing pipes; split on |; trim each cell.
+    const trimmed = line.replace(/^\|/, '').replace(/\|$/, '');
+    return trimmed.split('|').map((c) => c.trim());
+}
+/**
+ * Extract every inline-code substring from a markdown blob (e.g. `colour.brand.primary`).
+ */
+export function extractInlineCode(md) {
+    const out = [];
+    let m;
+    const re = new RegExp(INLINE_CODE.source, 'g');
+    while ((m = re.exec(md)) !== null)
+        out.push(m[1]);
+    return out;
+}
+/**
+ * Extract every hex colour (`#rgb`, `#rrggbb`, `#rrggbbaa`) from a markdown blob.
+ * Filters out the all-zero `#000000` placeholder *if* the file still looks unfilled,
+ * because the starter-kit template seeds tokens with `#000000` to signal "TBD".
+ */
+export function extractHexColours(md) {
+    return md.match(HEX_COLOUR) ?? [];
+}
+/**
+ * Return the first non-blank, non-hint paragraph of a markdown block.
+ * "Hint" blockquotes (lines starting with `> *italics*`) are skipped because
+ * they're template scaffolding the operator forgot to delete.
+ */
+export function firstParagraph(md) {
+    const lines = md.split('\n');
+    const para = [];
+    for (const raw of lines) {
+        const line = raw.trim();
+        if (!line) {
+            if (para.length > 0)
+                break;
+            continue;
+        }
+        if (HINT_BLOCKQUOTE.test(line))
+            continue;
+        if (line.startsWith('#')) {
+            if (para.length > 0)
+                break;
+            continue;
+        }
+        para.push(line);
+    }
+    return para.join(' ').trim();
+}
+/**
+ * Detect placeholder-only files. A file that still contains the literal
+ * "Replace bracketed placeholders" hint, or whose body is mostly `[bracketed]`
+ * scaffolding, hasn't been filled in yet and shouldn't be rendered as if it had.
+ */
+export function isPlaceholder(md) {
+    if (/Replace\s+(?:the\s+)?bracketed\s+placeholders?/i.test(md))
+        return true;
+    if (/Delete this hint block/i.test(md))
+        return true;
+    // A title that's itself a bracketed placeholder ("# [Module name]") is the canonical
+    // signal of an unfilled file — title bracketing dominates everything else.
+    const titleMatch = md.match(/^#\s+(.+)$/m);
+    if (titleMatch && /\[[^\]]+\]/.test(titleMatch[1]))
+        return true;
+    // Count [bracketed] vs total non-blank non-heading lines; if dominant, treat as placeholder.
+    const lines = md
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l && !l.startsWith('#') && !l.startsWith('>'));
+    if (lines.length === 0)
+        return true;
+    const bracketed = lines.filter((l) => /^\[.+\]$/.test(l) || /^[-*]\s*\[.+\]/.test(l)).length;
+    return bracketed / lines.length > 0.6;
+}
+/**
+ * Strip the front-matter-y top of a register file: the `>` hint blockquotes and any
+ * **Status:** / **Last updated:** metadata. Leaves the actual content sections intact.
+ */
+export function stripPreamble(md) {
+    const lines = md.split('\n');
+    const out = [];
+    let seenHeading = false;
+    for (const line of lines) {
+        if (HEADING_LINE.test(line))
+            seenHeading = true;
+        if (seenHeading)
+            out.push(line);
+        else if (line.startsWith('# '))
+            out.push(line);
+    }
+    return out.join('\n');
+}

package/dist/render/run.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Orchestrator for `nuos-catalogue render` — generates companion HTML views
+ * for the visual registers (ui-ux, design-system, maps, architecture) from
+ * the canonical markdown.
+ *
+ * Companions are *generated artefacts*, not source. The markdown remains the
+ * source of truth for every agent, every search, every diff. The companion
+ * exists so a human operator can scan visual artefacts (wireframes, swatches,
+ * timelines, module graphs) in their natural medium instead of reading prose
+ * descriptions of them.
+ */
+export declare const RENDERABLE_REGISTERS: readonly ["surfaces", "design-system", "maps", "architecture"];
+export type RenderableRegister = (typeof RENDERABLE_REGISTERS)[number];
+export interface RenderOptions {
+    buildRoot: string;
+    /** Only render these registers (default: all). */
+    only?: RenderableRegister[];
+    /** Override "now" for deterministic output in tests. */
+    now?: () => Date;
+}
+export interface RenderReport {
+    results: {
+        register: RenderableRegister;
+        written: boolean;
+        outPath: string;
+        detail: string;
+    }[];
+}
+export declare function runRender(options: RenderOptions): Promise<RenderReport>;

package/dist/render/run.js

@@ -0,0 +1,92 @@
+/**
+ * Orchestrator for `nuos-catalogue render` — generates companion HTML views
+ * for the visual registers (ui-ux, design-system, maps, architecture) from
+ * the canonical markdown.
+ *
+ * Companions are *generated artefacts*, not source. The markdown remains the
+ * source of truth for every agent, every search, every diff. The companion
+ * exists so a human operator can scan visual artefacts (wireframes, swatches,
+ * timelines, module graphs) in their natural medium instead of reading prose
+ * descriptions of them.
+ */
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { renderSurfaces } from './surfaces.js';
+import { renderDesignSystem } from './design-system.js';
+import { renderMaps } from './maps.js';
+import { renderArchitecture } from './architecture.js';
+export const RENDERABLE_REGISTERS = ['surfaces', 'design-system', 'maps', 'architecture'];
+export async function runRender(options) {
+    const { buildRoot } = options;
+    const targets = options.only ?? [...RENDERABLE_REGISTERS];
+    const now = options.now ?? (() => new Date());
+    const generatedAt = isoDate(now());
+    const projectName = await resolveProjectName(buildRoot);
+    const ctx = { buildRoot, projectName, generatedAt };
+    const report = { results: [] };
+    for (const register of targets) {
+        switch (register) {
+            case 'surfaces': {
+                const r = await renderSurfaces(ctx);
+                report.results.push({
+                    register,
+                    written: r.written,
+                    outPath: r.outPath,
+                    detail: r.written ? `${r.surfaceCount} surfaces` : 'skipped (no ui-ux/)',
+                });
+                break;
+            }
+            case 'design-system': {
+                const r = await renderDesignSystem(ctx);
+                report.results.push({
+                    register,
+                    written: r.written,
+                    outPath: r.outPath,
+                    detail: r.written ? 'rendered' : 'skipped (no design-system/)',
+                });
+                break;
+            }
+            case 'maps': {
+                const r = await renderMaps(ctx);
+                report.results.push({
+                    register,
+                    written: r.written,
+                    outPath: r.outPath,
+                    detail: r.written ? `${r.mapCount} maps` : 'skipped (no maps/)',
+                });
+                break;
+            }
+            case 'architecture': {
+                const r = await renderArchitecture(ctx);
+                report.results.push({
+                    register,
+                    written: r.written,
+                    outPath: r.outPath,
+                    detail: r.written ? `${r.moduleCount} modules` : 'skipped (no architecture/)',
+                });
+                break;
+            }
+        }
+    }
+    return report;
+}
+async function resolveProjectName(buildRoot) {
+    // buildRoot is `<project>/docs/build`; methodfile.json lives at the project root.
+    const projectRoot = path.resolve(buildRoot, '..', '..');
+    const methodfilePath = path.join(projectRoot, 'methodfile.json');
+    if (existsSync(methodfilePath)) {
+        try {
+            const mf = JSON.parse(await readFile(methodfilePath, 'utf8'));
+            if (mf.project?.name)
+                return mf.project.name;
+        }
+        catch {
+            // fall through to directory-name default
+        }
+    }
+    return path.basename(projectRoot);
+}
+function isoDate(d) {
+    return d.toISOString().slice(0, 10);
+}

package/dist/render/surfaces.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Render the `ui-ux/` register as a single companion HTML page.
+ *
+ * Output structure:
+ *   1. Sitemap — every surface listed (linked to its card lower down), grouped
+ *      where possible by the persona handle it serves.
+ *   2. Surface cards — one per surface markdown file, showing type, persona, the
+ *      "What they see" prose, primary actions, contracts touched, design-system
+ *      pieces used.
+ *
+ * The intent is the human-reviewable artefact the markdown can't be:
+ * a non-developer scanning the whole UI surface set in one scroll.
+ */
+export interface SurfaceRenderResult {
+    written: boolean;
+    outPath: string;
+    surfaceCount: number;
+}
+export declare function renderSurfaces(opts: {
+    buildRoot: string;
+    projectName: string;
+    generatedAt: string;
+}): Promise<SurfaceRenderResult>;

package/dist/render/surfaces.js

@@ -0,0 +1,144 @@
+/**
+ * Render the `ui-ux/` register as a single companion HTML page.
+ *
+ * Output structure:
+ *   1. Sitemap — every surface listed (linked to its card lower down), grouped
+ *      where possible by the persona handle it serves.
+ *   2. Surface cards — one per surface markdown file, showing type, persona, the
+ *      "What they see" prose, primary actions, contracts touched, design-system
+ *      pieces used.
+ *
+ * The intent is the human-reviewable artefact the markdown can't be:
+ * a non-developer scanning the whole UI surface set in one scroll.
+ */
+import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { parseSections, firstParagraph, isPlaceholder, } from './parser.js';
+import { pageWrapper, card, emptyState, escapeHtml, renderProse, renderInlineMarkdown, } from './html.js';
+const SKIP_FILES = new Set(['_index.md', 'surface-template.md']);
+export async function renderSurfaces(opts) {
+    const dir = path.join(opts.buildRoot, 'ui-ux');
+    const outPath = path.join(dir, '_view.html');
+    if (!existsSync(dir)) {
+        return { written: false, outPath, surfaceCount: 0 };
+    }
+    const surfaces = await loadSurfaces(dir);
+    const body = renderBody(surfaces);
+    const html = pageWrapper({
+        title: 'Surfaces & sitemap',
+        projectName: opts.projectName,
+        generatedAt: opts.generatedAt,
+        sourceNote: '<code>docs/build/ui-ux/</code>',
+        body,
+    });
+    await mkdir(dir, { recursive: true });
+    await writeFile(outPath, html, 'utf8');
+    return { written: true, outPath, surfaceCount: surfaces.length };
+}
+async function loadSurfaces(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const surfaces = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        if (SKIP_FILES.has(entry.name))
+            continue;
+        const filePath = path.join(dir, entry.name);
+        const md = await readFile(filePath, 'utf8');
+        if (isPlaceholder(md))
+            continue;
+        surfaces.push(parseSurface(entry.name, md));
+    }
+    surfaces.sort((a, b) => a.title.localeCompare(b.title));
+    return surfaces;
+}
+function parseSurface(file, md) {
+    const sections = parseSections(md);
+    const preamble = sections.get('') ?? '';
+    const titleMatch = md.match(/^#\s+(.+)$/m);
+    return {
+        file,
+        slug: file.replace(/\.md$/, ''),
+        title: titleMatch ? titleMatch[1].trim() : file,
+        type: extractMetadata(preamble, 'Type'),
+        status: extractMetadata(preamble, 'Status'),
+        personaRefs: extractPersonaRefs(sections.get('Who uses this surface') ?? ''),
+        sections,
+    };
+}
+function extractMetadata(preamble, key) {
+    const re = new RegExp(`\\*\\*${key}:\\*\\*\\s*(.+)`, 'i');
+    const m = preamble.match(re);
+    return m ? m[1].trim() : null;
+}
+function extractPersonaRefs(body) {
+    const out = [];
+    const re = /P\d{3}/g;
+    let m;
+    while ((m = re.exec(body)) !== null)
+        out.push(m[0]);
+    return Array.from(new Set(out));
+}
+function renderBody(surfaces) {
+    if (surfaces.length === 0) {
+        return card('No surfaces filed yet', emptyState('Phase C of planning produces this content. Once surfaces are filed in docs/build/ui-ux/, this view will render them.'));
+    }
+    return [renderSitemap(surfaces), ...surfaces.map(renderSurfaceCard)].join('\n');
+}
+function renderSitemap(surfaces) {
+    const groups = new Map();
+    for (const s of surfaces) {
+        const key = s.personaRefs.length > 0 ? s.personaRefs.join(', ') : '(no persona linked)';
+        const bucket = groups.get(key) ?? [];
+        bucket.push(s);
+        groups.set(key, bucket);
+    }
+    const sections = [...groups.entries()]
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([persona, group]) => {
+        const items = group
+            .map((s) => {
+            const typeTag = s.type ? ` <span class="tag">${escapeHtml(s.type)}</span>` : '';
+            return `<li><a href="#${escapeHtml(s.slug)}">${escapeHtml(s.title)}</a>${typeTag}</li>`;
+        })
+            .join('');
+        return `<h4>${escapeHtml(persona)}</h4><ul class="sitemap-list">${items}</ul>`;
+    })
+        .join('');
+    return card('Sitemap', sections);
+}
+function renderSurfaceCard(s) {
+    const tags = [];
+    if (s.type)
+        tags.push(`<span class="tag">${escapeHtml(s.type)}</span>`);
+    if (s.status)
+        tags.push(`<span class="tag tag--status">${escapeHtml(s.status)}</span>`);
+    for (const ref of s.personaRefs)
+        tags.push(`<span class="tag">${escapeHtml(ref)}</span>`);
+    const headerTags = tags.length > 0 ? `<div class="card__tags">${tags.join(' ')}</div>` : '';
+    const sectionBlocks = [headerTags];
+    for (const [heading, body] of s.sections) {
+        if (heading === '' || heading.toLowerCase() === 'notes')
+            continue;
+        if (heading === 'Open questions about this surface' && !body.trim())
+            continue;
+        const rendered = body.trim() ? renderProse(body) : '';
+        if (!rendered)
+            continue;
+        sectionBlocks.push(`<h4>${escapeHtml(heading)}</h4>${rendered}`);
+    }
+    // Best-effort wireframe: render the first paragraph of "What they see" as a
+    // hint label inside a skeletal frame. Not a real wireframe — a signal that
+    // this is a surface and roughly what it contains.
+    const seen = s.sections.get('What they see') ?? '';
+    const hint = firstParagraph(seen);
+    const wireframe = hint
+        ? `<div class="wireframe"><div class="wireframe__label">${renderInlineMarkdown(hint).slice(0, 240)}</div></div>`
+        : '';
+    return `<section id="${escapeHtml(s.slug)}" class="card">
+    <h3>${escapeHtml(s.title)}</h3>
+    ${wireframe}
+    <div class="card__body">${sectionBlocks.join('')}</div>
+  </section>`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nusoft/nuos-build-catalogue",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "NuOS build-catalogue tooling: semantic search (WU 110) + migration runner that lifts markdown artefacts into JSON-backed workflow records (WU 111, Phase G).",
   "type": "module",
   "bin": {
@@ -19,7 +19,7 @@
     "build": "rm -rf dist && tsc && chmod +x dist/cli.js",
     "prepublishOnly": "npm run build",
     "verify-storage": "tsx scripts/verify-persistence.ts",
-    "test": "tsx --test tests/chunk.test.ts tests/metadata.test.ts tests/crawl.test.ts tests/migrate.test.ts tests/commands-read.test.ts tests/regenerate.test.ts tests/commands-write.test.ts tests/ac-parse.test.ts tests/create.test.ts tests/init.test.ts tests/wu-111-soak-findings.test.ts tests/plan.test.ts tests/swarm.test.ts tests/setup-progress-bar.test.ts tests/setup-ollama-pull.test.ts tests/setup-run-llm-setup.test.ts tests/wu-active.test.ts tests/install-claude-hooks.test.ts",
+    "test": "tsx --test tests/chunk.test.ts tests/metadata.test.ts tests/crawl.test.ts tests/migrate.test.ts tests/commands-read.test.ts tests/regenerate.test.ts tests/commands-write.test.ts tests/ac-parse.test.ts tests/create.test.ts tests/init.test.ts tests/wu-111-soak-findings.test.ts tests/plan.test.ts tests/mode.test.ts tests/render.test.ts tests/swarm.test.ts tests/setup-progress-bar.test.ts tests/setup-ollama-pull.test.ts tests/setup-run-llm-setup.test.ts tests/wu-active.test.ts tests/install-claude-hooks.test.ts",
     "typecheck": "tsc --noEmit",
     "index": "tsx src/cli.ts index",
     "search": "tsx src/cli.ts search"

package/templates/agents/coder.md

@@ -38,15 +38,17 @@ If anything in the work unit is ambiguous, **stop and surface the ambiguity to t
 
 1. **Plan the change in your head first**, then state it in 1-2 sentences before writing code. Match existing code idioms; don't introduce new patterns the project hasn't adopted.
 
-2. **Make the smallest change that satisfies the work unit's acceptance criteria.** Don't refactor adjacent code "while you're there" unless the work unit explicitly asks for it.
+2. **Search before writing (DRY — strict).** Before adding any new helper, utility, type, component, hook, validator, query, styled primitive, or constant: grep the codebase for one that already does the job — by name (the noun you'd naturally call it), by shape (signature, prop list, structural pattern), and in the conventional locations for the stack (`lib/`, `utils/`, `hooks/`, `components/`, `types/`, `db/queries/`, `schemas/`, equivalents). If found, import and use it (extend in-place if it needs a small addition). If close-but-not-quite, **stop and surface to the coordinator** — extending the existing thing is almost always cheaper than spawning a parallel implementation. This rule applies to new code in *this* WU; pre-existing duplication elsewhere is a follow-up to file, not your job. Search-and-reuse only — this is *not* a directive to extract net-new abstractions; the rule against premature abstraction (point 4) still applies.
 
-3. **Write code that the tester can verify.** Every acceptance criterion in the work unit should be checkable by looking at the running system — your code should make that easy.
+3. **Make the smallest change that satisfies the work unit's acceptance criteria.** Don't refactor adjacent code "while you're there" unless the work unit explicitly asks for it.
 
-4. **Avoid speculative abstractions.** Three similar lines of code beats a premature abstraction. Don't design for hypothetical future requirements. The architect designs; you implement what's needed now.
+4. **Write code that the tester can verify.** Every acceptance criterion in the work unit should be checkable by looking at the running system — your code should make that easy.
 
-5. **No comments unless WHY is non-obvious.** A hidden constraint, a workaround for a specific bug, behaviour that would surprise a reader. If removing the comment wouldn't confuse a future reader, don't write it.
+5. **Avoid speculative abstractions.** Three similar lines of code beats a premature abstraction. Don't design for hypothetical future requirements. The architect designs; you implement what's needed now.
 
-6. **Write testable code (vitest gate).** If `methodfile.json` declares `testing.framework: "vitest"` with `testing.enforced: true`, every source file you create or substantially modify in this WU must end up covered by at least one vitest test — the tester writes them, but your job is to make that cheap. Export the units the tester needs to reach; avoid burying observable logic inside untestable closures; keep side effects at the edges. Files that genuinely can't be unit-tested (pure type declarations, config glue) are fine — flag them in your notes so the reviewer doesn't treat them as drift.
+6. **No comments unless WHY is non-obvious.** A hidden constraint, a workaround for a specific bug, behaviour that would surprise a reader. If removing the comment wouldn't confuse a future reader, don't write it.
+
+7. **Write testable code (vitest gate).** If `methodfile.json` declares `testing.framework: "vitest"` with `testing.enforced: true`, every source file you create or substantially modify in this WU must end up covered by at least one vitest test — the tester writes them, but your job is to make that cheap. Export the units the tester needs to reach; avoid burying observable logic inside untestable closures; keep side effects at the edges. Files that genuinely can't be unit-tested (pure type declarations, config glue) are fine — flag them in your notes so the reviewer doesn't treat them as drift.
 
 ## When you finish
 

package/templates/agents/reviewer.md

@@ -46,13 +46,15 @@ nuos-catalogue memory store --value="<the pattern and why it matters>" --wu=<han
 
 4. **Does it match existing code idioms?** New patterns introduced without justification are a yellow flag — surface them to the coordinator as either "rename to match existing X" or "intentional, file as new pattern in architecture/".
 
-5. **Does it surface or hide changes future work needs to know?** If the coder modified an interface that downstream work depends on, the change should be in a decision file or a contract update — not silent.
+5. **Does new code reinvent something the codebase already has? (DRY — strict.)** For each new helper, utility, type, component, hook, validator, query, styled primitive, or constant the coder added in this WU, grep the codebase for an existing implementation that does the same job — by name, by signature/shape, and in the conventional locations for the stack (`lib/`, `utils/`, `hooks/`, `components/`, `types/`, `db/queries/`, `schemas/`, equivalents). If you find one, raise a **BLOCKER** citing the existing path; the coder must reuse it (extending the existing one in place if needed) rather than ship a parallel implementation. This applies only to *new* code in this WU vs. the *existing* codebase — don't flag duplication within the WU's own output as a violation; the rule against premature abstraction still governs net-new shared code.
 
-6. **Is there dead-weight or scope creep?** Refactors adjacent to the work unit that weren't asked for. Speculative abstractions. Unnecessary comments. Half-implementations of features not in this work unit.
+6. **Does it surface or hide changes future work needs to know?** If the coder modified an interface that downstream work depends on, the change should be in a decision file or a contract update — not silent.
 
-7. **Is jargon being introduced into user-facing copy?** If the work unit serves a non-engineer persona, the surface text should match the project's voice file. Flag anything that sounds like dev-speak in a user-facing surface.
+7. **Is there dead-weight or scope creep?** Refactors adjacent to the work unit that weren't asked for. Speculative abstractions. Unnecessary comments. Half-implementations of features not in this work unit.
 
-8. **Does the vitest gate pass (JS/TS projects)?** If `methodfile.json` declares `testing.framework: "vitest"` with `testing.enforced: true`, run both gates from [build-wu.md §Step 5.5](../protocols/build-wu.md):
+8. **Is jargon being introduced into user-facing copy?** If the work unit serves a non-engineer persona, the surface text should match the project's voice file. Flag anything that sounds like dev-speak in a user-facing surface.
+
+9. **Does the vitest gate pass (JS/TS projects)?** If `methodfile.json` declares `testing.framework: "vitest"` with `testing.enforced: true`, run both gates from [build-wu.md §Step 5.5](../protocols/build-wu.md):
    - **Gate A:** Run `npx vitest run` (or whatever `testing.command` says) from the implementation repo root. Capture the full output. Non-zero exit → BLOCKER finding with the failing test list.
    - **Gate B:** Compute `git diff --name-only <swarm-base>...HEAD`, filter to source files (`.ts/.tsx/.js/.jsx` under `src/`, `app/`, `routes/`, `pages/`, `lib/`, `components/`, `api/` — exclude `*.test.*`, `*.spec.*`, `*.d.ts`, configs). For each remaining file, grep the test directories for an import of that module or a colocated `*.test.*` file. Any uncovered file → BLOCKER finding naming the file. The coder may rebut by flagging files as genuinely untestable (type-only, config glue) in the WU notes — accept those rebuttals when reasonable.