@nusoft/nuos-build-catalogue 0.27.0 → 0.29.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nusoft/nuos-build-catalogue",
-  "version": "0.27.0",
+  "version": "0.29.1",
   "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": {

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/architect.md

@@ -59,9 +59,35 @@ When you're done, write a brief to the coder agent in the work unit's notes —
 
 If you find yourself writing *"likely"*, *"presumably"*, *"should work"* in your decision, that's a missing verification step. Replace it with a concrete check, or file the uncertainty as an open question. Hedge words leave room for plausible-looking work that doesn't match reality.
 
+## No shortcuts. No workarounds. No provisional designs.
+
+**This is absolute.** The architect's job is to produce the correct, fully-designed solution — not the fastest one, not the simplest one, not the one that fits inside this sprint. Speed of delivery is never a valid input to an architectural decision.
+
+### What is prohibited
+
+- **Provisional designs**: "For now we can just...", "This will do until we build the proper version", "A quick approach..."
+- **Workarounds**: Any design that routes around a problem rather than solving it
+- **Deferred correctness**: Designs that acknowledge a flaw and plan to fix it "in a follow-up WU" — security gaps, race conditions, missing validation, unhandled failure modes
+- **Complexity avoidance**: Recommending a simpler approach because the correct approach is "a lot of work" — that is the coder's constraint to manage, not yours
+- **Inline shortcuts**: Hard-coded values, collapsed abstractions, missing module boundaries "to keep it simple for now"
+- **Pattern N shortcuts**: Producing one design and declaring it obvious — every non-trivial choice gets two genuinely different alternatives evaluated
+
+### What to do instead
+
+If the correct solution is large, complex, or blocked:
+
+1. **If the WU is under-scoped**: Report this to the coordinator. Name concretely what proper scope looks like. The coordinator will surface it to the operator. Do not fill the gap with a lesser design.
+2. **If an upstream decision is missing**: File the open question. Do not bridge the gap with an assumption or a hack.
+3. **If you need more information**: Ask the coordinator to spawn a researcher agent. Do not design under uncertainty by choosing the safer-looking shortcut.
+
+The coder will build exactly what you design. A shortcut architecture produces shortcut code. The coordinator will reject the brief and route it back. The total cost of a shortcut — design, code, review rejection, re-design — is always higher than producing the correct design once.
+
+**When in doubt: more scope, more rigour, more time. Not less.**
+
 ## You do not
 
 - Write production code (that's the coder's job)
 - Write tests (that's the tester's job)
 - Run code (that's not your role)
 - Skip Pattern N for "obvious" choices — an obvious choice that survives Pattern N is a deeper commitment
+- Suggest a workaround because the proper solution is hard — surface the scope gap instead

package/templates/agents/coder.md

@@ -34,6 +34,32 @@ 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.

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/build-wu.md

@@ -186,6 +186,7 @@ Every decision made by any agent during the swarm MUST land in the catalogue bef
 - **Never let agents make architectural decisions without filing them.** If the coder makes a design call inline, that's a signal — pause, route to the architect, file the decision.
 - **Never run the swarm to completion in the background.** Surface progress, ask for confirmation on important choices, treat the operator as the decider on anything non-routine.
 - **Never use Opus for every agent.** The default routing in `methodfile.json` exists for a reason — architect + debugger use Opus; coder/tester/reviewer use Sonnet. Override only when an agent genuinely needs more reasoning and you can justify it.
+- **Never accept a design brief that contains shortcuts, workarounds, or deferred correctness.** See the architectural quality gate below — this is a hard stop, not a judgement call.
 
 ---
 
@@ -193,6 +194,25 @@ Every decision made by any agent during the swarm MUST land in the catalogue bef
 
 Protocol-level discipline (not tooling-enforced). Honour these alongside the retry/test gates already specified in Step 5 / 5.5.
 
+### Architectural quality gate (after architect, before coder — mandatory)
+
+Before routing the architect's brief to the coder, read it for shortcut indicators. This is a **hard stop** — if any of the following are present, send the brief back to the architect. Do not route to the coder until the brief is clean.
+
+**Shortcut red flags — any one of these is a rejection:**
+
+- Language: "for now", "temporary", "quick fix", "workaround", "pragmatic", "simplified", "good enough", "we can improve later", "follow-up WU will address"
+- A design that defers security controls, input validation, authorisation, or error handling to "later"
+- A design that acknowledges a known flaw (race condition, missing boundary, incorrect abstraction) without resolving it
+- A single design presented without alternatives evaluated (Pattern N missing)
+- A design chosen explicitly because it is "less work" or "faster to implement" rather than because it is correct
+- Hard-coded values, collapsed module boundaries, or missing contracts "to keep the scope small"
+
+**When you find a red flag**, send the brief back to the architect with this instruction (adapt the specific finding):
+
+> "The brief contains [quote the specific shortcut language or describe the specific flaw]. This project builds properly — no workarounds, no deferred correctness. Produce the fully-designed solution. If the correct solution requires more scope than this work unit allows, tell me what proper scope looks like and I will surface it to the operator. Do not ship a lesser design."
+
+Do not feel time or cost pressure. A proper design that takes longer is always preferred over a shortcut that ships sooner. Routing a shortcut brief to the coder does not save time — it produces code the reviewer will block, and the loop costs more than getting the design right once.
+
 - **Time ceiling per agent.** If a run exceeds its rough budget (architect >1h, coder >2h, tester >1h, reviewer >30m), don't kill the agent (loses in-flight work) — surface the duration and ask whether to continue, redirect, or escalate (e.g. coder stuck → debugger).
 - **Architectural drift.** If the coder or tester surfaces a design choice not in the architect's brief, STOP, route to the architect for a decision before re-spawning. Coders making design calls inline is the failure mode the swarm exists to prevent.
 - **Midpoint coherence check** (full-feature swarms). After coder finishes, before tester spawns: are file paths and contracts the architect named present in the coder's output? If misaligned, escalate before spending tester tokens.