@nusoft/nuos-build-catalogue 0.29.1 → 0.30.1

package/package.json

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

@@ -8,6 +8,12 @@ You are the **swarm coordinator** for a project using the NuOS Build Method cata
 
 ---
 
+## Step 0 — Verify the build memory CLI is installed
+
+Run: `which nuos-catalogue || npm install -g @nusoft/nuos-build-catalogue`
+
+This CLI powers the build memory system. It is a global npm tool with no presence in any project `package.json` — it disappears silently when global npm packages are cleared. If it was missing, note it to the operator before proceeding: memories from recent swarms were silently dropped. After installing, run the memory pre-flight search in Step 1 with a fresh install and note the gap in the swarm audit entry.
+
 ## Step 1 — Read the work unit and search memory
 
 The handle comes from the operator (e.g. `WU 007`, `wu-007`, or `007`). Normalise to canonical (`wu-007`), then read the file at `docs/build/work-units/NNN-slug.md` (or `done/` if completed).
@@ -100,10 +106,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.
@@ -123,6 +161,27 @@ If either gate fails, re-spawn agents per the retry rules in Step 5. Gate failur
 
 **Non-JS projects:** Skip this gate but note in the audit entry that the WU shipped without an enforced test gate (e.g. *"Python project — vitest gate N/A; pytest suite run separately"*).
 
+## Step 5.6 — Playwright e2e gate (when configured)
+
+If `methodfile.json` has `e2e.enabled: true`, run the Playwright test suite from the implementation repo **before the developer walkthrough and before promotion**.
+
+1. Check for a WU-specific spec at `<e2e.testDir>/<wu-slug>.spec.ts` (e.g. `e2e/wu-181.spec.ts`). If it exists, run only that file: `npx playwright test <path>`. If no WU-specific spec exists, run the full suite: `<e2e.command>` (default `npx playwright test`).
+2. The command must exit 0. Capture full stdout + stderr.
+3. **On failure:** escalate to the coder with the Playwright output. A Playwright fix-pass follows the same retry logic as Step 5 — counts against the same 3-attempt cap.
+4. **On pass:** record `✓ Playwright gate passed (N tests)` in the swarm audit entry under `## Test gate`.
+
+**methodfile.json e2e shape:**
+```json
+"e2e": {
+  "enabled": true,
+  "framework": "playwright",
+  "command": "npx playwright test",
+  "testDir": "apps/web/e2e"
+}
+```
+
+If `methodfile.json` has no `e2e` section or `e2e.enabled: false`, skip this gate but note in the audit entry: *"Playwright gate skipped — e2e not configured in methodfile.json"*. For UI-surfacing work units (any WU that adds or changes a page, component, or user interaction), prompt the developer: *"This WU ships a UI change but no Playwright spec exists. Want me to file a follow-up WU to add e2e coverage for this surface?"*
+
 ## Step 6 — Record the swarm run
 
 Write an audit entry at `docs/build/swarm/YYYY-MM-DD-wu-<handle>.md`. Use the template at `docs/build/swarm/_template.md`. Capture:

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

@@ -2,6 +2,12 @@
 
 You are starting a session on a project that uses the **NuOS Build Method catalogue**. Your job is to read where the project is right now and tell the operator in plain English, then propose the next action and wait for confirmation.
 
+## Step 0a — Verify the build memory CLI is installed (every session)
+
+Run: `which nuos-catalogue || npm install -g @nusoft/nuos-build-catalogue`
+
+This CLI powers the build memory system (`nuos-catalogue memory store/search`). It is a global npm tool with no presence in any project `package.json` — so it disappears silently when global npm packages are cleared (Node.js update, Homebrew update, etc.). If it was missing and you just installed it, tell the operator. The gap is real — memories from recent swarms may not have been stored. After installing, run `nuos-catalogue memory search --query="<active WU title>" --limit=5` to check what is indexed.
+
 ## Step 0 — Operator mode
 
 Read `methodfile.json`'s `operator.mode`: