@nusoft/nuos-build-catalogue 0.24.0 → 0.25.0

package/package.json

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

@@ -46,6 +46,8 @@ If anything in the work unit is ambiguous, **stop and surface the ambiguity to t
 
 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. **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
 
 Append a brief note to the work unit's `## Notes / log` section:

package/templates/agents/reviewer.md

@@ -52,6 +52,10 @@ nuos-catalogue memory store --value="<the pattern and why it matters>" --wu=<han
 
 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.
 
+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):
+   - **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.
+
 ## How you write findings
 
 Each finding has:

package/templates/agents/tester.md

@@ -39,9 +39,11 @@ nuos-catalogue memory store --value="<what you learned about testing this area>"
 
 3. **Failure paths matter as much as happy paths.** If the work unit's walkthrough mentions what happens when data is missing or the user makes a mistake, write a test for each.
 
-4. **Use the existing test idioms.** Don't introduce a new assertion library, a new fixture pattern, or a new way of mocking. If the project uses `node:test`, use it. If it uses Vitest, use Vitest.
+4. **Use the framework declared in `methodfile.json`'s `testing.framework`.** For JS/TS projects this defaults to **vitest** — the harness pre-wires it. If `testing.framework` is null or names a non-vitest runner (e.g. `pytest`), match the project's existing idiom instead. Never silently switch frameworks; if the declared framework is missing from the repo, escalate to the coordinator before writing tests.
 
-5. **Tests must be reproducible.** No flaky timing, no relying on order, no shared mutable state between tests unless the framework explicitly supports it.
+5. **Per-touched-file coverage is mandatory (vitest gate).** When `testing.framework` is vitest and `testing.enforced` is true, every source file the coder created or substantially modified in this WU must have at least one test file referencing it. Run `git diff --name-only <swarm-base>...HEAD` to get the list. For each `.ts/.tsx/.js/.jsx` file under `src/`, `app/`, `routes/`, `pages/`, `lib/`, `components/`, or `api/` (excluding test files, `.d.ts`, configs), write or extend a test that imports the module and exercises observable behaviour. Colocated (`foo.test.ts` next to `foo.ts`) or `tests/`-mirrored layout — match what already exists.
+
+6. **Tests must be reproducible.** No flaky timing, no relying on order, no shared mutable state between tests unless the framework explicitly supports it.
 
 ## When you run the tests
 

package/templates/protocols/build-wu.md

@@ -88,6 +88,14 @@ Use Claude Code's **Task tool**. Each spawn names the agent (`subagent_type`), t
 
 Omit `null` fields. If `techStack.defined` is `false` or the section is absent, note it in the swarm audit entry and suggest the operator define the stack (`/plan-orientation` or edit `methodfile.json` directly) before the next swarm run — agents generating code without a known stack default to generic patterns that often need rework.
 
+**Vitest pre-flight (JS/TS projects only).** Before spawning the coder, check `methodfile.json`'s `testing` block. If `testing.framework` is `vitest` and `testing.enforced` is `true`, verify the implementation repo has vitest installed and a `vitest.config.ts` (or `.js`/`.mts`) present. If either is missing, before any agent runs:
+
+1. Surface to the operator in one line: *"Vitest is the declared test runner but isn't wired up in the implementation repo yet. I'll install it (`npm i -D vitest @vitest/coverage-v8`) and drop a minimal `vitest.config.ts` before the coder starts. OK?"*
+2. On confirmation: (a) run `npm i -D vitest @vitest/coverage-v8` in the implementation repo; (b) copy the harness's `vitest.config.ts` template into the repo root and `example.test.ts` into `tests/example.test.ts` (create the directory if missing). The templates ship inside the installed harness package at `node_modules/@nusoft/nuos-build-catalogue/templates/testing/` — read them from there; if the harness is being run from a checkout, they're at `<harness-repo>/templates/testing/`; (c) add a `"test": "vitest run"` script to the implementation repo's `package.json` if absent; (d) run `npx vitest run` once to confirm the wiring works.
+3. Record the setup in the swarm audit entry under a `## Setup` section so the next swarm doesn't repeat the check.
+
+If `testing.framework` is not vitest (e.g. the project is Python), skip this pre-flight — the existing "match the project's idiom" rule applies.
+
 **Spawn in parallel where possible.** If two agents can work independently (e.g. tester writing tests while reviewer reads design), spawn them in the same message. Sequential when an agent's output is the next agent's input (architect → coder).
 
 For each spawn:
@@ -102,6 +110,25 @@ When each agent returns, capture their output. Three outcomes are typical:
 - **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.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.
+
+**Gate A — the suite passes:** Run the command in `testing.command` (default `npx vitest run`) from the implementation repo root. The command must exit 0. Capture full output. If any test fails, the gate fails — re-spawn the coder + tester with the failure output, counted against the retry cap in Step 5.
+
+**Gate B — every touched source file is covered:**
+
+1. Compute the WU's changed files: `git diff --name-only <base>...HEAD` where `<base>` is the swarm's starting commit (recorded in the audit entry's `## Setup` section, or `HEAD~1` if not).
+2. Filter to source files: anything matching `*.ts`, `*.tsx`, `*.js`, `*.jsx` under `src/`, `app/`, `routes/`, `pages/`, `lib/`, `components/`, or `api/`. Exclude `*.test.*`, `*.spec.*`, `*.d.ts`, config files, and anything under `node_modules/`, `dist/`, `build/`, `.next/`.
+3. For each remaining file, check at least one `.test.ts(x)` or `.spec.ts(x)` references it. Acceptable references: (a) an `import` statement naming the file's module path, (b) a colocated `foo.test.ts` next to `foo.ts`, (c) a `tests/foo.test.ts` whose basename matches.
+4. Any source file with no matching test is a Gate B failure. Re-spawn the tester with the uncovered file list and a directive to add at least one passing test per file.
+
+If both gates pass, record `✓ vitest gate passed (N tests, M files covered)` in the swarm audit entry under `## Test gate` and continue to Step 6.
+
+If either gate fails, re-spawn agents per the retry rules in Step 5. Gate failures count against the 3-attempt cap. After the third failure, escalate to the operator in plain English: *"After three attempts the vitest gate still fails on [list]. Either the tests need redesign or the touched files genuinely shouldn't be tested (config glue, declaration files). How would you like to proceed?"*
+
+**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 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:
@@ -213,6 +240,10 @@ For full-feature swarms (architect → coder → tester → reviewer), after the
 
 If anything looks misaligned, escalate to the operator before spending more tokens on the tester.
 
+### Vitest test gate (JS/TS projects)
+
+Step 5.5 above defines the gate in full. Restated as a verification rule: a JS/TS work unit cannot promote with reviewer APPROVE unless `vitest run` exits 0 AND every source file the WU touched has at least one test file referencing it. The reviewer runs the gate; the coordinator enforces the outcome. This is the load-bearing gate for code quality — drift here means shipping untested behaviour.
+
 ### Recording gate triggers
 
 Every gate trigger gets recorded in the swarm audit entry under a `## Gate triggers` section. Even if the swarm continues, the trigger is logged. This builds the audit trail for the operator to review when reasoning about whether the swarm pattern is paying off.

package/templates/starter-kit/methodfile.json

@@ -19,6 +19,15 @@
     "externalServices": [],
     "notes": null
   },
+  "testing": {
+    "framework": "vitest",
+    "command": "npx vitest run",
+    "configPath": "vitest.config.ts",
+    "enforced": true,
+    "policy": "every-touched-source-file-must-be-covered-by-a-passing-test",
+    "appliesTo": ["typescript", "javascript", "tsx", "jsx"],
+    "comment": "Vitest is the default test runner for JS/TS implementation repos. The swarm enforces two gates before a WU can promote: (1) `npx vitest run` exits 0; (2) every source file touched by the WU is referenced by at least one .test.ts(x) or .spec.ts(x). If the project's techStack does not include JS/TS, set framework to whatever idiom the stack uses (or null to opt out — the coordinator will warn but not block)."
+  },
   "catalogue": {
     "root": "docs/build/",
     "registers": {

package/templates/testing/README.md

@@ -0,0 +1,21 @@
+# Vitest scaffolding
+
+These files are copied into a JS/TS implementation repo by the swarm coordinator (see [build-wu.md §Step 4 — Vitest pre-flight](../protocols/build-wu.md)) when:
+
+- `methodfile.json` has `testing.framework: "vitest"` AND `testing.enforced: true`, and
+- the implementation repo does not yet have vitest installed or a `vitest.config.ts` present.
+
+## Files
+
+- `vitest.config.ts` — minimal Node-environment config with sensible include/exclude globs for typical `src/`, `app/`, `routes/`, `lib/` layouts and v8 coverage wired in.
+- `example.test.ts` — single passing test, dropped at `tests/example.test.ts` so the operator can confirm the runner works end-to-end.
+
+## What the coordinator does
+
+1. Runs `npm i -D vitest @vitest/coverage-v8` in the implementation repo.
+2. Copies `vitest.config.ts` to the repo root.
+3. Copies `example.test.ts` to `tests/example.test.ts` (creates the directory if missing).
+4. Adds `"test": "vitest run"` to the implementation repo's `package.json` `scripts` block if absent.
+5. Runs `npx vitest run` once to confirm the wiring works before spawning the coder.
+
+The example test is meant to be deleted as soon as the first real WU adds real tests — its purpose is purely to prove the wiring before the swarm depends on it.

package/templates/testing/example.test.ts

@@ -0,0 +1,7 @@
+import { describe, expect, it } from 'vitest';
+
+describe('vitest wiring', () => {
+  it('runs', () => {
+    expect(1 + 1).toBe(2);
+  });
+});

package/templates/testing/vitest.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts', 'src/**/*.test.ts', 'app/**/*.test.{ts,tsx}', 'routes/**/*.test.{ts,tsx}'],
+    exclude: ['node_modules', 'dist', '.next', 'build'],
+    environment: 'node',
+    reporters: ['default'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json-summary'],
+      include: ['src/**/*.{ts,tsx}', 'app/**/*.{ts,tsx}', 'routes/**/*.{ts,tsx}', 'lib/**/*.{ts,tsx}'],
+      exclude: ['**/*.test.*', '**/*.spec.*', '**/*.d.ts'],
+    },
+  },
+});