@nusoft/nuos-build-catalogue 0.28.0 → 0.30.0

package/package.json

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

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

@@ -100,10 +100,42 @@ For each spawn:
 
 When each agent returns, capture their output. Three outcomes are typical:
 
-- **APPROVED** by reviewer → work unit is ready to promote ✅ shipped. Run end-of-session to commit.
+- **APPROVED** by reviewer → do NOT promote yet. Go to Step 5.1 — developer walkthrough.
 - **REQUEST CHANGES** by reviewer → re-spawn coder with reviewer's findings as input. Cap at 3 retry loops; if still failing, escalate to debugger or operator.
 - **ESCALATE** (any agent surfaces an architectural issue, a design ambiguity, a need for the operator's call) → STOP the swarm. Surface the issue to the operator in plain English; do not auto-decide.
 
+## Step 5.1 — Developer walkthrough (mandatory before promotion)
+
+The reviewer has approved. Before the work unit is promoted to shipped, **stop and brief the developer** so they can verify the feature themselves in their running dev environment.
+
+Write a short, plain-English walkthrough that tells the developer:
+
+1. **What was built** — one or two sentences describing the feature or change in terms of what it does, not how it was coded.
+2. **How to see it** — the exact steps to exercise the feature right now: which URL to open, which screen to navigate to, which action to take, which data to enter. Be specific enough that someone can follow without guessing.
+3. **What to look for** — what correct behaviour looks like at each step. What should appear, what should happen, what should NOT happen.
+4. **Any edge cases worth checking** — a second scenario or error path that is worth a quick manual check given what was built.
+
+Example format:
+
+---
+**What was built:** The password reset email now sends within 5 seconds and links to the new `/reset` page.
+
+**How to test it:**
+1. Go to `/login` and click "Forgot password"
+2. Enter any registered email address and submit
+3. Check that email inbox — the reset email should arrive within 5 seconds
+4. Click the link in the email — it should open `/reset?token=…` and show the new password form
+
+**What correct looks like:** The form accepts the new password, shows a confirmation message, and redirects to `/login`. The old password no longer works.
+
+**Worth checking:** Try submitting the reset form twice — the second submission should show "link expired", not an error page.
+
+---
+
+Then ask: **"Does everything look right? Reply 'yes' to promote this work unit, or tell me what you found and I'll route it back to the coder."**
+
+**Do not promote, do not run end-of-session, do not move to Step 6 until the developer explicitly confirms.**
+
 ## Step 5.5 — Run the test gate (JS/TS projects)
 
 If `methodfile.json` has `testing.framework: "vitest"` and `testing.enforced: true`, this gate is mandatory before the reviewer's APPROVE can stand. The reviewer is responsible for running it (see [reviewer.md](../agents/reviewer.md)), but the coordinator owns the outcome.
@@ -186,6 +218,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 +226,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.