@nurix/etna 0.19.81 → 0.19.83

package/bin/etna.js

@@ -14,12 +14,13 @@
 // Harnesses are addressed by their harness/<folder> name; several harnesses may
 // share one plugin.
 
-import { existsSync } from 'node:fs';
+import { existsSync, mkdirSync, copyFileSync, cpSync, rmSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import * as p from '@clack/prompts';
 import { materializeHarness, readJson as readJsonOrThrow } from '../lib/install/materialize.mjs';
+import { projectSkills } from '../lib/codex/skills.mjs';
 
 // WHERE A HARNESS'S FILES LAND is not decided here — `lib/install/materialize.mjs` owns that
 // mapping, because the Apollo push ships the same tree and the two must never diverge. This
@@ -151,20 +152,82 @@ async function installHarness(harnessName, harnesses) {
   );
 }
 
-// Parse argv. `--name=<harness>` / `--name <harness>` selects a harness; -h/--help shows
+// Parse argv. `--name=<harness>` / `--name <harness>` selects a harness; `--rule=<name>` and
+// `--skill=<name>` install one catalog component instead of a whole harness; -h/--help shows
 // help; any other bare token is the dropped positional form (a breaking change in 0.18.0).
 function parseArgs(args) {
   let name = null;
   let help = false;
   let positional = null;
+  const components = [];
+  const takeValue = (a, flag, i) =>
+    a.startsWith(`${flag}=`) ? [a.slice(flag.length + 1), i] : [args[i + 1] ?? '', i + 1];
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === '-h' || a === '--help') help = true;
     else if (a.startsWith('--name=')) name = a.slice('--name='.length);
     else if (a === '--name') name = args[++i] ?? '';
-    else if (!a.startsWith('-') && positional === null) positional = a;
+    else if (a === '--rule' || a.startsWith('--rule=')) {
+      const [value, next] = takeValue(a, '--rule', i);
+      i = next;
+      if (value) components.push({ kind: 'rules', name: value });
+    } else if (a === '--skill' || a.startsWith('--skill=')) {
+      const [value, next] = takeValue(a, '--skill', i);
+      i = next;
+      if (value) components.push({ kind: 'skills', name: value });
+    } else if (!a.startsWith('-') && positional === null) positional = a;
   }
-  return { name, help, positional };
+  return { name, help, positional, components };
+}
+
+// Install one catalog component into the current directory — a rule as
+// `.claude/rules/<name>.md`, a skill as `.claude/skills/<name>/`.
+//
+// Deliberately does NOT record the name in `.claude/harness.json`'s `owned` manifest. Both
+// prune paths key off that manifest, so a name that was never owned is never prune-eligible
+// and the component rides through every later harness roll untouched. Recording it would
+// invert that: the next roll would see it in the prior `owned`, miss it in the bundle, and
+// delete it. Subscription state lives in etna's roster, never in the consumer repo.
+function installComponent({ kind, name }) {
+  const catalogDir = join(dataDir, 'catalog');
+  const index = readJson(join(catalogDir, 'index.json')) || { rules: [], skills: [] };
+  const available = index[kind] || [];
+  const label = kind === 'rules' ? 'rule' : 'skill';
+
+  if (!available.includes(name)) {
+    p.log.error(`No ${label} named "${name}" in the catalog.`);
+    if (available.length) p.log.message(`Available ${kind}: ${available.join(', ')}`);
+    if (kind === 'skills') {
+      p.log.message(
+        'Only skills listed in .github/subscribers/skills.md ship in the catalog — the full\n' +
+          'shared catalog is far too large to bundle. Add a row there to make one installable.',
+      );
+    }
+    return false;
+  }
+
+  const targetDir = process.cwd();
+  if (kind === 'rules') {
+    const dest = join(targetDir, '.claude', 'rules', `${name}.md`);
+    mkdirSync(dirname(dest), { recursive: true });
+    copyFileSync(join(catalogDir, 'rules', `${name}.md`), dest);
+    p.log.success(`Installed rule \`${name}\` → .claude/rules/${name}.md`);
+  } else {
+    const dest = join(targetDir, '.claude', 'skills', name);
+    rmSync(dest, { recursive: true, force: true });
+    mkdirSync(dirname(dest), { recursive: true });
+    cpSync(join(catalogDir, 'skills', name), dest, { recursive: true });
+    p.log.success(`Installed skill \`${name}\` → .claude/skills/${name}/`);
+    // The Codex mirror rebuilds from the INSTALLED tree rather than the bundle, so a
+    // subscribed skill is projected for free — the same path a harness install takes.
+    try {
+      projectSkills({ targetDir, projectHasGit: existsSync(join(targetDir, '.git')) });
+      p.log.info(`Mirrored to .agents/skills/${name}/ for Codex.`);
+    } catch (e) {
+      p.log.warn(`Codex mirror skipped: ${e?.message || e}`);
+    }
+  }
+  return true;
 }
 
 // npx caches aggressively: a bare `npx @nurix/etna` can re-run a STALE cached copy
@@ -200,22 +263,51 @@ function selfUpdateOrReexec() {
 async function main(args) {
   const idx = loadHarnessIndex();
   const harnesses = idx.harnesses || {};
-  const { name, help, positional } = parseArgs(args);
+  const { name, help, positional, components } = parseArgs(args);
 
   if (help) {
     p.intro('@nurix/etna — Nurix harness installer');
     p.log.message(
       'Usage:\n' +
         '  npx @nurix/etna                   pick a harness from the menu\n' +
-        '  npx @nurix/etna --name=<harness>  install that harness directly',
+        '  npx @nurix/etna --name=<harness>  install that harness directly\n' +
+        '  npx @nurix/etna --rule=<name>     install one catalog rule\n' +
+        '  npx @nurix/etna --skill=<name>    install one subscribed catalog skill',
     );
     printHarnessList(harnesses);
-    p.outro('No args → interactive menu. --name=<harness> → direct install.');
+    const index = readJson(join(dataDir, 'catalog', 'index.json'));
+    if (index) {
+      p.log.message(
+        `Catalog rules:  ${(index.rules || []).join(', ') || '(none)'}\n` +
+          `Catalog skills: ${(index.skills || []).join(', ') || '(none)'}`,
+      );
+    }
+    p.outro('No args → interactive menu. --name / --rule / --skill → direct install.');
     return;
   }
 
   p.intro('@nurix/etna — Nurix harness installer');
 
+  // A component install is standalone and skips the harness path entirely: it writes one
+  // file or folder and records no ownership, so it needs no bundle, no manifest, and no
+  // prune pass. Combining it with --name would make the ordering load-bearing (the harness
+  // roll can prune a name it owns), so the flags are mutually exclusive by design.
+  if (components.length) {
+    if (name !== null) {
+      p.log.error('--name installs a whole harness; --rule/--skill install one component.');
+      p.outro('Run them as separate commands — a harness roll can prune what it owns.');
+      process.exit(1);
+    }
+    const failed = components.filter((component) => !installComponent(component));
+    p.outro(
+      failed.length
+        ? `${components.length - failed.length}/${components.length} installed — ${failed.length} not in the catalog.`
+        : `Installed ${components.length} component(s) into .claude/.`,
+    );
+    if (failed.length) process.exit(1);
+    return;
+  }
+
   // Breaking change (0.18.0): the positional form `etna <harness>` was replaced by
   // `--name=<harness>`. Fail loudly with the new syntax rather than silently misfiring.
   if (positional && name === null) {

package/data/catalog/index.json

@@ -0,0 +1,20 @@
+{
+    "rules": [
+        "changelog",
+        "cloudflare",
+        "code-eval-batcher",
+        "database",
+        "frontend",
+        "general",
+        "kb",
+        "nomenclature",
+        "pnpm",
+        "react-native",
+        "rust-desktop",
+        "temporal",
+        "testing"
+    ],
+    "skills": [
+        "nustack"
+    ]
+}

package/data/catalog/rules/changelog.md

@@ -0,0 +1,25 @@
+# Changelog
+
+Every unit of work leaves one record — `docs/history/changelog/YYYY-MM-DD-{three-words}.md` (the three words name the work, not the commit) — plus its row in `docs/history/CHANGELOG.md`, appended in the same pass so the index never trails the folder. Entry format, field rules, and the closed exemption list are the `documentation` skill's `templates/changelog-entry.md`; this rule owns when an entry is owed and how it lives. An entry is never a commit summary — it carries the refinement context only the working session holds, which no diff reconstructs.
+
+## When an entry is owed
+
+| Trigger | What to write |
+| --- | --- |
+| A plan reaches `Status: Complete` | A draft entry for that plan, linked to it — written now, while the session still holds the context |
+| The user asks for a changelog | The entry for the work in hand. No commit required |
+| A commit is made | Every non-exempt commit is covered by an entry — the `commit` skill writes or completes it (no `commit` skill in the runtime ⇒ write the entry from the `documentation` skill's `templates/changelog-entry.md` and stage it with the commit) |
+
+Route the lesson by who pays for losing it: product context — what changed and why — belongs in the entry; anything the **next session would re-pay** — a library's API drifted from what the model expects, a validator's quirk, a tooling workaround — goes to `docs/memory/main.md` as well, because a changelog is read by people tracing history and memory is read by every session before it repeats the mistake.
+
+## Lifecycle
+
+Draft (created before its commit exists) → complete (missing fields filled from the diff and the session) → frozen the moment it rides in a commit. **Immutability begins at commit, not at creation** — a draft is meant to be edited, which is what lets a completed plan record its context before anything is committed; a committed entry is history, and a correction is a new entry linking back, **never** an edit.
+
+## Granularity
+
+A commit is the smallest unit an entry may describe; above that the mapping is judgment — four commits may be four entries or one, whichever reads better as history. An entry spanning several commits rides in the **last** of them, naming the predecessors in `Commits:`. When work exceeds what a draft describes, write a second entry rather than stretching the draft — the first stays an honest account of the plan.
+
+## Migrations are a different genre
+
+**One-shot migrations are a different genre.** Work that runs **once** against a live system — a data backfill, a schema cutover, a dependency or harness upgrade rolled across repos — is a **migration runbook** at `docs/history/migrations/YYYY-MM-DD-{slug}.md` (template: the `documentation` skill's `templates/migration-runbook.md`), authored **before** execution and outcome-stamped after. A changelog entry says what changed in the repo; a runbook says what was executed against the world and how to verify or undo it. A repeatable procedure is neither — that is `docs/operations/`. When a runbook defers targets, it records **why** and the **trigger to re-evaluate them**, so the next run re-checks rather than inheriting the skip.

package/data/catalog/rules/cloudflare.md

@@ -0,0 +1,180 @@
+# Cloudflare Worker
+
+Conventions for Cloudflare Workers — `wrangler.jsonc` setup, vars and secrets, and code shape (dispatch, errors, modules, WebSockets). Schema design doctrine is the `schema-design` skill.
+
+## 1. Project & wrangler.jsonc Setup
+
+### 1.1 Wrangler version
+
+- Use Wrangler **v4**. If an editor flags valid config as invalid, check the wrangler version first.
+- **No `package.json`** (dep-free worker): use `npx wrangler@4` in every command and doc. Never create a `package.json` just to record the version.
+- **`package.json` exists**: pin wrangler to the exact version tested against (not `^4.0.0`), reinstall, and verify with `wrangler deploy --dry-run` before pushing.
+
+### 1.2 Config format
+
+- Use `wrangler.jsonc` (not `wrangler.toml`).
+- Include `"$schema": "node_modules/wrangler/config-schema.json"`.
+
+### 1.3 Comments in jsonc
+
+None by default. Keep a comment only when it captures a non-obvious **WHY** — a hidden constraint, workaround, or account-specific quirk. Never narrate what a key already says.
+
+### 1.4 Public entry points — workers.dev & preview URLs
+
+- **Don't expose on `workers.dev` by default** — it is public and guessable (`<worker>.<account>.workers.dev`). Default to `"workers_dev": false`; when a deploy is requested and no custom domain or route exists yet, warn the user that enabling it makes the Worker public and enable it only on confirmation.
+- **`preview_urls` is a second public door** (`<version>-<worker>.<account>.workers.dev`) — `workers_dev` alone is not the whole switch. Set `"preview_urls": false` with it.
+- Pair a custom domain with a `routes` entry using `custom_domain: true`. **The zone must be in the same account as the Worker** — a route pointing at a zone the account doesn't hold fails at deploy, so check the zone before writing the route.
+- **Declare both keys explicitly, in the same edit that adds the route** — never leave them to the implicit default, and never delete them as redundant once a route exists.
+
+> **Adding a route cuts over atomically — you cannot stage it.** The moment a `routes` entry lands, an absent `workers_dev` key disables `workers.dev` on that same deploy; "add the route now, turn it off once the custom domain answers" is not a sequence wrangler will execute. Where the certificate is slow to provision, that gap is downtime — confirm the outage window with the user before cutting over.
+
+Deleting a route is likewise a cutover: `workers.dev` does not return until `"workers_dev": true` is set explicitly, and a torn-down hostname `404`s rather than redirecting — callers holding the old URL get no forwarding.
+
+### 1.5 Default config
+
+Every Worker carries these keys. Deviate only where a rule below says to.
+
+```jsonc
+"workers_dev": false,
+"preview_urls": false,
+"observability": {
+    "logs": {
+        "enabled": false,
+        "invocation_logs": true
+    }
+}
+```
+
+- `workers_dev` / `preview_urls` — entry-point policy and cutover mechanics: §1.4.
+- **Bootstrap override:** a new Worker (especially cron-only) runs `logs.enabled: true` until a few real runs look clean, then flips back — with logs off, `console.log` is live-only via `npx wrangler tail` and nothing persists after a failed run.
+
+### 1.6 Project structure & dependencies
+
+- Main entry file: `index.ts`. Reusable helpers: `helper.ts`.
+- TypeScript under `strict: true` — no build step, and a minimal `tsconfig.json` ships even in dep-free Workers.
+- Don't run `npm run build` or `npm run deploy` in examples.
+- **`package.json` / `package-lock.json` are opt-in.** Create them only when code under `src/` imports an npm package at runtime; add both the moment the first real dep lands. Run wrangler, linters, and one-offs via `npx <tool>`. `node_modules/` stays in `.gitignore` either way.
+
+### 1.7 Environment & configuration
+
+- Use the deployed Cloudflare URL in docs/tests, not `localhost`.
+- Prefer SQLite-based Durable Objects over in-memory-only designs; add classes under `migrations.new_sqlite_classes`.
+
+### 1.8 Cloudflare Secrets Store
+
+Use when the user mentions it. Use the same `binding` name as the `secret_name`.
+
+```jsonc
+"secrets_store_secrets": [
+    { "binding": "CLICKUP_KEY", "store_id": "792206780c0c46e8ba8ade3f21b44eac", "secret_name": "CLICKUP_KEY" }
+]
+```
+
+Access in code: `await env.CLICKUP_KEY.get()`.
+
+### 1.9 Naming
+
+- Repo/dir: `cf-<name>` (e.g. `cf-extract-design`).
+- Worker name: `<name>` — repo name minus the `cf-` prefix.
+- R2 bucket, D1 database, and KV namespace names: equal to the worker name.
+
+### 1.10 Vars & secrets
+
+**Non-secret vars live in the `vars` block in `wrangler.jsonc`**, checked in. Never move them to the dashboard. A single-tenant application Worker declares them at the top level; a multi-tenant Worker declares per-tenant vars under each `env.<tenant>` block (§11).
+
+**Secrets never touch git.** Local dev: a gitignored `.dev.vars` (`KEY=VALUE` dotenv, auto-loaded by `wrangler dev`) with a committed `.dev.vars.example` listing the keys and placeholder values. Production: `wrangler secret put <NAME>`, a gitignored `.secrets` file pushed with `wrangler secret bulk .secrets` (or shipped with a deploy via `wrangler deploy --secrets-file .secrets`), or the Secrets Store (§1.8). Never log or echo a secret value.
+
+**No `keep_vars`** — leave it unset. It guards only plaintext vars set out-of-band in the dashboard and never touches secrets; `wrangler secret put` secrets survive every deploy regardless, so never add it to protect them. Only the multi-tenant pattern sets `keep_vars: true` (§11).
+
+**Never name a deployed-value file `.env` or `.env.<anything>`** — `wrangler dev` auto-loads a root `.env` as local dev vars, so a prod-valued `.env` silently becomes the local environment on a fresh clone or in CI. Committed `*.example` files carry keys with placeholder values only.
+
+`.gitignore`: `.dev.vars`, `.secrets`, `.secrets.*`, `.env`, `.env.*`
+
+### 1.11 Deploys
+
+**Never auto-deploy.** `wrangler deploy` (any variant — `--env`, `versions upload`) runs only when the user explicitly asks. Building, dry-running (`wrangler deploy --dry-run`), and `wrangler dev` are fine unprompted. Finish the change, then tell the user it's ready to deploy.
+
+## 2. Code & Helpers
+
+- Use `generateUuidV7()` in `helper.ts` for IDs.
+- Only `await` what's needed (e.g. `request.json()`, `do.fetch(...)`).
+
+## 3. fetch() Structure
+
+`validateRequest()` first, then `switch (path)` for dispatch. Single `try/catch` wrapping the entire handler. No if-chains, no regex in fetch.
+
+```js
+export default {
+  async fetch(request, env, ctx) {
+    try {
+      const route = validateRequest(request);
+      switch (route.path) {
+        case "monitors":
+          return await handleMonitors({ ...route, env, ctx });
+        default:
+          throw { code: 404, message: "Route not found" };
+      }
+    } catch (error) {
+      console.error("Unhandled error in fetch()", error);
+      return createErrorResponse(
+        error.message || "Internal server error",
+        error.code || 500,
+      );
+    }
+  },
+};
+```
+
+No nested `try/catch` except around WebSocket `send`/`close` (see §9).
+
+## 4. validateRequest()
+
+Lives in `helper.ts`. Parses the URL in one place and returns `{ path, method, query, resourceId, subPath }`; throws `{ code: 400 }` when a path requires a resource ID and none is present.
+
+## 5. Validation
+
+Fail fast with thrown `{ code, message }` (`400` bad input, `401` missing/invalid auth). Validate required fields explicitly — no optional chaining for required fields.
+
+## 6. Errors & Responses
+
+- Throw structured errors: `{ code, message }`. Always `console.error()` with context (path, user, etc.). No empty catch blocks.
+- Response envelope `{ status: 1|0, message, data }` — the shared cross-service contract.
+- `createResponse(data, message, code)` in `helper.ts` bakes CORS in, returns a null body for 204/304, and uses proper HTTP codes; `createErrorResponse(message, code)` delegates to it.
+- CORS is passive: a `CORS_HEADERS` const in `helper.ts`, spread into `createResponse()` — no explicit OPTIONS handler, no wrapper functions. Origin-restricted CORS builds the headers from an allowlist (plus `localhost` in dev), still inside `createResponse()`.
+
+## 7. Handler Signatures
+
+Single destructured object — never positional args. Compose by spreading route with env/ctx: `handleGetStats({ request, env, resourceId })`, not `handleGetStats(request, id, env)`.
+
+## 8. Module Structure
+
+Feature-based folders with `handle.ts` + `helper.ts` pairs. `index.ts` only does dispatch.
+
+| Path | Role |
+| --- | --- |
+| `src/index.ts` | Entry point — dispatch only |
+| `src/helper.ts` | Shared CORS, responses, validation, utilities |
+| `src/database.ts` | Shared D1 queries |
+| `src/<feature>/handle.ts` | Route handlers |
+| `src/<feature>/helper.ts` | Feature-specific helpers & DB ops |
+
+## 9. WebSockets
+
+Standard `WebSocketPair` handshake (`server.accept()`, return 101 with `webSocket: client`). Check `readyState === WebSocket.OPEN` before sending. The only acceptable nested `try/catch`: wrap `send`; in its catch, `close(1011)` inside a bare inner try, then evict the session.
+
+## 10. D1 Schema
+
+Follows the shared database naming and column-type vocabulary; what earns a table and the rest of the design doctrine is the `schema-design` skill.
+
+## 11. Multi-tenant Workers (native environments)
+
+Rare — only when **one Worker codebase ships as several independent tenants**: separate Workers, domains, and data stores from a single `src/`. Use **native wrangler environments**, never one Worker that switches tenant at runtime. For a single-tenant application Worker, §1.10 applies and this section does not.
+
+- **One config, `env.<tenant>` blocks.** The top-level block is **local dev** (`wrangler dev`): a `*-dev` name and placeholder D1/KV ids, simulated locally. Each `env.<tenant>` block is **one production tenant**; deploy it with `wrangler deploy --env <tenant>`.
+- **Named environments never inherit** `vars` / `d1_databases` / `kv_namespaces` / `routes` / `secrets_store_secrets` / `assets` from the top level — **each `env.<tenant>` declares them in full**. Dropping a binding from an env block disables that capability for that one tenant.
+- **Per-tenant non-secret vars live in `env.<tenant>.vars`**, checked in.
+- **Local-dev vars** come from a gitignored `.vars.local`, injected as `--var` by the dev script (the top-level block carries no in-config `vars`).
+- **Per-tenant secrets, never in git** — `wrangler secret put <NAME> --env <tenant>`, or a gitignored per-tenant `.secrets` (e.g. `worker/tenants/<tenant>/.secrets`) pushed with `wrangler secret bulk --env <tenant>`, plus a committed `.secrets.example`. Secrets Store bindings are declared inside each env block.
+- **`keep_vars: true`** (top level) keeps a per-tenant deploy **additive**: tenants inject their non-secret vars via `--var` (or the dashboard), and without it a deploy would wipe them. On secrets it changes nothing (§1.10).
+
+`.gitignore`: §1.10's list, with `.vars.local` in place of `.dev.vars`.

package/data/catalog/rules/code-eval-batcher.md

@@ -0,0 +1,67 @@
+# Code-Eval Batcher
+
+Evaluating and ranking **multiple code projects** — candidate take-homes, submissions, a folder of repos — against the production-readiness + product-quality rubric. The main agent performs this directly rather than delegating it: the rollup needs every scorecard in one context, so the session that ranks must be the one that fans out. A single project does **not** need this rule — invoke the `evaluator` skill directly. Scoring how a person *steered a session* is `interview-eval`, not this rule.
+
+## Division of labor
+
+Per-project scoring — the rubric, gates, absolute banding, the 8 sub-criteria, every recipe — belongs to the **`evaluator` skill** (`.claude/skills/evaluator/`); never re-derive it here. This rule owns only what the skill deliberately doesn't: **enumeration, parallel dispatch, weighting, and the cross-project rollup.** **Never re-band a project against the others** — cohort-relative banding is the anti-pattern this design removed; the only cross-project levers live in the weights block.
+
+## Procedure
+
+| # | Step |
+| --- | --- |
+| 0 | **Preflight once:** `bash .claude/skills/evaluator/preflight.sh`. Halt on non-zero and report the missing tools — never score with degraded signals. |
+| 1 | **Enumerate** the projects → local paths, one slug each (its dir name). Choose an `out_dir` (default `./code-eval-out`). |
+| 2 | **Dispatch in parallel — batches of 4.** Per project: an `Agent` call with `subagent_type="general-purpose"` instructing it to invoke the `evaluator` skill on that one path, write the workspace to `<out_dir>/<slug>/`, validate it (`python3 .claude/skills/evaluator/validate_scorecard.py <out_dir>/<slug>/scorecard.yaml`), and return the workspace path + the scorecard's `normalized`. **Issue all four calls in one block** — that is what makes them concurrent; start the next batch when the block returns. |
+| 3 | **Collect** every `<out_dir>/*/scorecard.yaml`. Re-dispatch a validation failure once; on the second failure mark the project `VALIDATION_FAILED` and continue. |
+| 4 | **Weight + normalize** every project (math below) using the weights block. |
+| 5 | **Rollup** → `<out_dir>/results/{scorecard.csv, ranking.md, summary.md}` (contents below), sorted by rank score desc. Leave everything uncommitted. |
+
+## Weighting math
+
+For each project `p`, read each sub-criterion `s`'s raw 0–5 `score` (the evaluator's absolute band) from its `scorecard.yaml`:
+
+1. **Weighted (0–100)** over sub-criteria with a non-null `score` and `weight > 0`:
+   `weighted_p = 100 × Σ_s (score_{p,s} / 5 × weight_s) / Σ_s weight_s`
+2. **Gate penalty:** `adjusted_p = max(0, weighted_p − Σ_{g ∈ gates_triggered_p} gate_penalties[g])`.
+3. **Normalize** across the set `{adjusted_p}` per `normalization`:
+   - `percent_of_max` (default) → `adjusted_p` unchanged — absolute, comparable across runs.
+   - `min_max` → `100 × (adjusted_p − min) / (max − min)`; `max == min` ⇒ all 100. Spreads a tight set; not comparable across runs.
+   - `z_score` → `clamp(0, 100, 50 + 10 × (adjusted_p − mean) / sd)`; `sd == 0` or n < 2 ⇒ fall back to `adjusted_p`.
+
+`VALIDATION_FAILED` projects are excluded from min/max/mean/sd and listed separately. A null sub-criterion drops out of that project's weighted average — never impute a 0. Compute with a short throwaway script over the scorecards; round reported scores to 2 decimals.
+
+| Output | Contents |
+| --- | --- |
+| `scorecard.csv` | `rank, project, <8 scores>, gates, short_circuited, evaluator_total, weighted, penalty, rank_score` |
+| `ranking.md` | ranked table headed with the normalization method — the sort key |
+| `summary.md` | n scored, the exact weights / penalties / normalization used, top-5 / bottom-5, gate frequency, any `VALIDATION_FAILED` |
+
+## Weights — edit this block to change the ranking
+
+The math above consumes these values verbatim. Edits here are overwritten on a harness re-install — to persist a custom weighting, drop a `code-eval-batcher.weights.json` with the same shape in the `out_dir` and read that instead.
+
+```json
+{
+  "weights": {
+    "code_quality": 12.5,
+    "testing": 12.5,
+    "deployment_readiness": 12.5,
+    "maintainability": 12.5,
+    "problem_substantiveness": 12.5,
+    "ux_mechanics": 12.5,
+    "value_articulation": 12.5,
+    "mechanical_ambition": 12.5
+  },
+  "gate_penalties": {
+    "DEMO": 0, "BROKEN": 0, "UNTESTED": 0, "TESTS_TRIVIAL": 0,
+    "SECRETS": 0, "VULN": 0, "AUTH": 0, "OBSERVABILITY": 0
+  },
+  "normalization": "percent_of_max"
+}
+```
+
+- **`weights`** — relative importance; any non-negative numbers, normalized to sum 100 over the present, weighted sub-criteria. `0` drops a sub-criterion. The all-12.5 default reproduces the evaluator's own equal-weight total.
+- **`gate_penalties`** — flat 0–100-scale points docked per triggered gate, on top of the band caps the evaluator already applied. Default 0 = rely on the evaluator's caps alone. E.g. `SECRETS: 15` docks 15 from any project with a committed secret.
+
+**No silent fallback.** A malformed weights block, a failed preflight, or a scorecard that won't validate is reported loudly — never worked around.

package/data/catalog/rules/database.md

@@ -0,0 +1,34 @@
+# Database
+
+Naming and the fixed column vocabulary for relational schemas in **every** Nurix project — one concept, one name, everywhere. Written for SQLite / Cloudflare D1 + Drizzle; a Postgres project keeps the same column names and semantics with native types (`uuid`, `timestamptz`, `boolean`). **Design doctrine — what earns a table, state vs. logs, junctions, FK policy, uniqueness traps — is the `schema-design` skill; consult it before any schema change.**
+
+## Keys & the shared vocabulary
+
+Three column roles are fixed across every table and every project:
+
+- **`id`** — the primary key, **always a UUID** (`TEXT PRIMARY KEY` on D1, `uuid` on Postgres), never a synthetic or natural key (❌ `type_page_button`, `human:default`). Runtime rows mint a UUIDv7; seed rows derive a deterministic UUIDv5 of the natural key so re-seeds stay stable. **Never** mix synthetic and UUID ids in one table. The single exemption is a log whose **composite key is its ordering** (`PRIMARY KEY (<entity>_id, sequence)`), declared at the table that uses it — everything else, logs included, takes a UUIDv7.
+- **`slug`** — the **stable key rows in another scope reference**: `UNIQUE`, lowercase `snake_case`. A slug means the same thing in every scope, so a slug reference survives a copy with no remapping — copying between scopes is the `schema-design` skill. ❌ Never rename this role `handle`, `key`, `code`, or `name` in another project.
+- **`label`** — the **human display name** — ❌ never `name`, `title`, or `display_name`.
+
+Reference columns name what they point at: `<entity>_id` for a UUID-PK reference (`user_id`, `app_id`), `<entity>_slug` for a slug reference (`source_slug`).
+
+- **Enforced, same scope** (the referenced row must exist) → a real `FOREIGN KEY (<x>_id) REFERENCES <table>(id)`.
+- **Cross-scope** (the reference must survive being copied) → `<x>_slug` as a plain column, **no** FK — an FK would bind the row to one scope's copy of the target, which is the remapping the slug exists to avoid.
+- **Drift-tolerant** (a controlled-vocabulary value that may fall off-list) → a plain value column, **no** FK, paired with an `is_*` boolean recording whether the value is in the canonical set.
+
+**Every inbound FK to a hub table declares a deliberate `ON DELETE`.** A hub (`users`, `devices`, anything several modules point at) collects edges from teams that never meet, and a single `NO ACTION` among them turns deleting the parent into a constraint error naming neither table. Decide per edge: the child dies with the row (`CASCADE`) or survives it (`SET NULL`, which needs a nullable column) — `NO ACTION` on a hub is a deferred outage, not a default.
+
+## Naming
+
+- **Tables** — `snake_case`, plural noun for what they hold (`users`, `apps`, `devices`).
+- **Junction (M:N) tables** — `<entityA>_<entityB>_map`, **always**, even when the join carries its own columns; singular stems, owning/anchor entity first (`app_user_map`, `app_device_map`). ❌ Never a "nice" noun (`members`, `installs`, `memberships`, `enrolments`) — the name must read as a join, and a reviewer should know both sides from it. The `_map` suffix is reserved for genuine M:N — the cardinality test that decides junction vs. column is the `schema-design` skill.
+- **Columns** — `snake_case`; booleans `is_*` / `has_*`; timestamps `created_at` / `updated_at`; foreign keys `<entity>_id`.
+- **Indexes** — `<table>_<col(s)>_idx`; unique `<table>_<col(s)>_unique`; a junction's composite unique reads `<table>_<colA>_<colB>_unique` (`app_user_map_app_user_unique`).
+- **Drizzle mirror** — the exported object is the camelCase table name (`app_user_map` → `appUserMap`); column props are the camelCase of the column (`created_at` → `createdAt`). The `sqliteTable("…")` string and every index name must match the DDL (`init.sql`) exactly — the schema-parity boundary.
+
+## Column types (SQLite / D1)
+
+- **Timestamps** — `created_at` + `updated_at`, both `TEXT NOT NULL DEFAULT (datetime('now'))`, on **every** table — except append-only logs, which carry only `created_at`.
+- **Booleans** — `INTEGER` (Drizzle `integer(…, { mode: "boolean" })`); the `is_*` / `has_*` names are § Naming.
+- **JSON** — `TEXT` (Drizzle `text(…, { mode: "json" })`).
+

package/data/catalog/rules/frontend.md

@@ -0,0 +1,40 @@
+# Frontend
+
+Tailwind v4 + shadcn-based UI conventions for **web** apps — styling, the `@nurix/components` library, the `design.md` token artifact, and design-skill routing — plus the TypeScript conventions every package compiles under.
+
+- **Build every UI through the `design` skill** — never hand-roll layouts; the page archetypes, the `design.md` identity system with its token artifact (`design.tokens.css`), and chrome wiring live in the skill.
+- **The brief's stated theme binds** — dark boots dark when the brief says so (recorded in the project's `design.md`); light is the default only when the brief is silent.
+- **`@nurix/components`** is the UI library — import by subpath (`@nurix/components/button`). **Never** `npx shadcn add`, no `components.json` scaffold — consume the prebuilt library (`.tsx`, not `.jsx`).
+- Vite: `@tailwindcss/vite` + `@vitejs/plugin-react-swc`. Pin `react` / `react-dom` / `react/jsx-runtime` / `react/jsx-dev-runtime` to the app's single copy via `resolve.alias` — `@nurix/*` ship nested react, and two copies means two hook dispatchers.
+- Tailwind v4 is CSS-only — no `tailwind.config.js`, no PostCSS.
+- CSS entry `globals.css`, imports in order: `@import "./fonts.css"` (`@fontsource` registrations) → the project's `design.tokens.css` (derived from the repo-base `design.md` by the design skill's validator — **never** hand-edited) → `@import "tailwindcss"` → the library's `styles.css` — then `@theme inline {…}` mapping vars to tokens.
+- Tokens: CSS vars in `:root, :root[data-theme="light"]` and `:root[data-theme="dark"]` (both specificity 0,2,0 — armor a later bare `:root` can't defeat), consumed as semantic Tailwind tokens (`bg-card`, `text-foreground`). `globals.css` carries the active `@custom-variant dark` line; the theme attribute is `data-theme`. The library bundles `class-variance-authority`, `clsx`, `tailwind-merge` — don't re-add them.
+- Spacing in 2/4/6/8; `object-cover`; `truncate`; color through tokens — **never** hardcoded hex in components.
+
+## Component Search Order
+
+**A component already exists until the search proves otherwise** — building one is the last step, never the first instinct, and a primitive the library ships is never re-implemented. Search in order: **`@nurix/components`** (its `exports` keys are the available subpaths) → **the app's own `src/components/`**, which in a monorepo is the consuming package's pool → **the route folders**, where a near-match is a misfiled generic to promote rather than duplicate.
+
+**A new component lands in `src/components/` on first use, not on second.** Waiting for reuse to promote it fails in practice: nobody notices the second use, so the promotion never happens and the component sits where the next session will not look. Findability is the point of the pool, so one consumer earns a place in it.
+
+**The exception is mechanical — a component importing from a specific route folder belongs to that route folder.** That import is what domain-coupled means, and it is decidable the moment the file is written, where consumer count cannot classify anything until a second use exists. A pool component that starts importing a route has drifted and moves down.
+
+**Pay the pollution as you go, never as scheduled cleanup:** re-read the pool before adding — something differing from an existing component by one prop is a prop, not a component — and group the pool by kind once it passes roughly fifteen flat files.
+
+## TypeScript
+
+Every package compiles under `strict: true` and `noUncheckedIndexedAccess: true`.
+
+### Type Safety
+
+- **Never** `any` to silence the checker. Unknown value → type `unknown`, then narrow (type guard / `zod` parse).
+- **Never** weaken strictness: no `// @ts-nocheck`; `// @ts-expect-error` only with a same-line reason.
+- Infer locals and return types; annotate at boundaries (exports, props, contracts).
+
+### Generics
+
+Shared libraries (`@nurix/components`, etc.) are generic on purpose — that's what types `cell(row)`, checks `slug` against `keyof TData`, and ties `data`/`columns` together; **never** widen to `any` to dodge it. State the row type **once per file** and let inference carry it — repeating `fn<Type>(…)` / `<Comp<Type>>` per call site is cosmetic (same safety, same emitted JS):
+
+- **Bind a repeated factory once** (preferred): `const col = defineColumn<Row>;` → `col({...})`.
+- **Infer JSX type args from props:** `<Table data={rows} columns={columns} />`, not `<Table<Row> …>`.
+- **Anchor with a collection annotation** when nothing else can: `const columns: ColumnDefinition<Row>[] = [...]`.

package/data/catalog/rules/general.md

@@ -0,0 +1,73 @@
+# General Standards
+
+Runtime versions, package policy, source layout, the API response envelope, and GitHub Actions pins — the workspace baseline.
+
+## Source Layout
+
+How a package's `src/` is laid out. A single-runtime package drops `server/` and `shared/`.
+
+| Folder | Intent — what it protects | Belongs here when |
+| --- | --- | --- |
+| `app/` | The frame that survives navigation — one router, one auth gate, one shell. The property is **instance count, not importance**; without it every route reinvents the chrome, and the shell becomes where "general" code hides. | Mounted once, present on every page |
+| `surfaces/` | An address maps to one deletable folder holding its page, panels, client and private `lib/`. **One folder per route outranks file count** — a one-file route keeps its folder, because the value is that the folder list *is* the route list. | A routable destination |
+| `components/` | UI shared across the app, **and the known place anyone looks before building** — the second job is the load-bearing one, because a component nobody finds gets rebuilt and the app grows three of it that disagree. | A component importing no route folder |
+| `lib/` | The client's non-visual work — API client, session state, ids, timestamps, hooks. | Non-React logic only the client uses |
+| `shared/` | The contracts and domain logic both runtimes read, so the halves cannot drift; without it the contract is stated twice and diverges on the first change nobody propagates. | Client **and** server both import it |
+| `server/` | The other runtime as a peer in the same package — what lets a contract be a file both sides import instead of a shape both sides guess. | Runs on the server runtime |
+
+**Split by role, not by feature** — a flat `src/leads/ src/accounts/…` trades one level of depth for unbounded root breadth, and the top-level scan is what keeps a repo legible. The container **bounds** rather than classifies, so `routes/` is an equally valid name for `surfaces/` — use the word the codebase already speaks.
+
+**Never `core/`** — its membership test collapses to "is it important?", making it the queue for files nobody could place; a bare `lib/` holding everything non-visual fails the same way, which is what `shared/` prevents. A route's own nested `lib/` is private and is **never** hoisted, and **dependencies point down** — a shared folder importing one route folder is a defect.
+
+**A folder earns its place at ~4+ files, or by being a boundary somebody could delete whole.** Below that, inline it: a folder around one file is a longer filename, and a folder holding only another folder is cascade with nothing at it. Density — not depth, not root breadth — is what makes a tree read as sprawling. The boundary clause splits the one-file cases: a one-file route folder stays, a one-file component folder goes.
+
+**Never judge dead code by a name grep** — a relative import never contains its own parent's path, so `grep "x/brand"` cannot see `from "./brand/Detail"`, and every folder imported only by its parent reads as dead. Test by transitive reachability from the real entry points, resolving specifiers as the bundler does (`.ts`, `.tsx`, `.css`, `/index.ts`; strip `?raw`/`?url`; map a `.js` specifier onto its `.ts` source), running the test tree as a **second, separate** entry set — reachable from tests alone means a suite pinning code nothing ships, and both go together. Ambient `.d.ts` files enter through tsconfig `include`, so a sweep always reports them dead. A retired mechanism spans more than source — grep the build config for the same concept before calling a removal complete. **Unreachable ≠ unwanted**: a routed surface rendering dummy data is reachable and still not product, and retiring it removes a route, which is a product decision.
+
+**Reshape an existing tree largest-lever-first**, verifying typecheck plus the full suite between steps: purge unreachable files → collapse single-occupancy and pass-through folders → push domain-coupled components down → name the shared layer (the only step that adds a top-level name) → optionally add a path alias, which makes depth invisible at the import site and dissolves most "flatten it" instincts. **Delete and promote before you move** — a folder whose name misdescribes its contents just relocates the lie.
+
+## Runtime Versions
+
+- **Node.js:** the version pinned in `.nvmrc` / `package.json` `engines` — never a hardcoded number anywhere.
+- **Package manager:** detect from the lockfile — **never** hardcode one.
+- **PostgreSQL:** 17 · **Redis:** 7.x (latest)
+
+## Packages
+
+**The approved table is `.claude/hooks/approved-packages.md`**, enforced by the PreToolUse install gate. It records three states, and the gate treats them differently:
+
+| The package is… | What happens |
+| --- | --- |
+| in the **Package** column | installs |
+| in a **Don't use** column | **blocked**, and the block names that row's replacement — `moment` answers "use `date-fns`" |
+| in neither | **installs.** No decision exists, so there is nothing to enforce |
+
+A rejection is a decision and binds; an absence is not one and never blocks work. Unlisted packages are harvested across the fleet by the package census, and become rows — or bans — by explicit user decision. **Never edit the table to unblock yourself**; a rejection changes only on the user's say-so.
+
+Two **dev-only** installs are exempt even from the rejection check being reached: a scoped companion of an approved package (`@testing-library/react` is on the table, so `-D @testing-library/user-event` needs no row of its own) and `@types/*`.
+
+## API Response Envelope
+
+Success and error share **one** envelope — a cross-service contract clients branch on, so a per-service "improvement" (`success: true`, a boolean `status`, a bare payload) breaks every consumer:
+
+```json
+{
+  "status": 1,
+  "message": "Message sent successfully",
+  "data": { "delivered": [{ "user@example.com": 2 }] }
+}
+```
+
+Error: `{ "status": 0, "message": "Error description", "data": null }`
+
+HTTP codes, default list: `200`, `201` (created), `400`, `401` (not authenticated), `403` (not authorized), `404`, `500` — plus `204`/`304` (null-body responses), `409` (conflicting write), `429` (rate limit), `503` (unhealthy dependency) where the semantics call for them. Middleware- and protocol-emitted codes are exempt from the envelope.
+
+## GitHub Actions
+
+Pin the major, and check it against the action's releases — a major behind still runs, so a stale pin never fails, it only warns.
+
+| Action | Version | Use |
+| --- | --- | --- |
+| `actions/checkout` | v7 | Repo checkout |
+| `actions/setup-node` | v7 | Node toolchain + npm cache |
+
+Set `node-version` via `node-version-file: .nvmrc`, **never** the runner's default.

package/data/catalog/rules/kb.md

@@ -0,0 +1,6 @@
+# Knowledge-Base Folders
+
+Conventions for any folder that is majority markdown — `docs/`, `research/`, an Obsidian vault, any knowledge base. Folder shape and linking only. **Instruction files are not a knowledge base and this rule does not reach them** — `rules/`, `agents/`, and skill bodies carry their own linking discipline and no `Readme.md`.
+
+- **Every topic folder carries a `Readme.md`**, created with the topic's first document — **never** `index.md` or an unscoped filename. `Readme.md` is what GitHub and Obsidian surface first, so every folder introduces itself.
+- **Every mention is a link** — wikilinks (`[[other-doc]]`) inside Obsidian-native vaults, relative markdown links (`[label](../other-doc.md)`) everywhere else. Unlinked mentions decay a knowledge graph into a pile of files.