@nurix/etna 0.20.36 → 0.20.38

package/data/harnesses/hr/skills/evaluator/criteria/deployment-readiness.md

@@ -1,13 +1,13 @@
 # Deployment-Readiness — Extraction Plan
 
-- **Sub-criterion:** 1.3 (AI-only)
-- **Weight:** 12.5 pts (4 Code AI × 12.5 = 50 pts half)
+- **Sub-criterion:** 1.3 (Production-Grade Code)
+- **Weight:** 12.5 pts
 - **Contenders:** Filesystem probes + Hadolint + **observability markers** (structured-logging library presence, metrics/tracing library presence, `/health` endpoint detection) + LLM README/Dockerfile read (layered)
 - **Source quote:** _"Can this actually ship? Docker, config, health checks, or clear instructions to run it outside localhost."_
 
-Bands are **absolute** — per-signal thresholds in the _Banding_ section. Gates this recipe owns: **`DEMO`** (`deployment_readiness ≤ 1` when all 4 run-section/deploy signals are false OR README claims a deploy artifact that doesn't exist in the tree) and **`OBSERVABILITY`** (caps `deployment_readiness ≤ 3` when structured-logging library is absent AND metrics/tracing library is absent). Structured-logging detection: presence of `structlog` / `winston` / `pino` / `log-slog` / `zap` in deps OR JSON log format detected in code. Metrics/tracing detection: OpenTelemetry SDK / Prometheus client / Datadog agent / statsd client / a custom `/metrics` endpoint. Gate fires only when **both** categories are absent — a repo with structured logging but no metrics still ships above 3. Raw dump: `raw/deployment-readiness-observability-markers.json` with fields `{logging_lib: "<name>"|null, metrics_lib: "<name>"|null, has_health_endpoint: bool, json_log_detected: bool}`.
+Bands are **absolute** — per-signal thresholds in _Aggregation_. This recipe owns two gates, each in its own section below: `DEMO` and `OBSERVABILITY`.
 
-> Five signals, integrated by the scorer. Serverless-native repos (no Dockerfile) can reach band 5 via PaaS/managed-platform path — see bands. No weighted-math internal split — the LLM emits a single 0–5 band and cites the most load-bearing signal.
+Signals 1–5 feed the band and Signal 6 feeds the `OBSERVABILITY` gate. There is no weighted internal split — the LLM emits a single 0–5 band and cites the most load-bearing signal. Serverless-native repos with no Dockerfile reach band 5 through Path B.
 
 ---
 
@@ -71,7 +71,7 @@ Capture: `has_env_example`, `env_in_gitignore`, `tracked_env_files` (list; shoul
 ls <repo>/.github/workflows/ 2>/dev/null \
   | grep -iE 'deploy|release|publish|ship'
 
-# PaaS configs — broad 2026 landscape
+# PaaS configs
 ls <repo>/{\
 vercel.json,netlify.toml,\
 fly.toml,\
@@ -105,7 +105,7 @@ find <repo> -maxdepth 3 -name 'kustomization.yaml' 2>/dev/null
 Capture:
 
 - `deploy_workflow_files` (list)
-- `paas_configs` (list of present files; extend the list as new deploy targets appear)
+- `paas_configs` (list of present files)
 - `iac_dirs` (list of present dirs)
 - `has_any_deploy_artifact` = bool (OR across above + Signal 1 containerization)
 
@@ -171,7 +171,7 @@ Capture:
 
 ### Signal 6 — Observability markers (OBSERVABILITY gate trigger)
 
-Ships-to-prod requires signal — structured logs and metrics/traces. This signal looks for evidence that either is wired into the app. **Both** must be absent for the gate to fire; one present means the repo has the basics.
+Look for evidence that structured logs or metrics/traces are wired into the app.
 
 ```bash
 # Structured-logging library — check deps (manifest) + imports (code) + JSON-log
@@ -202,8 +202,8 @@ grep -rnE "import.*\b($LOG_LIBS)\b|from\s+($LOG_LIBS)" \
   2>/dev/null | head -20
 
 # JSON log-format heuristic — bare `json.dumps(...)` inside what looks like a
-# log call. Weak signal; participates only as a fallback. Evaluator should
-# confirm with LLM when this is the only logging-arm match.
+# log call. Weak, fallback only: confirm with the LLM read when this is the
+# only logging-arm match.
 grep -rnE '(logger|log)\.(info|warn|error|debug)\([^)]*json\.(dumps|stringify)' \
   <repo>/src <repo>/app \
   --include='*.py' --include='*.ts' --include='*.js' --include='*.go' \
@@ -238,7 +238,7 @@ grep -rnE '["/]metrics["/\s(]' <repo>/src <repo>/app \
   --exclude-dir=node_modules 2>/dev/null | head -10
 ```
 
-Assemble observability markers JSON (the sub-agent writes the interpreted fields, not the raw grep):
+Write the observability markers JSON with the interpreted fields, not the raw grep:
 
 ```json
 {
@@ -257,17 +257,17 @@ Capture:
 - `logging_lib` — name of the structured-logging library, or `null` if none found
 - `metrics_lib` — name of the metrics/tracing library, or `null` if none found
 - `has_metrics_endpoint` — bool (custom `/metrics` route found)
-- `has_json_log_format` — bool (heuristic match; low-confidence tiebreaker only)
+- `has_json_log_format` — bool (`json_log_detected` in the markers file; heuristic match, low-confidence tiebreaker only)
 - `observability_logging_present` = `(logging_lib != null) OR has_json_log_format`
 - `observability_metrics_present` = `(metrics_lib != null) OR has_metrics_endpoint`
 
-**OBSERVABILITY gate trigger:** `observability_logging_present == false` AND `observability_metrics_present == false`. Both must be absent for the gate to fire — one present is enough to avoid the cap. Caps `deployment_readiness ≤ 3`.
+These feed the [OBSERVABILITY gate](#observability-gate--both-arms-absent).
 
 ---
 
 ## Raw dumps (flat — files under `raw/` named `deployment-readiness-*`)
 
-Each signal writes its raw output to the flat `raw/` directory at the workspace root. Absent files = not extracted / not applicable. Aggregates go to `scorecard.yaml` under `data.`.
+Each signal writes its raw output to the flat `raw/` directory; an absent file means not extracted or not applicable. Aggregates go to `scorecard.yaml` under `data.`.
 
 | File | Source signal | Shape / note |
 | --- | --- | --- |
@@ -281,7 +281,7 @@ Each signal writes its raw output to the flat `raw/` directory at the workspace
 
 ## Aggregation → 0–5 band
 
-Scorer integrates the 5 signals. Rough directionality:
+Integrate Signals 1–5. Rough directionality:
 
 | Signal | Pulls score UP | Pulls score DOWN |
 | --- | --- | --- |
@@ -305,42 +305,32 @@ Scorer integrates the 5 signals. Rough directionality:
 | **1** | DEMO gate fires (see below); localhost-only repo |
 | **0** | Suppressed (DEMO gate caps at 1) |
 
-Serverless-native repos (Vercel/Fly/Cloudflare/Modal) reach band 5 via Path B — do not penalize absent Dockerfile if a PaaS config carries the deploy artifact.
+Serverless-native repos (Vercel/Fly/Cloudflare/Modal) reach band 5 via Path B — **never** penalize an absent Dockerfile when a PaaS config carries the deploy artifact.
 
 ---
 
 ## DEMO gate — two-signal agreement
 
-Gate fires only when **all three** are absent AND the LLM + mechanical README read agree:
+The gate fires on either trigger:
 
-```
-has_container_artifact == false
-AND has_any_deploy_artifact == false   (i.e. no GHA deploy, no PaaS config, no IaC)
-AND readme_has_run_section == false    (mechanical heading grep)
-AND llm_has_run_section == false        (LLM read)
-```
+1. **No ship path, by agreement** — every one of these is false, so the mechanical README read and the LLM read agree:
+   - `has_container_artifact`
+   - `has_any_deploy_artifact` (no GHA deploy, no PaaS config, no IaC)
+   - `readme_has_run_section` (mechanical heading grep)
+   - `llm_has_run_section` (LLM read)
+2. **Phantom artifact** — the README claims a deploy artifact (Dockerfile / compose / k8s / target) that does not exist in the tree.
 
-**Why two-signal:** a single LLM judgment as a hard gate means one noisy call caps the score. Requiring heading grep + LLM agreement makes the gate robust to LLM noise. If `llm_confidence == low`, defer to mechanical-only (skip the LLM side of the AND).
+Requiring the grep and the LLM to agree keeps one noisy LLM call from capping the score. If `llm_confidence == low`, drop the LLM term and decide on the mechanical terms alone.
 
-When fired, emit `gates_triggered: [DEMO]` and cap `deployment_readiness ≤ 1`.
+When fired, add `DEMO` to `gates_triggered` and cap `deployment_readiness ≤ 1`.
 
 ---
 
 ## OBSERVABILITY gate — both arms absent
 
-Gate fires only when **both** observability arms are absent:
-
-```
-observability_logging_present == false
-  AND
-observability_metrics_present == false
-```
-
-That is: the repo ships neither a structured-logging library (structlog / winston / pino / log-slog / zap / a detected JSON-log format) **nor** a metrics/tracing library (OpenTelemetry / Prometheus client / Datadog / statsd / a custom `/metrics` endpoint).
-
-**Why both-arms:** enterprise observability is "logs AND metrics", but a single-binary CLI or a thin FaaS handler may legitimately ship with just structured logs and skip metrics (or vice versa). Demanding both is punitive on small, valid shapes. The gate catches the repo that's shipping without _any_ production-grade signal — `print()`-only logging and no metrics — which is the failure we care about.
+The gate fires only when `observability_logging_present == false` **and** `observability_metrics_present == false` — the repo ships neither a structured-logging library (structlog / loguru / winston / pino / log-slog / zap, or a detected JSON-log format) **nor** a metrics/tracing library (OpenTelemetry / Prometheus client / Datadog / statsd, or a custom `/metrics` endpoint). **Never** fire it on one missing arm: a single-binary CLI or a thin FaaS handler legitimately ships structured logs without metrics, or the reverse; the gate targets `print()`-only logging with no metrics at all.
 
-When fired, emit `gates_triggered: [OBSERVABILITY]` and cap `deployment_readiness ≤ 3`. Absent arm names ship in the evidence string: `"no structured logger AND no metrics/tracing — cap at 3"`.
+When fired, add `OBSERVABILITY` to `gates_triggered`, cap `deployment_readiness ≤ 3`, and name the absent arms in evidence: `"no structured logger AND no metrics/tracing — cap at 3"`.
 
 ---
 
@@ -351,7 +341,7 @@ When fired, emit `gates_triggered: [OBSERVABILITY]` and cap `deployment_readines
 - Fully serverless (Vercel/Fly only, no Dockerfile) → Path B; PaaS config in Signal 3 carries deploy artifact weight.
 - LLM low-confidence → DEMO gate falls back to mechanical-only (README heading grep + artifact absence).
 
-Annotate evidence with `"Signals used: [...]"` and `"Path: A | B"` so the audit trail is explicit.
+Annotate evidence with `"Signals used: [...]"` and `"Path: A | B"`.
 
 ---
 
@@ -406,9 +396,9 @@ data:
 
 ## Caveats
 
-- File presence ≠ working artifact. Only runtime verification (a separate manual pass) catches broken Dockerfiles / deploy workflows.
-- Hadolint catches form, not intent. A "clean" Dockerfile that installs nothing still lints green.
-- PaaS probe list needs periodic update — new deploy targets appear faster than the list evolves.
-- LLM sample is 1 README. Repos with multi-file docs (`docs/`, `CONTRIBUTING.md`, wiki) may be under-scored on the interpretive signal. Consider glob-and-concat for docs-heavy repos.
-- Localhost grep is a noisy counter-signal even with env-var exclusion — LLM notes should adjudicate when the count is > 0 but reasonable.
-- Two-signal DEMO gate may still false-negative on repos whose README has a heading like `## Getting Started` that only says `npm run dev` (LLM catches this; mechanical does not). That's why LLM is in the AND, not replaced.
+- File presence ≠ working artifact. Only runtime verification (a separate manual pass) catches broken Dockerfiles or deploy workflows.
+- Hadolint catches form, not intent — a Dockerfile that installs nothing still lints green.
+- The PaaS probe list is non-exhaustive; extend it when a new deploy target appears.
+- The LLM reads one README, so repos with multi-file docs (`docs/`, `CONTRIBUTING.md`, wiki) may be under-scored. Prefer globbing and concatenating the docs for docs-heavy repos.
+- The localhost grep is noisy even with env-var exclusion — the LLM notes adjudicate when the count is > 0 but reasonable.
+- The DEMO gate can still false-negative on a README whose `## Getting Started` heading only says `npm run dev`: the grep passes it and only the LLM term catches it, which is why the LLM stays in the AND rather than replacing the grep.

package/data/harnesses/hr/skills/evaluator/criteria/maintainability.md

@@ -1,11 +1,11 @@
 # Maintainability — Extraction Plan
 
-- **Sub-criterion:** 1.4 (AI-only)
-- **Weight:** 12.5 pts (4 Code AI × 12.5 = 50 pts half)
+- **Sub-criterion:** 1.4 (Production-Grade Code)
+- **Weight:** 12.5 pts
 - **Contenders:** gitleaks + lizard (**per-language CCN**: Py 10 / JS-TS 10 / Java 12 / Go 15) + knip/deptry + **dep-vuln scan** (`pip-audit` / `npm audit --json` / `govulncheck` / Trivy) + LLM folder/README read (layered)
 - **Source quote:** _"Folder structure and clarity that makes it easy for another engineer to pick up and extend."_
 
-Bands are **absolute** — per-signal thresholds in the _Banding_ section. Gates this recipe owns: **`SECRETS`** (trigger: `gitleaks_findings ≥ 1`, caps `maintainability ≤ 2`) and **`VULN`** (fires when dep-vuln scan reports ≥ 1 CVE at CRITICAL OR ≥ 3 at HIGH across any dep, direct or transitive; caps `maintainability ≤ 2`). Dep-vuln tool selection by ecosystem: Python → `pip-audit`, JS/TS → `npm audit --json` (reads package-lock.json), Go → `govulncheck`, built container → `trivy image`. Skipped if no recognized package manifest. Data fields: `dep_vuln_critical` (int), `dep_vuln_high` (int), `dep_vuln_tool` (string), `dep_vuln_by_ecosystem` (map). Raw dumps: `raw/maintainability-dep-vuln-pip-audit.json` / `raw/maintainability-dep-vuln-npm-audit.json` / `raw/maintainability-dep-vuln-govulncheck.json` / `raw/maintainability-dep-vuln-trivy.json` (one file per tool that ran). lizard `--ccn` threshold uses a per-language lookup (see Signal 2 below).
+Bands are **absolute** — per-signal thresholds in _Aggregation_. This recipe owns two gates — `SECRETS` and `VULN` — defined in § Gates.
 
 ---
 
@@ -35,14 +35,13 @@ Capture:
 ### Signal 2 — Polyglot complexity (lizard, per-language CCN)
 
 ```bash
-# 16+ langs. lizard auto-detects languages from file extensions — do NOT pass
-# `--languages`; it was removed in lizard 1.21+ and the wrapper errors with
-# `unrecognized arguments` (or, depending on the version, silently no-ops).
+# lizard auto-detects 16+ languages from file extensions. Never pass
+# `--languages` — lizard rejects it as `unrecognized arguments` or silently no-ops.
 lizard -o /tmp/lizard.csv <repo> \
   -x '*/node_modules/*' -x '*/.venv/*' -x '*/dist/*' -x '*/build/*'
 ```
 
-**Per-language CCN thresholds** — a function is "god" when its CCN exceeds the threshold for its language. Python/JS/TS are idiom-dense and deserve the tightest cap; Go's for/if-heavy control flow tolerates higher CCN before it becomes hard to read.
+**Per-language CCN thresholds** — a function is "god" when its CCN exceeds its language's threshold. Go's for/if-heavy control flow tolerates a higher CCN before it becomes hard to read; idiom-dense Python/JS/TS get the tightest cap.
 
 | Language (lizard CSV column 7 / filename extension) | God-function CCN threshold |
 | --- | --- |
@@ -52,7 +51,7 @@ lizard -o /tmp/lizard.csv <repo> \
 | Go (`.go`) | > 15 |
 | Everything else | > 15 (fallback) |
 
-Parse using the per-language lookup. The lizard CSV has columns: `NLOC,CCN,token,param,length,location,file,name`. Key on file extension:
+The lizard CSV columns are `NLOC,CCN,token,param,length,location,file,name`; key the lookup on file extension:
 
 ```bash
 # God-functions counted per-language threshold
@@ -94,19 +93,15 @@ Capture:
 Run per ecosystem present in the repo. Detect via package manifest:
 
 ```bash
-# JS/TS — install project deps BEFORE running knip. knip walks imports and
-# needs the repo's own node_modules to resolve them; a bare `npx knip` on a
-# freshly-cloned repo with no deps installed silently produces `_NOT_RUN` /
-# empty output (observed when a sub-app reported `Cannot find module 'vite'`
-# and knip never ran).
+# JS/TS — install project deps BEFORE knip. knip resolves imports through the
+# repo's own node_modules; on a fresh clone it silently yields `_NOT_RUN` /
+# empty output (e.g. `Cannot find module 'vite'`).
 #
-# This branch is MANDATORY when package.json exists. The deps-install step is
-# not optional — do not skip it for time/budget reasons. If the install
-# genuinely fails (registry down, lockfile broken), knip still runs and
-# records the failure in /tmp/knip.err; the resulting `knip_NOT_RUN: true` in
-# the scorecard MUST be accompanied by a `knip_reason` quoting the install-step
-# error from /tmp/jsdeps.log. A reason of "deps-install step not executed this
-# pass" is non-conformant.
+# MANDATORY when package.json exists — never skip the install for time or
+# budget. If the install genuinely fails (registry down, lockfile broken), knip
+# still runs and records the failure in /tmp/knip.err; `knip_NOT_RUN: true`
+# MUST carry a `knip_reason` quoting the install error from /tmp/jsdeps.log.
+# "deps-install step not executed this pass" is a non-conformant reason.
 if [ -f <repo>/package.json ]; then
   cd <repo>
   # Detect lock file → pick the matching package manager. If no lock file
@@ -125,17 +120,12 @@ if [ -f <repo>/package.json ]; then
   npx --yes knip --reporter json > /tmp/knip.json 2> /tmp/knip.err || true
 fi
 
-# Python — detect src-layout / Poetry packages declarations so deptry doesn't
-# false-positive on first-party imports. One observed project reported 292
-# bogus DEP001s because deptry treated `app.*` imports (declared via Poetry's
-# `packages = [{ include = "app", from = "src" }]`) as third-party.
-#
-# Strategy: pull every `tool.poetry.packages[].include` and every
-# `tool.setuptools.packages.find` package name out of pyproject.toml, plus
-# any top-level package directory under src/ (setuptools-src layout
-# convention). Pass them as a comma-separated list to --known-first-party.
-# Falls back gracefully (empty list → flag omitted) if no pyproject.toml or
-# no parseable declarations.
+# Python — pass first-party packages to --known-first-party, or deptry reports
+# every first-party import as a bogus DEP001 (e.g. `app.*` declared via Poetry's
+# `packages = [{ include = "app", from = "src" }]`, hundreds of findings).
+# Collect `tool.poetry.packages[].include` and `tool.setuptools.packages.find`
+# names from pyproject.toml, plus every top-level dir under src/
+# (setuptools-src convention). An empty list omits the flag.
 if [ -f <repo>/pyproject.toml ] || [ -f <repo>/requirements.txt ]; then
   cd <repo>
   kfp=""  # known-first-party packages, comma-separated
@@ -270,15 +260,16 @@ elif [ -f <repo>/yarn.lock ]; then
   timeout 120 yarn npm audit --json > /tmp/npmaudit.json 2>/dev/null || true
 fi
 
-# Go — govulncheck walks the module graph. Skipped when go is not on PATH
-# (preflight.sh documents this; sub-agent emits _NOT_RUN when appropriate).
+# Go — govulncheck walks the module graph. Without go on PATH preflight skips
+# it; record the Go scan as `_NOT_RUN` with reason
+# "govulncheck unavailable (go not installed)".
 if [ -f <repo>/go.mod ] && command -v govulncheck >/dev/null 2>&1; then
   cd <repo>
   timeout 180 govulncheck -json ./... > /tmp/govulncheck.json 2>/dev/null || true
 fi
 
-# Container — Trivy scans a built image OR the filesystem directly. FS scan is
-# cheaper (no docker build) and covers the same OS+lang package surface.
+# Trivy — scan the filesystem, not a built image: same OS + language package
+# surface, no docker build.
 timeout 180 trivy fs --format json --scanners vuln --quiet \
   <repo> > /tmp/trivy.json 2>/dev/null || true
 ```
@@ -320,7 +311,7 @@ Capture (aggregated across every tool that ran):
 
 ## Raw dumps (flat — files under `raw/` named `maintainability-*`)
 
-Each signal writes its raw output to the flat `raw/` directory at the workspace root. Absent files = not extracted / not applicable. Aggregates go to `scorecard.yaml` under `data.`.
+Each signal writes its raw output to the flat `raw/` directory; an absent file means not extracted or not applicable. Aggregates go to `scorecard.yaml` under `data.`.
 
 | File | Source signal | Shape / note |
 | --- | --- | --- |
@@ -341,7 +332,7 @@ Each signal writes its raw output to the flat `raw/` directory at the workspace
 
 ## Aggregation → 0–5 band
 
-Scorer integrates the 5 signals. Rough directionality:
+Integrate Signals 1–6. Rough directionality:
 
 | Signal | Pulls score UP | Pulls score DOWN |
 | --- | --- | --- |
@@ -372,9 +363,9 @@ Scorer integrates the 5 signals. Rough directionality:
 | `SECRETS` | `gitleaks_findings ≥ 1` (any secret in git history — even if rotated) | `maintainability ≤ 2` |
 | `VULN` | `dep_vuln_critical ≥ 1` OR `dep_vuln_high ≥ 3` across any ecosystem tool that ran (`pip-audit` / `npm audit` / `govulncheck` / `trivy fs`). Skipped when `dep_vuln_NOT_RUN == true` (no recognized manifest). | `maintainability ≤ 2` |
 
-The `SECRETS` gate fires even if the secret has been rotated out of HEAD — leaked-and-revoked still blocks "pick up and extend" because the leak is permanent in git history. `gitleaks_any_still_in_head` lets the scorer comment on severity but doesn't change the gate.
+`SECRETS` fires even when the secret is rotated out of HEAD — the leak is permanent in git history, and "pick up and extend" assumes a trustworthy history. `gitleaks_any_still_in_head` never changes the gate; state the severity (still in HEAD vs. history-only) in evidence.
 
-The `VULN` gate fires on committed dependency manifests only; it does not attempt to resolve what version is actually running in production (runtime verification is out of scope — a separate maintainer follow-up). A repo that pins vulnerable versions but ships a build that avoids the vulnerable code path still takes the gate — the signal is "ships committed dependency hygiene", not "is exploitable at runtime".
+`VULN` reads committed dependency manifests only — no runtime resolution, no version-pinning analysis (runtime verification is out of scope). A repo pinning a vulnerable version takes the gate even if its build avoids the vulnerable code path: the signal is committed dependency hygiene, not exploitability.
 
 ---
 
@@ -436,10 +427,7 @@ data:
 
 ## Caveats
 
-- **lizard CCN thresholds are language-idiomatic.** Python's 10 ≠ Kotlin's 12 ≠ Go's 15. The per-language lookup in Signal 2 sets the threshold per file extension; absolute and fixed.
-- **knip / deptry only cover their ecosystems.** Mixed repos run both and aggregate; there's no polyglot dep-hygiene tool.
-- **LLM "pickup" judgment is brittle at sample size = 3 sampled files.** Evidence should name the files sampled.
-- **`SECRETS` gate is conservative.** Fires even on rotated secrets — "pick up and extend" assumes trust in git history, and rotation doesn't erase the leak. Scorer should mention severity (`still_in_head` vs. history-only) in evidence.
-- **`VULN` gate is committed-manifest only.** Does not attempt runtime resolution or version-pinning analysis. A repo that pins a vulnerable version but ships a build that avoids the vulnerable code path still takes the gate — by design, it's a cleanliness signal, not an exploitability signal.
-- **`CONTRIBUTING.md` / ADR / RFC presence** is a weak signal — absence is common even in healthy repos. Don't penalize for missing; reward when present.
-- **Tech-debt markers** may be legitimate scoping comments (`TODO: address in v2`) or abandoned work. LLM adjudicates when count is suspiciously high.
+- **knip / deptry cover only their ecosystems.** Mixed repos run both and aggregate; no polyglot dep-hygiene tool exists.
+- **The LLM "pickup" judgment is brittle at 3 sampled files.** Evidence **must** name the files sampled.
+- **`CONTRIBUTING.md` / ADR / RFC presence** is a weak signal — absence is common in healthy repos. Reward presence; never penalize absence.
+- **Tech-debt markers** may be legitimate scoping comments (`TODO: address in v2`) or abandoned work; the LLM adjudicates when the count is suspiciously high.

package/data/harnesses/hr/skills/evaluator/criteria/mechanical-ambition.md

@@ -5,7 +5,7 @@
 - **Contenders:** scc + Semgrep stub rule + git analytics + Tier-A build check + LLM README-vs-shipped diff (layered)
 - **Source quote:** _"Genuinely shippable scope."_
 
-This recipe measures the **mechanical** evidence of ambition (LoC, commits, delivery concentration, stubs, shipped-vs-promised ratio, Tier-A build) against the project's apparent size, and whether the built scope holds together. Bands are **absolute**. Gate this recipe owns: **`BROKEN`** (Tier-A build check fails outside `DEPS_NOT_INSTALLED`; caps **`mechanical_ambition ≤ 2`**).
+This recipe measures the **mechanical** evidence of ambition — LoC, commits, delivery concentration, stubs, shipped-vs-promised ratio, Tier-A build — against the project's apparent size, and whether the built scope holds together. Bands are **absolute**. This recipe owns the `BROKEN` gate, defined in § Gates.
 
 ---
 
@@ -162,7 +162,7 @@ Aggregate `build_check_passed` bool — true if all applicable checks produced z
 
 Capture: `build_check_passed` (bool), `build_errors_summary` (string — first 20 lines for LLM context), `build_checks_applied` (list of checks that ran).
 
-**Escalation note:** if errors contain `Cannot find module` / `ModuleNotFoundError`, flag `DEPS_NOT_INSTALLED` — Tier-A can't distinguish "broken" from "needs install." Scorer may choose to escalate to Tier-B (shallow install) for such repos.
+**Escalation:** if errors contain `Cannot find module` / `ModuleNotFoundError`, flag `DEPS_NOT_INSTALLED` — Tier-A cannot tell "broken" from "needs install". For such repos you may escalate to Tier-B (a shallow install).
 
 ### Signal 5 — LLM README-vs-shipped diff
 
@@ -192,7 +192,7 @@ Capture:
 
 ## Raw dumps (flat — files under `raw/` named `mechanical-ambition-*`)
 
-Each signal writes its raw output to the flat `raw/` directory at the workspace root. Absent files = not extracted. Aggregates go to `scorecard.yaml` under `data.`.
+Each signal writes its raw output to the flat `raw/` directory; an absent file means not extracted. Aggregates go to `scorecard.yaml` under `data.`.
 
 | File | Source signal | Shape / note |
 | --- | --- | --- |
@@ -202,13 +202,13 @@ Each signal writes its raw output to the flat `raw/` directory at the workspace
 | `raw/mechanical-ambition-tier-a-build.log` | Signal 4 | Combined output of checks that ran (py_compile, ruff -F, tsc --noEmit, go vet, gofmt, node --check). First 20 lines per tool. |
 | `raw/mechanical-ambition-llm-read.md` | Signal 5 | README-vs-shipped diff: `{promises: [...], shipped: [...], shipped_ratio, scope_match_score, notable_gaps, one_sentence}` |
 
-Additional short-lived intermediates: the `stubs.yml` semgrep rule config is a skill artifact — generate it under `$SKILL_DIR/criteria/mechanical-ambition-stubs.yml` (or inline on-the-fly), not in the repo workspace.
+The `stubs.yml` rule config is a scratch intermediate — write it to `/tmp/stubs.yml` (Signal 2), **never** into the scored repo or the workspace.
 
 ---
 
 ## Aggregation → 0–5 band
 
-Scorer integrates the 5 signals. Rough directionality:
+Integrate Signals 1–5. Rough directionality:
 
 | Signal | Pulls score UP | Pulls score DOWN |
 | --- | --- | --- |
@@ -236,16 +236,16 @@ Scorer integrates the 5 signals. Rough directionality:
 | --- | --- | --- |
 | `BROKEN` | `build_check_passed == false` (and not because of `DEPS_NOT_INSTALLED`) | `mechanical_ambition ≤ 2` |
 
-Affects this sub-criterion only. Canonical gate list in [../SKILL.md](../SKILL.md).
+Affects this sub-criterion only. The canonical gate list is [`SKILL.md` → Gates](../SKILL.md#gates-cap-specific-items-stack-additively).
 
 ---
 
 ## Fallback — signals missing
 
 - scc doesn't support a language → LoC count may under-report; document in evidence.
-- Semgrep stub rule misses project-specific stub patterns → LLM catches what regex missed; increase weight of Signal 5.
+- Semgrep stub rule misses project-specific stub patterns → the LLM read catches what the rule missed; weight Signal 5 more heavily.
 - Repo has < 5 commits → git analytics degrade (cramming, commit-rate meaningless); rely on Signals 1, 2, 5.
-- `DEPS_NOT_INSTALLED` flag on Tier-A → `BROKEN` gate does NOT fire on this alone; scorer should either: (a) escalate to Tier-B, or (b) defer build-status judgment to the LLM's read of repo shape.
+- `DEPS_NOT_INSTALLED` flag on Tier-A → the `BROKEN` gate does **not** fire on it alone; either escalate to Tier-B or defer build status to the LLM's read of repo shape.
 - README missing → Signal 5 is degraded; emit `llm_confidence: low`.
 
 Annotate evidence with `"Signals used: [...]"`.
@@ -293,8 +293,8 @@ data:
 
 ## Caveats
 
-- **Tier-A build check catches ~80% of breakage.** Import-resolution errors need deps installed. `DEPS_NOT_INSTALLED` flag suppresses the `BROKEN` gate when the check failed for install reasons.
-- **Stub detection via Semgrep misses project-specific patterns.** A function that returns hardcoded fake data without any stub marker looks "shipped" but isn't. LLM Signal 5 compensates.
-- **Delivery-concentration detection is heuristic.** Last-day share > 30% flags concentrated delivery but doesn't distinguish "final polish" from a single large drop. LLM evidence should adjudicate when the flag fires.
-- **`llm_shipped_ratio` depends on how the README frames features.** Terse READMEs may under-count promises; florid READMEs may over-count. Evidence should show the promise list.
-- **COCOMO is a sanity check, not a score driver.** `cocomo_estimated_months > 3` is a soft-overreach signal relative to the project's apparent size; `< 0.1` is a soft-underreach signal. Don't gate on it.
+- **The Tier-A build check catches ~80% of breakage** — import-resolution errors need deps installed, which is what `DEPS_NOT_INSTALLED` covers.
+- **Semgrep stub detection misses project-specific patterns.** A function returning hardcoded fake data with no stub marker looks shipped; Signal 5 compensates.
+- **Delivery-concentration detection is heuristic.** A last-day share > 30% cannot tell final polish from a single large drop; the LLM evidence adjudicates when the flag fires.
+- **`llm_shipped_ratio` depends on how the README frames features** — terse READMEs under-count promises, florid ones over-count. Evidence **must** show the promise list.
+- **COCOMO is a sanity check, never a score driver or a gate.** `cocomo_estimated_months > 3` is a soft overreach signal relative to the project's apparent size; `< 0.1` a soft underreach signal.

package/data/harnesses/hr/skills/evaluator/criteria/problem-substantiveness.md

@@ -4,13 +4,13 @@
 - **Weight:** 12.5 pts
 - **Source quote:** _"Is the problem clearly stated, non-trivial, with defined user/use-case?"_
 
-This recipe scores whether the problem is substantively framed — a crisp, non-trivial problem statement with a defined user and use-case, versus a toy-shaped placeholder.
+This recipe scores whether the problem is substantively framed — a crisp, non-trivial problem statement with a defined user and use-case — or a toy-shaped placeholder.
 
 ---
 
 ## Extraction recipe
 
-LLM-primary. The evaluator reads the top of the repo (README, any PRD/SPEC doc, sample data, one or two handler files) and answers: **Is this a substantive, well-defined problem, or a toy-shaped placeholder?**
+LLM-primary: read the top of the repo (README, any PRD/SPEC doc, sample data, one or two handler files) and decide whether it is a substantive, well-defined problem or a toy-shaped placeholder.
 
 ### Signal 1 — Problem framing (LLM interpretive)
 
@@ -21,7 +21,7 @@ Feed the LLM the following context:
 head -500 "$REPO/README.md" > /tmp/prob-sub-readme.md
 
 # PRD / SPEC / DESIGN docs if present
-find "$REPO" -maxdepth 3 -iname "PRD*.md" -o -iname "SPEC*.md" -o -iname "DESIGN*.md" \
+find "$REPO" -maxdepth 3 \( -iname "PRD*.md" -o -iname "SPEC*.md" -o -iname "DESIGN*.md" \) \
   -not -path '*/node_modules/*' -not -path '*/.venv/*' 2>/dev/null \
   | xargs -I{} head -200 {} 2>/dev/null > /tmp/prob-sub-docs.md
 
@@ -33,7 +33,7 @@ find "$REPO" -maxdepth 4 \( -iname '*.csv' -o -iname '*.json' -o -iname 'sample*
 tree -L 2 -I 'node_modules|.venv|.git|dist|build' "$REPO" 2>/dev/null | head -80 > /tmp/prob-sub-tree.txt
 ```
 
-Write the LLM read to `raw/problem-substantiveness-llm-read.md`. The LLM emits:
+Write the LLM read to `raw/problem-substantiveness-llm-read.md`. It emits:
 
 ```yaml
 detected_domain: "internal dev tooling" | "customer-facing SaaS" | "infra automation" | "ops observability" | "data pipeline" | "agent/LLM tooling" | ...
@@ -71,7 +71,7 @@ Aggregate the LLM output into `raw/problem-substantiveness-proxies.json`:
 | **1** | No problem statement, or README is an unmodified starter/template README. `problem_clarity_score ≤ 1`. |
 | **0** | Empty README + no PRD/SPEC + toy pattern detected. |
 
-**Toy-pattern auto-floor:** if `toy_pattern_detected == true` (hello-world, generic TODO, calculator, tic-tac-toe, etc.), cap the band at **2** regardless of other signals — a clear problem statement doesn't rescue a toy.
+**Toy-pattern cap:** if `toy_pattern_detected == true` (hello-world, generic TODO, calculator, tic-tac-toe, etc.), cap the band at **2** regardless of other signals — a clear problem statement never rescues a toy.
 
 ---
 
@@ -84,5 +84,5 @@ Aggregate the LLM output into `raw/problem-substantiveness-proxies.json`:
 
 ## Not in scope
 
-- Judging whether the problem matches a specific organization's real priorities needs operational context — out of scope; this scores whether the problem is substantively framed, not whether it's the right problem for any given org to be solving.
-- Judging the quality of the implementation — that's 1.1–1.4 + 2.4. This recipe only looks at framing.
+- **Whether it is the right problem for a given organization** — that needs operational context; this recipe scores only whether the problem is substantively framed.
+- **Implementation quality** — scored by 1.1–1.4 and 2.4.