@nurix/etna 0.18.4 → 0.18.5

package/data/harnesses/hr/skills/evaluator/criteria/ux-mechanics.md

@@ -0,0 +1,283 @@
+# UX Mechanics — Extraction Plan
+
+- **Sub-criterion:** 2.2 (Product Thinking)
+- **Weight:** 12.5 pts
+- **Contenders:** UX heuristic grep bundle (web) + clig.dev greps (CLI) + **enterprise API quality signals** (API-only path) + LLM read (layered, path-dependent)
+- **Source quote:** _"Clear user flows, thoughtful UX (even with minimal UI). Usability, not just features."_
+
+This recipe scores usability and user-flow quality across three surfaces (web UI / CLI / API-only). Bands are **absolute**. The **API-only path is not capped** — enterprise backends can score up to 5. API-only signal bundle: (a) OpenAPI/Swagger spec presence + completeness (all routes documented, examples present, error shapes declared), (b) route naming consistency (kebab / snake / camel singular-vs-plural coherence), (c) response envelope + error-handling consistency (uniform `{data, error}` or RFC 7807), (d) versioning strategy (`/v1/` prefix, `Accept-Version` header, or clearly no-version-needed), (e) idempotency on mutations (Idempotency-Key header support on POST/PUT/PATCH), (f) rate-limiting presence (middleware + headers), (g) input validation at boundaries (schema validation on incoming requests), (h) API documentation quality (written docs beyond autogen). Three-path detection (web / CLI / API-only) writes `raw/ux-mechanics-path-detection.json`. Gates: none owned by this recipe.
+
+---
+
+## Path detection (first step)
+
+```bash
+# Web-UI — presence of framework routes/components
+find <local-repo-path> -maxdepth 4 -type d \
+  \( -name pages -o -name app -o -name routes -o -name screens -o -name views \
+     -o -name components \) \
+  -not -path '*/node_modules/*' 2>/dev/null
+
+find <local-repo-path> -maxdepth 4 -type f \
+  \( -name '*.tsx' -o -name '*.jsx' -o -name '*.vue' -o -name '*.svelte' \) \
+  -not -path '*/node_modules/*' 2>/dev/null | head -5
+
+# CLI — executable entrypoint indicators
+grep -lE '"bin"\s*:' <local-repo-path>/package.json 2>/dev/null
+grep -lE '\[project\.scripts\]|console_scripts' \
+  <local-repo-path>/pyproject.toml <local-repo-path>/setup.cfg 2>/dev/null
+grep -rlE 'cobra\.Command|click\.(group|command)|typer\.Typer|commander|yargs' \
+  <local-repo-path>/cmd <local-repo-path>/src <local-repo-path>/main.go 2>/dev/null
+
+# Backend-only — HTTP server without UI components
+grep -rlE 'Flask|FastAPI|express\(\)|gin\.Default|fiber\.New|@nestjs/core' \
+  <local-repo-path>/src <local-repo-path>/app <local-repo-path>/internal 2>/dev/null
+```
+
+Capture: `path` ∈ `web-ui` / `cli` / `backend-only` / `mixed` (run all relevant bundles).
+
+---
+
+## Path A — Web-UI
+
+### Signal A1 — UX heuristic grep bundle
+
+Six UX signals (each +1 if present):
+
+```bash
+# Loading states
+grep -rlE 'isLoading|isFetching|<Skeleton|<Spinner|<Suspense[^>]*fallback' \
+  <local-repo-path>/src <local-repo-path>/app <local-repo-path>/pages 2>/dev/null | head -1
+
+# Error states
+grep -rlE 'isError|<ErrorBoundary|error\s*\?|<ErrorState|toast\.error|notify\.error' \
+  <local-repo-path>/src <local-repo-path>/app 2>/dev/null | head -1
+
+# Empty states
+grep -rlE 'length\s*===?\s*0|isEmpty|<EmptyState|"No results"|"Nothing here"' \
+  <local-repo-path>/src <local-repo-path>/app 2>/dev/null | head -1
+
+# Form validation
+grep -rlE 'zod|yup|react-hook-form|vee-validate|required=|pattern=' \
+  <local-repo-path>/src <local-repo-path>/app 2>/dev/null | head -1
+
+# Destructive-action feedback
+grep -rlE 'toast|<Dialog|<AlertDialog|confirm\(' \
+  <local-repo-path>/src <local-repo-path>/app 2>/dev/null | head -1
+
+# Responsive
+grep -rlE '\b(sm:|md:|lg:|xl:|@media)\b' \
+  <local-repo-path>/src <local-repo-path>/app 2>/dev/null | head -1
+```
+
+Capture: `ux_heuristics_hit` (count 0-6).
+
+### Signal A2 — Route / navigation tree
+
+```bash
+# Route tree
+tree -L 3 <local-repo-path>/{pages,app,routes,src/routes} 2>/dev/null
+
+# Route count (Next.js file-based, React Router, Vue Router)
+grep -rcE '<Route\s+path|createBrowserRouter|router\.(addRoute|push)' \
+  <local-repo-path>/src <local-repo-path>/app 2>/dev/null | awk -F: '{n+=$2} END {print n+0}'
+
+# Orphan detection — route files with no inbound <Link> / router.push
+# (LLM does this better; surface as context)
+```
+
+Capture: `route_count`, `route_tree_depth`, `has_nav_primitive` (bool).
+
+---
+
+## Path B — CLI
+
+### Signal B1 — shellcheck (shell repos)
+
+```bash
+if find <local-repo-path> -name '*.sh' -not -path '*/node_modules/*' | head -1 > /dev/null; then
+  shellcheck -f json <local-repo-path>/**/*.sh > /tmp/shellcheck.json 2>/dev/null
+fi
+```
+
+Capture: `shellcheck_findings`, `shellcheck_by_severity` (error/warning/info/style).
+
+### Signal B2 — clig.dev conformance greps
+
+````bash
+# --help wiring
+grep -rlE 'argparse|click\.(command|group|option)|typer\.Typer|commander|cobra|yargs|\.addHelp\(' \
+  <local-repo-path>/cmd <local-repo-path>/src <local-repo-path> 2>/dev/null
+
+# stderr discipline — writes to stderr for errors
+grep -rlE 'sys\.stderr|stderr\.write|console\.error|process\.stderr|log\.(Error|Fatal)|fmt\.Fprintln\(os\.Stderr' \
+  <local-repo-path>/src <local-repo-path> 2>/dev/null
+
+# Non-zero exit paths
+grep -rcE 'sys\.exit\([1-9]|process\.exit\([1-9]|os\.Exit\([1-9]|return [1-9]' \
+  <local-repo-path>/src <local-repo-path> 2>/dev/null
+
+# Common flags: --verbose / --dry-run / --yes / --quiet
+grep -rcE '"--?(verbose|quiet|dry-run|yes|version)"' \
+  <local-repo-path> 2>/dev/null
+
+# Logging library
+grep -rlE 'logging\.|logger\.|log\.|pino|winston|zerolog|zap' \
+  <local-repo-path>/src <local-repo-path> 2>/dev/null
+
+# README usage examples — fenced code blocks with command invocations
+grep -cE '^\s*\$ |^\s*```(sh|bash|console|shell)' <local-repo-path>/README.md 2>/dev/null
+````
+
+Capture 6 booleans + counts:
+
+- `cli_help_wired` (bool)
+- `cli_stderr_discipline` (bool)
+- `cli_exit_codes_used` (count)
+- `cli_common_flags_count`
+- `cli_logging_present` (bool)
+- `cli_readme_examples` (count of fenced cmd blocks)
+- `cli_clig_conformance_score` = count of the 6 booleans satisfied (0-6)
+
+---
+
+## Path C — Backend-only (API-UX surrogate)
+
+### Signal C1 — OpenAPI / docs presence
+
+```bash
+# OpenAPI / Swagger spec
+find <local-repo-path> -maxdepth 3 \
+  \( -name 'openapi.yaml' -o -name 'openapi.json' \
+     -o -name 'swagger.yaml' -o -name 'swagger.json' \
+     -o -name 'api.yaml' \) 2>/dev/null
+
+# FastAPI / NestJS / Hono / etc. auto-doc imports (implicit OpenAPI)
+grep -rlE 'from fastapi|@nestjs/swagger|from hono|\.openapi\(' \
+  <local-repo-path>/src <local-repo-path>/app 2>/dev/null
+```
+
+### Signal C2 — Structured error responses
+
+```bash
+# Error response shape — looks for consistent {error, code, message} JSON patterns
+grep -rlE '\{\s*"error"|\{\s*error:\s*|HTTPException|abort\(|c\.JSON\(\d{3}' \
+  <local-repo-path>/src <local-repo-path>/app 2>/dev/null
+
+# HTTP status code usage
+grep -rcE '\b(status|code|HTTP_)(\s*=\s*|_| = )?[1-5]\d\d\b' \
+  <local-repo-path>/src <local-repo-path>/app 2>/dev/null | head
+```
+
+### Signal C3 — README API examples
+
+````bash
+# curl / httpie invocation blocks in README
+grep -cE '^\s*(curl |http )|```(http|json)' <local-repo-path>/README.md 2>/dev/null
+````
+
+Capture:
+
+- `api_has_openapi` (bool)
+- `api_structured_errors` (bool)
+- `api_status_code_variety` (count of distinct status codes used)
+- `api_readme_examples` (count)
+- `api_surrogate_score` (0–5; integrated mechanically)
+
+---
+
+## Signal X (shared) — LLM read
+
+**Web-UI path:** read top 2 route files + main layout + 1 form component → score "thoughtful UX" **CLI path:** read main command file + 1 error-handling path → score "thoughtful CLI" **Backend-only path:** read 2 route handlers + error-response module → score "thoughtful API"
+
+Capture:
+
+- `llm_ux_score` (0–5)
+- `llm_files_sampled` (list)
+- `llm_confidence` (high/medium/low)
+- `llm_notes` (one sentence)
+
+---
+
+## Raw dumps (flat — files under `raw/` named `ux-mechanics-*`)
+
+Each signal writes its raw output to the flat `raw/` directory at the workspace root. Absent files = not extracted or path not applicable. Aggregates go to `scorecard.yaml` under `data.`.
+
+| File | Source | Shape / note |
+| --- | --- | --- |
+| `raw/ux-mechanics-path-detection.json` | Path detection | `{path: "web-ui"/"cli"/"backend-only"/"mixed", web_evidence: [...], cli_evidence: [...], backend_evidence: [...]}` |
+| `raw/ux-mechanics-ux-heuristics.json` | Signal A1 | 6-signal hit map: `{loading, error, empty, validation, confirmation, responsive}` — bool each (Path A only) |
+| `raw/ux-mechanics-routes.json` | Signal A2 | `{route_count, route_tree_depth, has_nav_primitive, route_tree_raw}` (Path A only) |
+| `raw/ux-mechanics-cli-probes.json` | Signal B2 | `{help_wired, stderr_discipline, exit_codes_used, common_flags_count, logging_present, readme_examples, clig_conformance_score}` (Path B only) |
+| `raw/ux-mechanics-shellcheck.json` | Signal B1 | Raw `shellcheck -f json` output (Path B with `.sh` files only) |
+| `raw/ux-mechanics-api-surrogate.json` | Signals C1–C3 | `{has_openapi, structured_errors, status_code_variety, readme_curl_examples, surrogate_score}` (Path C only) |
+| `raw/ux-mechanics-llm-read.md` | Signal X | LLM UX read: `{files_sampled, ux_score, confidence, one_sentence}` + short rationale |
+
+---
+
+## Aggregation → 0–5 band
+
+Scorer integrates the path-specific signals + LLM read.
+
+**Banding (absolute):**
+
+### Path A (web-UI)
+
+- **5** — ≥ 5/6 UX heuristics present, route tree clean + no orphans, LLM ≥ 4
+- **3** — 3–4 heuristics present, routes inferable but some orphans, LLM ~3
+- **1** — 0–2 heuristics, routes unclear
+
+### Path B (CLI)
+
+- **5** — full clig.dev conformance (all 6 signals), shellcheck-clean, README has invocation examples, LLM ≥ 4
+- **3** — help + errors + exit codes, missing common flags or logging, README thin
+- **1** — bare script, no `--help`, no stderr discipline
+
+### Path C (backend-only / enterprise API) — **uncapped**
+
+- **5** — OpenAPI spec complete + consistent response envelope + versioning + idempotency on mutations + rate-limiting + input validation, LLM ≥ 4
+- **3** — OpenAPI + structured errors + HTTP status consistency, but missing versioning / idempotency / rate-limiting
+- **1** — undocumented endpoints, inconsistent response shapes
+
+---
+
+## Fallback — signals missing
+
+- Mixed-path repo (has both UI and CLI) → run both bundles, report both; take the stronger as primary, cite secondary as evidence.
+- README absent → LLM confidence drops; emit `llm_confidence: low`.
+- Repo has zero UI and zero CLI and no HTTP server → score `null` with an `UNCATEGORIZED` flag in evidence and explain why no path applied.
+
+Annotate evidence with `"Path: A|B|C"` and `"Signals used: [...]"`.
+
+---
+
+## Output (what the scorer emits)
+
+```yaml
+sub_criterion: ux_mechanics
+score: 4
+path: A
+evidence: "Next.js repo. 5/6 UX heuristics hit; 12 routes, no orphans; LLM rates 4 — forms use zod + RHF and all have error states. No confirmation dialogs for delete actions."
+data:
+  path: A
+  ux_heuristics_hit: 5
+  route_count: 12
+  route_tree_depth: 3
+  has_nav_primitive: true
+  llm_ux_score: 4
+  llm_files_sampled:
+    [app/layout.tsx, app/(auth)/login/page.tsx, components/TaskForm.tsx]
+  llm_confidence: medium
+  signals_used: [ux_heuristics, route_probe, llm]
+  gates_triggered: []
+```
+
+---
+
+## Caveats
+
+- **UX heuristic grep is noisy.** Presence of `isLoading` ≠ loading UI is actually shown. LLM adjudicates when score conflicts with heuristic count.
+- **Route-orphan detection is stack-specific** — reliable in Next.js file-based routing, weaker in hand-rolled React Router.
+- **Backend-only / API-only is uncapped.** Enterprise API design (OpenAPI quality + versioning + idempotency + rate-limiting + input validation) can score up to 5 on the strength of those signals, matching an equally polished web UI.
+- **CLI assessment via clig.dev** assumes conformance signals quality — some CLIs ship deliberately minimal with well-chosen defaults; LLM should adjudicate.
+- **Accessibility deliberately out of scope.** A11y lint and the `aria/role/htmlFor` heuristic are not part of this recipe because tool coverage is uneven and a11y is out of scope for this rubric. UX heuristics, clig.dev conformance, API-UX surrogates, and the LLM read remain.

package/data/harnesses/hr/skills/evaluator/criteria/value-articulation.md

@@ -0,0 +1,76 @@
+# Value Articulation — Extraction Plan
+
+- **Sub-criterion:** 2.3 (Product Thinking)
+- **Weight:** 12.5 pts
+- **Source quote:** _"Does the README make a case for impact? Are claims quantified (time saved, cost, quality)?"_
+
+This recipe scores how well the README articulates value — whether it makes a clear case for impact with a named audience and quantified outcomes (time / cost / quality).
+
+---
+
+## Extraction recipe
+
+README-centric. The evaluator parses the README for impact claims, audience, scope coverage, and quantified outcomes.
+
+### Signal 1 — README impact read (LLM interpretive)
+
+Feed the LLM the full README (truncated to the first ~1000 lines) plus a list of shipped capabilities (extracted from the `mechanical_ambition` recipe's `shipped_*` fields in its `raw/mechanical-ambition-llm-read.md`, if that recipe has already run for this project):
+
+```bash
+head -1000 "$REPO/README.md" > /tmp/val-art-readme.md
+```
+
+Write the LLM read to `raw/value-articulation-llm-read.md`. The LLM emits:
+
+```yaml
+scope_breadth: N                              # number of distinct capabilities the README claims
+integration_depth: "shallow" | "medium" | "deep"   # does it integrate with internal systems, external APIs, just local data?
+completeness_ratio: 0.0-1.0                   # 1 − (stubs/handlers ratio) from mechanical_ambition, or inferred 1.0 if no stubs
+time_saved_claim_in_readme: null | "<verbatim quote>"   # e.g. "saves 3 hours per incident triage"
+audience_inferred: "internal engineers" | "support agents" | "end customers" | "unclear"
+value_articulation_score: 0-5                 # 5 = crisp audience + quantified impact + scope matches claim; 0 = no value claim
+one_sentence: "<LLM's one-line verdict>"
+```
+
+### Signal 2 — Proxies JSON
+
+Aggregate into `raw/value-articulation-proxies.json`:
+
+```json
+{
+  "scope_breadth": N,
+  "integration_depth": "shallow|medium|deep",
+  "completeness_ratio": 0.0-1.0,
+  "time_saved_claim_in_readme": null|"...",
+  "audience_inferred": "..."
+}
+```
+
+---
+
+## Banding (absolute)
+
+| Band | Criteria |
+| --- | --- |
+| **5** | Crisp value story: named audience + quantified impact (time / cost / quality numbers) + scope matches the claim (completeness_ratio ≥ 0.85). `value_articulation_score: 5`. |
+| **4** | Strong value story with one gap (quantified OR audience-specific, not both; or scope slightly short of claim). `value_articulation_score: 4`, `completeness_ratio ≥ 0.7`. |
+| **3** | Value articulated but fuzzy: claim present but unquantified, OR audience generic. `value_articulation_score: 3`. |
+| **2** | README mentions value in passing but no coherent story. `value_articulation_score: 2`. |
+| **1** | No value claim, or README is an unmodified starter/template README. `value_articulation_score ≤ 1`. |
+| **0** | Empty README. |
+
+**Over-promise penalty:** if `completeness_ratio < 0.5` AND the README claims shipped functionality (not "WIP"), cap the band at **2** — the README is writing checks the code doesn't cash.
+
+---
+
+## Raw dumps
+
+- `raw/value-articulation-llm-read.md` — LLM's full README-impact read with axis scores + verbatim quantified-claim quotes.
+- `raw/value-articulation-proxies.json` — aggregated JSON (also embedded in `scorecard.yaml.value_articulation.data`).
+
+---
+
+## Not in scope
+
+- Judging whether the claimed impact is realistic needs real operational/runtime data — out of scope; this recipe scores how well the README *articulates* value, not whether the claimed magnitude holds up.
+- Measuring actual runtime behavior against claims — that's a separate runtime-verification pass, out of scope here.

package/data/harnesses/hr/skills/evaluator/preflight.md

@@ -0,0 +1,74 @@
+# Evaluator — Preflight
+
+> **Run before scoring a project.** This skill depends on external tools that must exist on the host. If a tool is missing, **install it** — do not silently fall back to grep / LLM-only. A silent fallback poisons the gate checks (VULN / SECRETS / AUTH / OBSERVABILITY) and makes the scorecard dishonest.
+
+The evaluator is allowed to install its own tools via `brew` / `pipx` / `npm -g`. Installing is cheap (~1 minute total) and idempotent. Ignoring a missing tool is not.
+
+---
+
+## Required tools
+
+| Tool | Purpose | Recipes that use it | Install (macOS, primary) |
+| --- | --- | --- | --- |
+| `gh` | GitHub API (CR scrape, GHA runs, PR enumeration) | 1.1, 1.2, 2.4 | `brew install gh` |
+| `jq` | JSON parsing in shell pipelines | all | `brew install jq` |
+| `gitleaks` | committed-secret scan — fires `SECRETS` gate | 1.4 | `brew install gitleaks` |
+| `lizard` | polyglot complexity / god-function detection (per-language CCN: Py 10 / JS-TS 10 / Java 12 / Go 15) | 1.1, 1.4 | `brew install lizard` |
+| `scc` | LoC + cocomo estimate (replaces tokei/cloc) | 1.4, 2.4a | `brew install scc` |
+| `semgrep` | polyglot static analysis (quality + resilience + multi-protocol auth) | 1.1, 1.2, 2.4a | `brew install semgrep` |
+| `hadolint` | Dockerfile lint | 1.3 | `brew install hadolint` |
+| `ruff` | Python lint + formatter | 1.1 (Python repos), 2.4a (tier-A) | `brew install ruff` |
+| `shellcheck` | shell-script lint | 2.2a (CLI path) | `brew install shellcheck` |
+| `tree` | folder-tree read for LLM context | 1.4, 2.2a, 2.4a | `brew install tree` |
+| `golangci-lint` | Go aggregate linter | 1.1 (Go repos) | `brew install golangci-lint` |
+| `biome` | TS/JS lint + format (preferred over eslint for speed) | 1.1 (TS/JS repos) | `npm i -g @biomejs/biome` |
+| `knip` | TS/JS dead-code + unused-deps | 1.4 | `npm i -g knip` |
+| `pipx` | isolated install for Python CLIs below | — | `brew install pipx && pipx ensurepath` |
+| `deptry` | Python unused-deps | 1.4 | `pipx install deptry` |
+| `pip-audit` | Python dep-vuln scan — feeds `VULN` gate | 1.4 (Python repos) | `pipx install pip-audit` |
+| `govulncheck` | Go dep-vuln scan — feeds `VULN` gate | 1.4 (Go repos) | `go install golang.org/x/vuln/cmd/govulncheck@latest` (conditional — skipped if go not on PATH) |
+| `trivy` | Container + JS dep-vuln scan — feeds `VULN` gate | 1.4 | `brew install trivy` |
+
+Host prerequisites that must already exist:
+
+- `brew` (macOS) or `apt` (Linux)
+- `node` + `npm` (≥ 18)
+- `python3` (≥ 3.10) — `pipx` layers on top
+
+---
+
+## Invocation
+
+Run once per host: `bash .claude/skills/evaluator/preflight.sh`. Idempotent — re-running no-ops when every tool is already present. Canonical install commands live in `preflight.sh` (the executable contract); edit there, not here. Host prerequisites (`brew`, `node`/`npm`, `python3`) must already exist — the script halts loud if any are missing.
+
+---
+
+## Required behaviour for scoring agents
+
+1. **Run preflight first.** Before extracting any signal, execute the preflight script.
+2. **If preflight exits non-zero, STOP.** Do not proceed to scoring with missing tools. Return a clear failure message to the caller naming which tools failed to install.
+3. **No silent fallback.** A signal that requires a tool must either run the tool or emit `{signal}_NOT_RUN: true` with `reason: "preflight failed"` in the matching sub-criterion's `data` block in `scorecard.yaml`. This is a loud failure mode, not a graceful one.
+4. **Re-running preflight is free.** Every invocation should run it — the first run installs; subsequent runs no-op.
+
+---
+
+## When a tool does not apply
+
+Some tools apply only when a repo contains the target language (e.g. `ruff` on Python, `golangci-lint` on Go, `knip` on TS/JS). In that case:
+
+- The tool is **not** required to be installed for repos where the language is absent.
+- The signal is emitted as `{signal}: null, reason: "language_not_present"` — NOT as `_NOT_RUN`.
+- Preflight still installs all tools idempotently; language filtering happens at the recipe level, not preflight.
+
+This separates "tool missing from host" (a failure) from "tool not applicable here" (expected).
+
+---
+
+## Rationale
+
+Silent fallback to grep / LLM equivalents corrupts the scorecard in two ways:
+
+1. **Wrong bands.** The absolute banding tables in each recipe are calibrated against real tool output (e.g. `lizard` CCN, `semgrep` finding density). A grep-estimated substitute lands the project in the wrong band.
+2. **Under-reporting bias.** `gitleaks` catches entropic tokens `grep` cannot; `pip-audit` / `trivy` catch CVEs no heuristic will. Missing them turns a SECRETS- or VULN-gate hit into silence — a dishonest pass.
+
+Installing tools is cheap and one-time. Skipping them silently produces a scorecard that looks complete but isn't.

package/data/harnesses/hr/skills/evaluator/preflight.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# Evaluator preflight — install required tools or fail.
+# Canonical source. Rationale + tool table live in preflight.md (the prose
+# contract); this script is the executable contract. Edit this file, not the .md.
+# Idempotent. Re-runnable. No-op when everything is installed.
+set -euo pipefail
+
+missing=()
+
+# Portable timeout wrapper. macOS has no `timeout` by default; `gtimeout` lives
+# in coreutils. If neither is present we run without a cap but warn — the User
+# should `brew install coreutils` to restore the 180s guard.
+if command -v timeout >/dev/null 2>&1; then
+  _timeout() { timeout "$@"; }
+elif command -v gtimeout >/dev/null 2>&1; then
+  _timeout() { gtimeout "$@"; }
+else
+  echo "[preflight] warning: no timeout/gtimeout on host — install coreutils for hang-safe installs (brew install coreutils)" >&2
+  _timeout() { shift; "$@"; }   # drop the seconds arg, exec the rest
+fi
+
+need() {
+  local tool="$1"
+  local install_cmd="$2"
+  if ! command -v "$tool" >/dev/null 2>&1; then
+    echo "[preflight] missing: $tool — installing with: $install_cmd" >&2
+    # 180s covers slow brew/npm fetches; a stuck package manager fails loud
+    # instead of hanging the run indefinitely (falls back to no-cap
+    # when timeout/gtimeout is unavailable — see wrapper above).
+    _timeout 180 bash -c "$install_cmd" || { echo "[preflight] INSTALL FAILED (or timed out): $tool" >&2; missing+=("$tool"); }
+  else
+    echo "[preflight] ok: $tool"
+  fi
+}
+
+# Host prerequisites — do not attempt to install; fail if missing.
+for bin in brew jq node npm python3; do
+  command -v "$bin" >/dev/null 2>&1 || { echo "[preflight] HOST MISSING: $bin — user must install" >&2; exit 2; }
+done
+
+# Homebrew-installable tools
+# NOTE: `lizard` is intentionally NOT brew-installed — brew's `lizard` is the
+# LZ5 data-compression CLI, which shadows the Python CCN analyzer of the same
+# name when on PATH first. We install the Python tool via pipx below and then
+# sanity-check that the `lizard` resolved on PATH is the analyzer, not the
+# compressor. If a user has `brew install lizard` already they'll need to
+# either `brew uninstall lizard` or reorder PATH so `~/.local/bin` is earlier.
+need gh             "brew install gh"
+need gitleaks       "brew install gitleaks"
+need scc            "brew install scc"
+need semgrep        "brew install semgrep"
+need hadolint       "brew install hadolint"
+need ruff           "brew install ruff"
+need shellcheck     "brew install shellcheck"
+need tree           "brew install tree"
+need golangci-lint  "brew install golangci-lint"
+need pnpm           "brew install pnpm"
+need yarn           "brew install yarn"
+need pipx           "brew install pipx && pipx ensurepath"
+need trivy          "brew install trivy"
+
+# npm-global tools
+need biome          "npm install -g @biomejs/biome"
+need knip           "npm install -g knip"
+
+# pipx-installed Python CLIs
+need deptry         "pipx install deptry"
+need lizard         "pipx install lizard"
+need pip-audit      "pipx install pip-audit"
+
+# Go-installed CLIs — only install govulncheck when go is already on PATH.
+# Hosts without Go skip this gracefully; Go-repo vuln scans then
+# surface as `_NOT_RUN: true` with reason "govulncheck unavailable (go not installed)".
+if command -v go >/dev/null 2>&1; then
+  need govulncheck  "go install golang.org/x/vuln/cmd/govulncheck@latest"
+else
+  echo "[preflight] skip: govulncheck (go not on PATH — install go manually + rerun preflight if you need Go dep-vuln scans)"
+fi
+
+# Sanity-check: the `lizard` on PATH must be the Python cyclomatic-complexity
+# analyzer, not brew's LZ5 compressor. The Python tool's --help output always
+# contains "Cyclomatic Complexity Analyzer"; the compressor prints a short
+# LZ5-compression usage blurb. Halt loudly on mismatch.
+if command -v lizard >/dev/null 2>&1; then
+  if ! lizard --help 2>&1 | grep -qi 'Cyclomatic Complexity Analyzer'; then
+    echo "[preflight] FAILED — 'lizard' on PATH is not the Python CCN analyzer." >&2
+    echo "[preflight]   Resolved: $(command -v lizard)" >&2
+    echo "[preflight]   Likely cause: brew's LZ5 compressor is shadowing pipx's lizard." >&2
+    echo "[preflight]   Fix: 'brew uninstall lizard' OR move \"\$HOME/.local/bin\" earlier in PATH than \$(brew --prefix)/bin." >&2
+    missing+=("lizard (wrong binary — see above)")
+  fi
+fi
+
+if [ "${#missing[@]}" -gt 0 ]; then
+  echo "[preflight] FAILED — these tools could not be installed: ${missing[*]}" >&2
+  echo "[preflight] scoring cannot proceed; fix manually and re-run" >&2
+  exit 1
+fi
+
+echo "[preflight] all tools ready"

package/data/harnesses/hr/skills/evaluator/validate_scorecard.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Validate a single scorecard.yaml against the evaluator schema.
+
+Usage: python3 validate_scorecard.py <path-to-scorecard.yaml>
+Exit:  0 on valid; 1 on first failure with a specific error on stderr.
+
+Run after emitting a scorecard. Catches malformed scorecards before a reader
+(or a downstream caller) trips over a missing field with no attribution.
+
+Schema: 8 sub-criterion blocks (4 Code + 4 Product). Totals: total / available
+/ normalized. Every sub-criterion carries score + evidence + data.
+"""
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:
+    print("[validate] FAIL: PyYAML not installed (pip install pyyaml)", file=sys.stderr)
+    sys.exit(1)
+
+REQUIRED_TOP = {
+    "project", "commit_sha_pinned", "rubric_version", "scored_at",
+    "agent_model",
+    "gates_triggered", "short_circuited",
+    "scored_sub_criteria", "total_sub_criteria",
+    "total", "available", "normalized",
+}
+
+# 1.x Production-Grade Code — 12.5 pts each
+CODE_SUBS = {
+    "code_quality",
+    "testing",
+    "deployment_readiness",
+    "maintainability",
+}
+
+# 2.x Product Thinking — 12.5 pts each
+PRODUCT_SUBS = {
+    "problem_substantiveness",   # 2.1
+    "ux_mechanics",              # 2.2
+    "value_articulation",        # 2.3
+    "mechanical_ambition",       # 2.4
+}
+
+SUB_CRITERIA = CODE_SUBS | PRODUCT_SUBS
+
+
+def fail(msg: str) -> None:
+    print(f"[validate] FAIL: {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+def main(path: str) -> None:
+    p = Path(path)
+    if not p.exists():
+        fail(f"file not found: {path}")
+
+    try:
+        doc = yaml.safe_load(p.read_text())
+    except yaml.YAMLError as e:
+        fail(f"YAML parse error in {path}: {e}")
+
+    if not isinstance(doc, dict):
+        fail(f"top-level of {path} is not a mapping")
+
+    missing_top = REQUIRED_TOP - doc.keys()
+    if missing_top:
+        fail(f"missing top-level keys: {sorted(missing_top)}")
+
+    missing_sub = SUB_CRITERIA - doc.keys()
+    if missing_sub:
+        fail(f"missing sub-criterion blocks: {sorted(missing_sub)}")
+
+    for sub in SUB_CRITERIA:
+        block = doc[sub]
+        if not isinstance(block, dict):
+            fail(f"{sub}: not a mapping")
+        if "score" not in block:
+            fail(f"{sub}: missing `score`")
+        if "evidence" not in block:
+            fail(f"{sub}: missing `evidence`")
+        if "data" not in block:
+            fail(f"{sub}: missing `data` block")
+
+    # total_sub_criteria must be 8 under this schema.
+    if doc.get("total_sub_criteria") != 8:
+        fail(f"total_sub_criteria must be 8 (got {doc.get('total_sub_criteria')!r})")
+
+    print(f"[validate] OK: {path}")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python3 validate_scorecard.py <path-to-scorecard.yaml>", file=sys.stderr)
+        sys.exit(2)
+    main(sys.argv[1])

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/etna",
-    "version": "0.18.4",
+    "version": "0.18.5",
     "description": "Bootstrap a project with a Nurix harness — copies the harness's CLAUDE.md, skills, agents, rules, and hooks directly into the project from a bundled payload (no marketplace fetch, no network).",
     "type": "module",
     "bin": {