@nusoft/nuos-build-catalogue 0.26.0 → 0.28.0

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.26.0",
+  "version": "0.28.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/mode.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/scripts/hooks/pre-commit

@@ -68,7 +68,8 @@ check_index_drift() {
   ids_in_tree=$(cd "$REPO_ROOT/$dir" && {
     find . -maxdepth 2 -type f -name "*.md" \
       -not -name "_index.md" \
-      -not -name "*-template.md" 2>/dev/null \
+      -not -name "*-template.md" \
+      -not -name "*-template-*.md" 2>/dev/null \
       | sed -nE "$file_regex" \
       | sort -u
   })

package/templates/agents/coder.md

@@ -34,19 +34,47 @@ nuos-catalogue memory store --value="<what worked and why, or what to avoid>" --
 
 If anything in the work unit is ambiguous, **stop and surface the ambiguity to the coordinator** rather than guessing. A guess produces work that may not match the design.
 
+## Design system gate (UI work — enforced by hook)
+
+**If this work unit touches any UI file (`.css`, `.scss`, `.less`, `.html`, `.tsx`, `.jsx`, `.vue`, `.svelte`, `.astro`), a write-gate hook is active. It will BLOCK the write and force you back here.**
+
+Before writing any UI file, complete these steps in order:
+
+1. **Read the design system — all of it:**
+   - `docs/build/design-system/tokens-colour.md` — every colour token and its hex value
+   - `docs/build/design-system/tokens-typography.md` — font sizes, weights, line heights
+   - `docs/build/design-system/tokens-spacing.md` — the spacing scale
+   - `docs/build/design-system/tokens-radius-elevation.md` — border radius, shadows
+
+2. **Identify the token reference pattern this project uses** — read two or three existing UI files to confirm one of:
+   - CSS custom properties: `color: var(--colour-text-primary);`
+   - Theme/token object: `color: theme.colour.text.primary`
+   - Utility class config: project-configured Tailwind or similar
+
+3. **Map every value to a token before writing a single line.** If a colour, size, or spacing value you need has no token in the design system, **stop and surface the gap to the coordinator** — do not invent a value or use a hardcode.
+
+The hook checks for:
+- Raw hex literals in colour properties: `color: #1a2b3c` — BLOCKED
+- Hex strings in JSX inline styles: `color: '#fff'` — BLOCKED
+- Hex colours in HTML style attributes — BLOCKED
+
+CSS custom property definitions (`--colour-x: #hex`) are allowed — that is where the token value lives. Everything else must use the token by name.
+
 ## How you work
 
 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. **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.
 
-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.
+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.
 
-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.
+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.
 
-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.
+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.
 
-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.
+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.
 

package/templates/claude-hooks/check-design-system-compliance.sh

@@ -0,0 +1,211 @@
+#!/usr/bin/env bash
+#
+# NuOS Build Method — Design System Compliance Hook (PreToolUse)
+#
+# Blocks Write / Edit / MultiEdit when:
+#   (a) the target file is a UI file (.css, .scss, .less, .html, .tsx,
+#       .jsx, .vue, .svelte, .astro), AND
+#   (b) the written content contains hardcoded colour values (hex literals,
+#       CSS named colours) in colour-property positions, AND
+#   (c) the project has a design system at docs/build/design-system/
+#
+# Rationale
+# ─────────
+#   Agents write UI code without first reading the design system, producing
+#   raw hex values that bypass the project's token contracts. The reviewer
+#   agent catches this after the fact — but by then the coder has already
+#   satisfied its acceptance criteria and treats the finding as "cleanup."
+#   This hook closes the gap at the moment of writing: the write is blocked
+#   and the agent is shown exactly where to look before it can retry.
+#
+# What is checked
+# ───────────────
+#   1. CSS/SCSS/Less: colour property with hardcoded hex literal
+#        color: #fff       ← BLOCKED
+#        --colour-x: #fff  ← allowed (token definition line; starts with --)
+#        color: var(--x)   ← allowed
+#   2. JSX/TSX: inline style object with hex string
+#        color: '#1a2b3c'  ← BLOCKED
+#   3. HTML: style attribute containing a hex colour
+#        style="color: #fff"  ← BLOCKED
+#
+# Degrade-safe: if content cannot be reliably parsed (no jq or python3,
+# or parse failure), the hook exits 0. Never block on ambiguous input.
+#
+# Exit codes
+# ──────────
+#   0 — allow (no violations, design system absent, or degrade-safe skip)
+#   2 — block (stderr is surfaced to the model by Claude Code)
+
+set -uo pipefail
+
+INPUT="$(cat 2>/dev/null || true)"
+
+# ── Project root ──────────────────────────────────────────────────────────────
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-}"
+if [[ -z "$PROJECT_ROOT" ]]; then
+  PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+fi
+if [[ -z "$PROJECT_ROOT" ]]; then exit 0; fi
+
+# ── Extract file path ─────────────────────────────────────────────────────────
+FILE=$(printf '%s' "$INPUT" \
+  | grep -oE '"(file_path|notebook_path)"[[:space:]]*:[[:space:]]*"[^"]+"' \
+  | head -1 \
+  | sed -E 's/"(file_path|notebook_path)"[[:space:]]*:[[:space:]]*"//' \
+  | tr -d '"')
+
+if [[ -z "${FILE:-}" ]]; then exit 0; fi
+
+# Normalise to absolute path
+case "$FILE" in
+  /*) ABSOLUTE_FILE="$FILE" ;;
+  *)  ABSOLUTE_FILE="$(pwd)/$FILE" ;;
+esac
+
+# ── Skip the design-system directory itself ───────────────────────────────────
+if [[ "$ABSOLUTE_FILE" == *"/docs/build/design-system/"* ]]; then
+  exit 0
+fi
+
+# Skip generated output directories
+case "$ABSOLUTE_FILE" in
+  */node_modules/*|*/dist/*|*/.next/*|*/build/*|*/.nuxt/*) exit 0 ;;
+esac
+
+# ── Only check UI file types ──────────────────────────────────────────────────
+EXTENSION="${FILE##*.}"
+case "$EXTENSION" in
+  css|scss|less|html|tsx|jsx|vue|svelte|astro) : ;;
+  *) exit 0 ;;
+esac
+
+# ── Find the design system ────────────────────────────────────────────────────
+DS_DIR=""
+if [[ -d "$PROJECT_ROOT/docs/build/design-system" ]]; then
+  DS_DIR="$PROJECT_ROOT/docs/build/design-system"
+else
+  # Split-repo pattern: look for a sibling catalogue that owns the design system
+  PARENT="$(dirname "$PROJECT_ROOT")"
+  for sibling in "$PARENT"/*/docs/build/design-system; do
+    if [[ -d "$sibling" ]]; then
+      DS_DIR="$sibling"
+      break
+    fi
+  done
+fi
+
+if [[ -z "$DS_DIR" ]]; then exit 0; fi
+
+COLOUR_FILE="$DS_DIR/tokens-colour.md"
+if [[ ! -f "$COLOUR_FILE" ]]; then exit 0; fi
+
+# ── Extract the content being written ─────────────────────────────────────────
+# Write  → tool_input.content
+# Edit   → tool_input.new_string
+# MultiEdit → tool_input.edits[].new_string (joined)
+CONTENT=""
+if command -v jq &>/dev/null; then
+  CONTENT=$(printf '%s' "$INPUT" | jq -r '
+    .tool_input.content //
+    .tool_input.new_string //
+    (.tool_input.edits // [] | map(.new_string // "") | join("\n")) //
+    ""
+  ' 2>/dev/null || true)
+elif command -v python3 &>/dev/null; then
+  CONTENT=$(printf '%s' "$INPUT" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    ti = d.get('tool_input', {})
+    out = ti.get('content') or ti.get('new_string')
+    if out is None:
+        edits = ti.get('edits', [])
+        out = '\n'.join(e.get('new_string', '') for e in edits)
+    print(out or '')
+except: pass
+" 2>/dev/null || true)
+fi
+
+if [[ -z "${CONTENT:-}" ]]; then exit 0; fi
+
+# ── Detect hardcoded colour violations ───────────────────────────────────────
+
+# 1. CSS/SCSS/Less: colour property with a hex literal value.
+#    Excludes lines that start with optional whitespace followed by '--'
+#    (those are CSS custom property definitions — they SET the token value).
+CSS_HEX=$(printf '%s' "$CONTENT" \
+  | grep -E '(color|background(-color)?|border(-color)?|fill|stroke|outline(-color)?|accent-color)[[:space:]]*:[[:space:]]*#[0-9a-fA-F]{3,8}' \
+  | grep -vE '^\s*--' \
+  | grep -oE '(color|background(-color)?|border(-color)?|fill|stroke|outline(-color)?|accent-color)[[:space:]]*:[[:space:]]*#[0-9a-fA-F]{3,8}' \
+  | head -3 || true)
+
+# 2. JSX/TSX: inline style object with a hex colour string.
+#    e.g. color: '#fff'  or  backgroundColor: "#1a2b3c"
+JSX_HEX=$(printf '%s' "$CONTENT" \
+  | grep -oE "(color|backgroundColor|borderColor|fill|stroke|outlineColor)[[:space:]]*:[[:space:]]*['\"]#[0-9a-fA-F]{3,8}" \
+  | head -3 || true)
+
+# 3. HTML: style attribute that contains a hex colour value.
+HTML_HEX=$(printf '%s' "$CONTENT" \
+  | grep -oE 'style=[^>]*#[0-9a-fA-F]{3,8}' \
+  | head -3 || true)
+
+if [[ -z "${CSS_HEX:-}" && -z "${JSX_HEX:-}" && -z "${HTML_HEX:-}" ]]; then
+  exit 0
+fi
+
+# ── Build the violation summary ───────────────────────────────────────────────
+VIOLATIONS=""
+[[ -n "${CSS_HEX:-}" ]]  && VIOLATIONS="$VIOLATIONS
+   CSS:  $(printf '%s' "$CSS_HEX" | head -1)"
+[[ -n "${JSX_HEX:-}" ]]  && VIOLATIONS="$VIOLATIONS
+   JSX:  $(printf '%s' "$JSX_HEX" | head -1)"
+[[ -n "${HTML_HEX:-}" ]] && VIOLATIONS="$VIOLATIONS
+   HTML: $(printf '%s' "$HTML_HEX" | head -1)"
+
+# ── Read token excerpt for the error message ──────────────────────────────────
+TOKEN_HINT=""
+TOKEN_EXCERPT=$(grep -E '`colour\.' "$COLOUR_FILE" 2>/dev/null | head -12 || true)
+if [[ -n "$TOKEN_EXCERPT" ]]; then
+  TOKEN_HINT="
+Available colour tokens (from $(basename "$DS_DIR")/tokens-colour.md):
+$TOKEN_EXCERPT
+
+  → Use the token name. Do NOT use the raw hex value."
+fi
+
+# ── Block ─────────────────────────────────────────────────────────────────────
+cat >&2 <<EOF
+✖ nuos: design-system compliance block — hardcoded colour values detected.
+
+   File:       $FILE
+   Violations:$VIOLATIONS
+
+   ── Required action ──────────────────────────────────────────────────────────
+
+   Before writing any UI file you MUST:
+
+     1. Read the full design system:
+          $DS_DIR/tokens-colour.md
+          $DS_DIR/tokens-typography.md
+          $DS_DIR/tokens-spacing.md
+          $DS_DIR/tokens-radius-elevation.md
+
+     2. Identify how this project references tokens by reading existing UI
+        files in the codebase — look for one of these patterns:
+          CSS custom properties:  color: var(--colour-text-primary);
+          JSX theme object:       color: theme.colour.text.primary
+          Tailwind config tokens: text-text-primary (if configured)
+
+     3. Replace EVERY hardcoded hex or named colour with the correct token
+        reference. If no token covers the value you need, STOP and surface
+        the gap to the coordinator — do NOT invent a one-off value.
+
+   This hook will block every write that contains a raw colour value.
+   The design system is the contract; the implementation must honour it.
+$TOKEN_HINT
+
+EOF
+
+exit 2

package/templates/protocols/end-of-session.md

@@ -67,7 +67,13 @@ Create `docs/build/sessions/YYYY-MM-DD-short-slug.md`. The entry includes:
 
 Add a row to `sessions/_index.md`.
 
-### 8. Verify nothing is lost
+### 8. Regenerate HTML companion views (if any visual register changed)
+
+If anything in `ui-ux/`, `design-system/`, `maps/`, or `architecture/` was edited this session, run `nuos-catalogue render` to refresh the companion HTML views (`_view.html` in each of those directories). These are generated artefacts — the markdown stays canonical — but they need to stay in sync so the operator's next review opens current views. Stage the refreshed `_view.html` files for the commit alongside the markdown.
+
+If none of those registers changed, skip this step.
+
+### 9. Verify nothing is lost
 
 Before committing, scan:
 
@@ -78,7 +84,7 @@ Before committing, scan:
 - Cross-references resolve (no dead links)
 - Dates are right
 
-### 9. Commit
+### 10. Commit
 
 Single commit. Message format: