@damiangilgonzalez/harness 1.3.7

package/skills/open-weights/references/licenses.md

@@ -0,0 +1,123 @@
+# Open-weight LICENSES — the load-bearing reference
+
+**Get this wrong and you ship something you have no legal right to ship.** This is the section that
+most often bites teams. The cardinal rule, again: **state the license class, then open the exact
+model + size card and confirm.** Everything below is class guidance + [verify-the-card] pointers,
+authored mid-2026 — licenses move per version, per size, per release month.
+
+## The three classes
+
+### 1. OSI-open (Apache-2.0, MIT) — permissive
+
+Commercial use, modification, and redistribution are allowed. Apache-2.0 adds a patent grant and a
+notice/attribution requirement (keep the `NOTICE`/`LICENSE`); MIT is barely-there attribution. This
+is the class you want for a product you distribute. Still read the card — attribution and notice
+obligations are real even when permissive.
+
+Class members (mid-2026, **verify each**): most Qwen sizes, Mistral open models, Phi (MIT), gpt-oss
+(Apache-2.0), DeepSeek-R1 (MIT), Gemma **4** (Apache-2.0), OLMo, SmolLM.
+
+### 2. Custom / community — free use *with conditions*
+
+Broad, royalty-free rights **but** the vendor keeps strings attached: an acceptable-use policy,
+mandatory attribution, naming rules, sometimes a scale cap, and a duty to pass restrictions
+downstream. **This is NOT OSI-open** even though people loosely call it "open." You can usually ship
+commercially — *if* you meet every condition.
+
+Class members (mid-2026, **verify**): **Llama** (Meta Community License), **Gemma 1–3** (Gemma
+Terms of Use).
+
+### 3. Non-commercial / restricted — cannot ship without a separate license
+
+Free to download and evaluate, but **not** for commercial deployment. Includes "research-only"
+cards, some RAIL variants, revenue-gated licenses ("above $X/month you must buy a commercial
+license"), and non-production licenses. Missing one of these is the expensive mistake.
+
+Class members (mid-2026, **verify**): **original Codestral** (MNPL non-production), some Cohere
+Command terms, various research-only community fine-tunes.
+
+## Per-family detail
+
+### Llama — Meta Llama Community License (custom, NOT OSI-open)
+
+- **Acceptable Use Policy** incorporated by reference — prohibited uses bind you and your users.
+- **Attribution:** derivatives/products must **prominently display "Built with Llama"**, and derived
+  model names must carry "Llama" per the naming rules.
+- **Redistribution:** include a copy of the Community License with any distribution of the weights.
+- **Scale cap:** if your product (or affiliates') exceeds **700M monthly active users** in the prior
+  calendar month, you must **request a license from Meta**, granted at Meta's sole discretion.
+- **Gated** on the Hub — accept terms before you can download.
+- Meta has revised terms across Llama versions — **verify the current version's license page**.
+
+### Gemma — custom Gemma Terms of Use + Prohibited Use Policy (Gemma 1–3)
+
+- Not Apache. A Google-authored license with a **Prohibited Use Policy** covering sensitive domains.
+- **Downstream pass-through:** if you distribute Gemma or a Gemma-derived model (weights, API, or
+  embedded), you must include/reference the Terms, ship the notice file ("Gemma is provided under
+  and subject to the Gemma Terms of Use found at ai.google.dev/gemma/terms"), and bind downstream
+  users to the Prohibited Use Policy. The restrictions **follow derivatives** — a fine-tune can't be
+  used for a purpose that would've been prohibited on the base.
+- **Gemma 4** reportedly switched to **Apache-2.0** (confirmed on ai.google.dev/gemma/terms,
+  2026-07-18). Same brand, different class by version — **check which Gemma you have.**
+- Google claims no rights in outputs you generate.
+
+### Qwen — mostly Apache-2.0, with per-size variance
+
+- Most sizes are Apache-2.0. Historically the very largest (and occasionally a special tier) shipped
+  under a separate **Qwen license**. Do not assume the whole family is Apache — **check each size**.
+
+### Mistral / Mixtral
+
+- Open models (Mistral 7B, Mixtral 8x7B/8x22B, many "Small") = **Apache-2.0**.
+- **Original Codestral = MNPL (Mistral AI Non-Production License)** — research/eval only, **no
+  commercial deployment**. **Codestral 2** relicensed **Apache-2.0** (Apr 2026) [verify which one].
+- Some newer models use a **"Modified MIT"** with a revenue-threshold commercial clause (e.g. above
+  a monthly-revenue bar you need a commercial license / Mistral platform access). Verify.
+
+### DeepSeek — per-model split
+
+- **Code** repositories: MIT.
+- **DeepSeek-R1** weights: **MIT**.
+- **Original DeepSeek-V3** weights: **custom DeepSeek License Agreement** (v1.0) with **OpenRAIL-
+  style use-based restrictions** (military use, harm to minors, disinformation, PII, discrimination,
+  etc.), which you must **pass forward** as an enforceable provision on redistribution.
+- Newer point releases have trended toward MIT [verify]. "DeepSeek = MIT" is an over-simplification.
+
+### Phi — MIT
+
+- The Phi-4 family (Phi-4, Phi-4-mini, reasoning, multimodal) is **MIT** [verify] — commercial use,
+  fine-tuning, redistribution allowed, no royalties.
+
+### gpt-oss — Apache-2.0
+
+- gpt-oss-20b / gpt-oss-120b = **Apache-2.0** [verify] — permissive commercial use.
+
+## Gated models (mechanics)
+
+Some models (Llama, Gemma, many others) are **gated**: you must accept terms on the Hub model page,
+then use a read-scoped token. Gating is an access gate, not a use-class — a gated model can be
+commercially usable (under its conditions), and an ungated model can still be non-commercial.
+Downloading without accepting terms returns a 403. The download step itself is a `huggingface` job.
+
+## The fine-tune / distill inheritance trap
+
+**A derivative inherits the base model's license and obligations.**
+
+- Fine-tune Llama → your fine-tune still owes "Built with Llama", the Acceptable-Use Policy, and the
+  MAU clause. You cannot re-license it as MIT.
+- Fine-tune Gemma → the Gemma Terms + Prohibited Use Policy follow your model downstream.
+- A **distill** trained on another model's outputs can inherit the **teacher's** terms (this is how
+  a restriction can travel into a model whose own card looks permissive). Check the base_model chain.
+- Merging models can compound obligations from **every** parent. Trace the lineage.
+
+When in doubt, treat the strictest ancestor's license as governing, and confirm on each card.
+
+## Commercial-ship decision flow
+
+1. Identify the **exact model + size** (not the family) you'll deploy.
+2. Open its `LICENSE` / terms page on the Hub or the vendor site.
+3. Classify: OSI-open → ship (honor attribution/notice). Custom/community → meet the conditions
+   (attribution string, AUP, MAU/revenue caps, pass-through) → ship. Restricted/non-commercial →
+   **stop**; get a separate license or pick another model.
+4. If it's a fine-tune/distill/merge, repeat for **every** ancestor and take the strictest.
+5. Record the decision (which model, which license, which conditions) — see `decision-records`.

package/skills/open-weights/references/model-families.md

@@ -0,0 +1,83 @@
+# Open-weight model families — depth notes
+
+**Every version and license line here is [verify the card] — authored against cards live mid-2026
+(accessed 2026-07-18). Families and rough size ladders are durable; specific versions are not.**
+Do not quote a license from this file into a product decision — open the model's `LICENSE`.
+
+## Llama (Meta)
+
+- **Sizes:** historically ~1B–70B dense; current line (Llama 4: Scout, Maverick) uses a
+  **mixture-of-experts** design with large total-param counts but a smaller active count per token.
+- **Strengths:** huge ecosystem — the most fine-tunes, quants, tooling, and community docs of any
+  family. If "will it just work in my runtime" matters, Llama is the safe bet.
+- **License:** **Meta Llama Community License — custom, NOT OSI-open.** Acceptable-Use Policy,
+  "Built with Llama" attribution, naming rules, and a **>700M-MAU** clause. Gated on the Hub. See
+  [licenses.md](licenses.md).
+
+## Qwen (Alibaba)
+
+- **Sizes:** a very wide ladder — sub-1B up to 200B+ (dense **and** MoE). Strong specialized lines:
+  **Qwen-Coder** (coding), **Qwen-VL** (vision), reasoning variants. Recent lines (Qwen3 / Qwen3.5 /
+  Qwen3.6) [verify].
+- **Strengths:** excellent multilingual coverage, strong coding, a size for nearly every hardware
+  budget, generally permissive licensing.
+- **License:** **mostly Apache-2.0 but per-size variance** — some sizes historically shipped under a
+  separate Qwen license. Check **each size's** card; never generalize "Qwen = Apache" to the family.
+
+## Mistral / Mixtral (Mistral AI)
+
+- **Sizes:** 7B dense (Mistral 7B), MoE (Mixtral 8x7B / 8x22B), and named tiers (Small/Large/Nemo).
+- **Strengths:** efficient, strong for their size; Mixtral popularized accessible MoE.
+- **License:** open models **Apache-2.0**; but **Codestral (original, code model) = MNPL
+  non-production** — free to eval, not to ship commercially. **Codestral 2** was relicensed
+  Apache-2.0 (Apr 2026) [verify]. Some newer models use a "Modified MIT" with a revenue-threshold
+  commercial clause. Per-model check required — see [licenses.md](licenses.md).
+
+## Gemma (Google)
+
+- **Sizes:** ~1B–~27B, plus specialized siblings: **PaliGemma** (vision-language), **CodeGemma**,
+  **ShieldGemma** (safety), **RecurrentGemma**, EmbeddingGemma, DataGemma.
+- **Strengths:** strong small-model quality, good multilingual, tight integration with Google tooling.
+- **License:** **Gemma 1–3 = custom Gemma Terms of Use + Prohibited Use Policy** (NOT Apache), with
+  a downstream pass-through duty. **Gemma 4** reportedly moved to **Apache-2.0** (confirmed on
+  ai.google.dev/gemma/terms, 2026-07-18) — verify the version you use. See [licenses.md](licenses.md).
+
+## DeepSeek
+
+- **Sizes:** very large MoE base/chat (V3-class, hundreds of B total), **R1** reasoning models, plus
+  **distills** into smaller Llama/Qwen backbones (handy for consumer hardware).
+- **Strengths:** frontier-class reasoning and coding at open-weight cost; distills bring much of the
+  quality to small sizes.
+- **License:** **per-model split.** Code repos MIT; **DeepSeek-R1 weights MIT**; original
+  **DeepSeek-V3 weights = custom DeepSeek License Agreement with OpenRAIL-style use restrictions**.
+  Newer point releases have moved toward MIT [verify]. Never assume "DeepSeek = MIT" — check the model.
+
+## Phi (Microsoft)
+
+- **Sizes:** small — ~3B to ~15B ("mini", reasoning, multimodal variants in the Phi-4 family).
+- **Strengths:** punches above its weight on reasoning for the size (trained on curated/synthetic
+  data); great for edge and cost-sensitive deployments.
+- **License:** **MIT** across the Phi-4 family [verify] — genuinely permissive, commercial-friendly.
+
+## gpt-oss (OpenAI)
+
+- **Sizes:** **gpt-oss-20b** and **gpt-oss-120b** — MoE, open *weights*. 120B runs on a single 80 GB
+  GPU; 20B targets ~16 GB.
+- **Strengths:** OpenAI's first open-weight LLMs since GPT-2; strong reasoning/agentic/tool-use.
+- **License:** **Apache-2.0** [verify] — permissive. Confirmed on OpenAI's own model-card page and
+  the Hugging Face repo (2026-07-18).
+
+## Others worth knowing (check the card)
+
+- **OLMo (AI2)** — *fully* open: weights **and** training data/code released. The pick when
+  reproducibility/provenance matters, not just weight availability.
+- **SmolLM (HF)** — tiny, permissive, edge-friendly.
+- **Falcon (TII)**, **Yi (01.AI)**, **Command / Command-R (Cohere)** — Command family often carries
+  more restrictive terms (research vs commercial split); verify carefully before shipping.
+
+## The "will it work Monday" filter
+
+Beyond quality, a family/size is only a real option if the **ecosystem** supports it: ready-made
+GGUF/AWQ/GPTQ quants on the Hub, support in your runtime (llama.cpp/Ollama/vLLM/TGI), documented
+chat template, and recent downloads. A brand-new model with no quants and no runtime support is a
+research artifact — route the actual pull to `huggingface` and the run to `ollama`/`vllm`.

package/skills/open-weights/references/sizing-and-quant.md

@@ -0,0 +1,89 @@
+# Size ↔ VRAM and quant formats — selection-time depth
+
+This is the **"will it fit before I pick it"** estimate. The **operational** per-request KV-cache
+sizing and runtime flags live in `ollama` (single box) and `vllm` (serving) — do not duplicate them
+here. These numbers are rules of thumb for *choosing a size class*, not a per-model spec sheet;
+confirm the real footprint with `ollama show` or the model card.
+
+## The weights formula
+
+```text
+weights_GB ≈ params(B) × bytes_per_param
+  fp16 / bf16 → 2.0     (2 GB per 1B params)
+  int8 / 8-bit → ~1.0   (1 GB per 1B params)
+  4-bit        → ~0.5–0.6 (≈ 0.6 GB per 1B params, conservative)
+
+total_VRAM ≈ weights_GB + KV_cache + runtime_overhead
+```
+
+The 4-bit rate is a round number: measured k-quant rates land near ~4.9 bits/weight for Q4_K_M
+(~0.6 byte/param). Round **up** when budgeting so you don't OOM. **KV cache and overhead are extra**
+and grow with context length — always leave a margin above the weights figure.
+
+### Worked examples (weights only, fp16 unless noted)
+
+| Model | Params | fp16 | 8-bit | 4-bit |
+|---|---|---|---|---|
+| Small | 3B | ~6 GB | ~3 GB | ~2 GB |
+| Mid | 8B | ~16 GB | ~8 GB | ~5 GB |
+| Large-consumer | 32B | ~64 GB | ~32 GB | ~20 GB |
+| Big | 70B | **~140 GB** | ~70 GB | ~40 GB |
+
+**The 70B lesson:** fp16 ~140 GB does not fit any single GPU on the market for most teams. Options:
+(a) **quantize** to 4-bit (~40 GB → fits one 80 GB card), accepting some quality/throughput cost; or
+(b) **tensor-parallel** across multiple GPUs (e.g. 2×80 GB) to keep full precision — a `vllm` job.
+
+## What fits which hardware class
+
+| Hardware | fp16 ceiling (weights) | Practical pick |
+|---|---|---|
+| 8 GB consumer GPU | ~3B | 7–8B @ 4-bit (~5 GB) + small context |
+| 12 GB | ~5B | up to ~14B @ 4-bit |
+| 16 GB | ~7B | 13–14B @ 4-bit; 7–8B @ 8-bit |
+| 24 GB (3090/4090) | ~10B | ~32B @ 4-bit (~20 GB) |
+| 48 GB (or 2×24) | ~22B | 70B @ 4-bit is tight; better on 80 GB |
+| 80 GB (A100/H100) | ~34B | 70B @ 4-bit (~40 GB), or a big MoE (gpt-oss-120b) |
+| 2×80 GB+ | 70B fp16 (~140 GB) via TP | full-precision large models |
+| Apple unified (e.g. 64 GB) | shares with the whole OS | budget vs **total** unified memory, not a GPU number |
+| CPU / edge | — | small GGUF (≤3B) at 4-bit; slow but runs |
+
+## MoE: total vs active params
+
+Mixture-of-experts models (Mixtral, gpt-oss, Llama 4, big Qwen/DeepSeek) route each token through a
+**subset** of experts. So a "120B" MoE might activate only ~5B params per token (fast inference) —
+**but you still need VRAM to hold all experts.** Budget against **total** params for memory and
+against **active** params for the speed intuition. Don't size a 120B MoE as if it were a 5B dense.
+
+## Quant formats — pick by runtime
+
+| Format | Runtime | Notes |
+|---|---|---|
+| **GGUF** | llama.cpp, Ollama, LM Studio | The local default. CPU + Apple Silicon + single GPU. Self-contained files with quant in the name. |
+| **AWQ** | vLLM, TGI, transformers | Activation-aware weight quant; strong 4-bit quality for GPU serving. |
+| **GPTQ** | vLLM, TGI, transformers | Older post-training quant; very widely available 4-bit. |
+| **bitsandbytes (NF4/int8)** | transformers | Load-time quantization — quick for experiments and QLoRA fine-tuning. |
+| **EXL2** | ExLlamaV2 | Variable bit-rate; good on consumer GPUs, flexible size/quality. |
+
+Rule: **local/Mac/CPU → GGUF**; **GPU serving → AWQ or GPTQ**; **fine-tuning experiments → bnb NF4**.
+Getting or converting to a format is a `huggingface` (convert) / `ollama` / `vllm` job.
+
+## Decoding a GGUF quant tag
+
+`Q4_K_M`:
+- **`Q4`** — nominal ~4-bit weights.
+- **`_K`** — a **k-quant**: mixed precision that keeps the more error-sensitive tensors (attention,
+  some feed-forward) at higher bit-depth than the bulk. Better quality than the old flat `Q4_0`.
+- **`_M`** — size/quality **tier**: `_S` (small, lower), `_M` (medium — the balanced default),
+  `_L` (large, higher). There are also non-K legacy tags (`Q4_0`, `Q4_1`, `Q5_0`…).
+
+Quality ladder (rough): `fp16` ≥ `Q8_0` (near-lossless, ~1 byte/param) > `Q6_K` > `Q5_K_M` >
+**`Q4_K_M`** (standard default, ~half of fp16 for a few % loss) > `Q3_K` > `Q2_K` (noticeable
+degradation). **Do not drop below Q4 to cram a too-big model onto a too-small GPU** — the quality
+falls off fast and you'll often still OOM at real context. Pick a smaller model instead.
+
+## Selection heuristic
+
+1. Estimate weights_GB at 4-bit for the sizes you're considering.
+2. Keep it **comfortably under** your VRAM (leave ~20–30% for KV cache + overhead + context).
+3. If nothing that fits passes your eval, the honest options are: a better-tuned smaller model, a
+   bigger box (route to `runpod`/`modal`), or `vllm` tensor-parallel — **not** sub-Q4 desperation.

package/skills/orient/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: orient
+description: "Always-on. The brújula: close every turn by situating the person — where they are, what just happened, why it mattered, and the next step as a question, never a dead end. Reads the accompaniment and technical dials from docs and calibrates how much it explains, rewriting the dial when the user asks for more or less. NOT the missing-skill installer (that is `suggest`)."
+tags: [orient, guide, compass, dial, meta, always-on]
+recommends: []
+profiles: [minimal, core, ui, full]
+origin: risco
+---
+
+# orient — the brújula that never leaves the user lost
+
+You are always loaded. Your one job: **after anything happens, keep the human oriented.** A tool
+executes and falls silent; a mentor walks alongside. You are what makes the harness a mentor.
+
+`suggest` keeps the *session* equipped ("you're missing a skill, install it?"). You keep the *person*
+equipped ("you are here, you did this, for this reason, next is X — which?"). The install prompt is
+its job, never yours.
+
+## The one rule
+
+**No turn ends in seco.** Any turn that finishes an action, reaches a fork, or could leave the user
+unsure closes with the brújula block. One block, at the end — never interrupt mid-work to orient.
+
+## The brújula block
+
+Four intents. The wording adapts to the person; the intents do not.
+
+```text
+📍 Dónde estás — the project phase/state (the map)
+✅ Qué acabas de hacer — one line, in the user's language
+🧭 Por qué — the technical why, scaled to the dial
+➡️ Siguiente — 1-3 concrete options, ending in a question
+```
+
+Situate them from what is **actually** built. If you are unsure of the project state, read the
+Knowledge map or the repo before writing 📍 — an invented state is worse than a shorter block.
+
+## Calibrate to the dial
+
+Read `docs/wiki/harness/user-profile.md` before writing the block. Two fields combine:
+`accompaniment_level` sets the depth, `technical_level` sets the vocabulary.
+
+| accompaniment_level | How the block behaves |
+|---------------------|-----------------------|
+| L0 — cavernícola | Only `✅` + `➡️`. One next option, a yes/no question. |
+| L1 — breve | The four lines; `🧭` is one line of why. |
+| L2 — explica decisiones | The four lines; `🧭` justifies the relevant decision; offer real forks. |
+| L3 — acompañamiento total | The four lines, full why, each option explained in plain language. |
+
+`technical_level` is orthogonal: a non-technical user gets plain language and analogies even at L0;
+a technical user skips the 101 explanations even at L3. No profile yet → assume non-technical + L3
+(the non-technical-first default) and offer to set the dial.
+
+The dial is spoken, not configured: when the user says "explícame más / menos", "no me expliques
+tanto" or "enséñame", update `accompaniment_level` in the profile, confirm in one line, and apply
+the new depth from this turn on.
+
+At a real fork, ask. Deciding alone is faster and wrong — the fork is the moment the person's
+judgment is worth more than yours.
+
+## See Also
+
+- `references/orientation-contract.md` — the full brújula contract: block anatomy, what each of the
+  four beats must contain, and how the dial changes their depth. Read it when a turn ends ambiguously
+  or when calibrating a new dial level.

package/skills/orient/evals/README.md

@@ -0,0 +1,16 @@
+# Evals — orient
+
+The always-on brújula. These cases check that it keeps the user oriented at the end of a
+turn (map + what happened + why-at-level + next step as a question) and that it defers
+install prompts to `suggest` and never interrupts trivial mid-flow edits.
+
+| Prompt | Expected |
+|---|---|
+| "ya está instalado, ¿y ahora qué?" | situate + next step as a question |
+| "no sé por dónde seguir" | render the map + 1-3 next options |
+| "explícame menos" | lower the dial, confirm, apply reduced depth |
+| "renombra esta variable" | no full brújula block (trivial mid-flow) |
+| "necesito una base de datos" | defer to `suggest` (no duplicate install prompt) |
+
+A pass = orient closes the turn without leaving the user in seco, scales the why to the
+dial, and never duplicates `suggest`'s install prompt.

package/skills/orient/evals/cases.yaml

@@ -0,0 +1,57 @@
+skill: orient
+
+# The always-on brújula. It fires at the END of a turn to keep the user oriented:
+# map + what happened + why (scaled to the dial) + a next step phrased as a question.
+# It defers "install a missing skill?" to suggest and does not interrupt mid-work.
+
+should_trigger:
+  - prompt: "Ya está instalado el postgresdb. ¿Y ahora qué?"
+    why: "An action just finished and the user is explicitly unsure what to do next — orient must situate them and propose the next step."
+
+  - prompt: "Vale, hemos creado la landing. ¿Qué hago con esto?"
+    why: "A step finished and the user asks for direction — orient closes with the map + next options as a question."
+
+  - prompt: "No sé por dónde seguir con mi proyecto."
+    why: "The user is lost — the core trigger: situate on the map and propose 1-3 next steps."
+
+  - prompt: "Explícame menos, que me agobio con tanto detalle."
+    why: "A spoken dial request — orient lowers accompaniment_level, confirms it, and applies the new depth."
+
+  - prompt: "¿En qué punto del proyecto vamos?"
+    why: "A 'where am I?' question — orient renders the map (what's built, what's missing, what phase)."
+
+  - prompt: "Acabo de terminar el spec. Listo."
+    why: "A turn ends after finishing work — orient must not end in seco; it proposes the next phase as a question."
+
+should_not_trigger:
+  - prompt: "Renombra esta variable a `userCount`."
+    route_to: "none"
+    why: "A trivial mechanical edit mid-flow — orient does not interrupt with a full brújula block over a one-line change."
+
+  - prompt: "Necesito una base de datos para guardar pedidos."
+    route_to: "suggest"
+    why: "This is an install gap — suggest owns it. orient must not duplicate the 'install it?' prompt."
+
+  - prompt: "Optimiza esta query de Postgres que va lenta."
+    route_to: "postgresdb"
+    why: "A concrete task owned by another skill; orient adds the closing block but does not drive the work."
+
+  - prompt: "Arregla el test que falla."
+    route_to: "external:superpowers-systematic-debugging"
+    why: "Root-cause work owned by superpowers' systematic-debugging; orient does not take over the task itself."
+
+capability:
+  - scenario: "The user just ran `npx @damiangilgonzalez/harness add postgresdb` and says 'ya está, ¿y ahora qué?'. The profile shows accompaniment_level L0. Show how orient closes the turn."
+    must_include:
+      - "Situates the user on the map ('📍 dónde estás' / what is built vs missing)"
+      - "States what just happened in one plain-language line ('✅ instalaste la base de datos')"
+      - "Proposes a concrete next step ending in a question, never leaving the turn in seco"
+      - "At L0, keeps it to ✅ + ➡️ with a single yes/no option and zero jargon"
+      - "Does NOT re-prompt to install a skill (defers that to suggest)"
+
+  - scenario: "Mid-project, the user says 'explícame menos'. The profile shows accompaniment_level L2. Show how orient responds."
+    must_include:
+      - "Updates accompaniment_level in docs/wiki/harness/user-profile.md to a lower level"
+      - "Confirms the change in one line"
+      - "Re-renders guidance at the reduced depth from this turn on"
+      - "Still closes with a next-step question (no seco)"

package/skills/orient/references/orientation-contract.md

@@ -0,0 +1,34 @@
+# Orientation contract
+
+The single definition of how the harness keeps the user oriented. The `orient` skill owns
+it; other skills reference this file in a short footer instead of copying it.
+
+## The rule
+
+**No turn ends in seco (dead-end).** Every turn that finishes an action, reaches a fork, or
+could leave the user unsure closes with the brújula block.
+
+## The brújula block
+
+```
+📍 Dónde estás — the project phase/state (the map)
+✅ Qué acabas de hacer — one line, in the user's language
+🧭 Por qué — the technical why, scaled to the dial
+➡️ Siguiente — 1-3 concrete options, ending in a question. Never in seco.
+```
+
+## Calibration (the dial)
+
+Read `docs/wiki/harness/user-profile.md`. Two fields combine: `accompaniment_level` (L0 | L1 | L2 | L3) sets how deep the block goes; `technical_level` (non-technical | mixed | technical) sets the vocabulary.
+
+- **L0 — cavernícola:** only `✅` + `➡️`, one option, yes/no question.
+- **L1 — breve:** the four lines; one line of why.
+- **L2 — explica decisiones:** the four lines; justify the relevant decision; real forks.
+- **L3 — acompañamiento total:** the four lines, full why, many orienting questions, each option in plain language.
+
+`technical_level` is orthogonal (plain language for `non-technical` even at L0; skip 101s for `technical` even at L3). Missing profile → assume `non-technical` + **L3** and offer to set the dial.
+
+## Division of labor
+
+- `orient` guides the **person** (this contract).
+- `suggest` equips the **session** ("install the missing skill?"). Defer install prompts to it.

package/skills/people-ops/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: people-ops
+description: "Use when the offer is signed and you now have to run the person — an onboarding plan from preboarding through the 30/60/90 ramp, drafting or auditing an internal policy or handbook section, standing up the recurring people rhythm (1:1s, review and goal cycles, headcount), or offboarding a leaver. NOT sourcing, interviewing or the offer itself (that is `hiring`)."
+tags: [people-ops, hr, onboarding, employee-handbook, policy, offboarding, one-on-ones, retention]
+recommends: [hiring, contracts, gdpr-privacy, sop-builder, project-ops, e-signature]
+origin: risco
+---
+
+# People-ops
+
+You run the people function as a steady operation, starting the moment a candidate says yes. Three jobs, no more: **onboard** the new hire, **write the policies** that govern them, and **run the people rhythm** so it does not live in one founder's head. The identity line: the offer is signed — now get this person productive, write the policies that bind them, and keep the team's people-rhythm running.
+
+One hard line sits above everything: **you begin at offer-signed.** Sourcing, screening, interviewing, scoring, and the offer itself are not yours — they belong to `../hiring/SKILL.md`. You also do not write the binding instruments. The employment contract, NDA, and IP-assignment are `../contracts/SKILL.md`; the handbook you write explicitly *is not* a contract. Employee-data privacy and GDPR record-handling are `../gdpr-privacy/SKILL.md`. A generic non-people process doc (how we deploy, how we close the books) is `../sop-builder/SKILL.md`; a cross-function team ritual is `../project-ops/SKILL.md`. When the work crosses one of those lines, hand off — do not improvise legal text or a deploy runbook under the banner of "HR."
+
+## The four moments (the spine)
+
+Every request lands in one of four moments. Find the moment first; it tells you the artifact to produce.
+
+| The moment | Trigger | Artifact you produce |
+|---|---|---|
+| **Preboarding** | Offer just signed, start date set | Preboarding checklist — paperwork + access requests pulled *forward* (fact 3) |
+| **Day 1** | Person starts today | Day-1 checklist — access live, equipment ready, intros; **no form marathon** |
+| **Ramp (30/60/90)** | First quarter | A 30/60/90 plan framed learn → contribute → own, with named **manager** moves |
+| **Ongoing rhythm** | Recurring | Weekly 1:1 + review/goal cadence; headcount + who-owns-what |
+| **Exit** | Someone is leaving | Offboarding checklist — same-day access revocation, knowledge handoff, exit conversation |
+
+Do not skip backward. If a founder asks for a 30/60/90 but preboarding never happened, say so — the plan assumes Day 1 already went right.
+
+## Onboarding
+
+The first 90 days decide retention, and almost nobody plans them. ~20% of organizations report half their new hires leave within the first 90 days; only ~29% run a structured 90-day program (Enboarder 2025 HR Leader survey, accessed 2026-06-02). A structured plan is the cheapest retention you will ever buy.
+
+**Pull paperwork into preboarding — protect Day 1.** ~40% of onboarding time is eaten by compliance tasks; e-signature, pre-filled forms, and self-service enrollment cut that from a day to under an hour (Pin / Kayako onboarding guides, accessed 2026-06-02). Send forms, equipment order, and account-provisioning requests in the days *before* the start date. Day 1 is then about people — the team, the manager, the first real task — not a desk of forms. Route the e-signature mechanics to `../e-signature/SKILL.md`.
+
+**The 30/60/90, framed learn → contribute → own:**
+
+- **Days 1–30 — learn.** Tools, codebase/product, who's who, the team's norms. One small shipped thing by day 30 so the win is real, not theoretical.
+- **Days 31–60 — contribute.** Owns a small recurring responsibility; pairs less; gives feedback on a process.
+- **Days 61–90 — own.** Carries a deliverable end-to-end; the ramp is a fact, not a hope.
+
+**Name the manager's moves — this is the biggest lever.** Active manager engagement makes a new hire ~3.4x more likely to report an exceptional onboarding experience, yet only ~18% discuss performance goals with their manager in the first 90 days (Gartner, 3,400 hires, via Asana, accessed 2026-06-02). So the plan must say what the *manager* does, not just HR:
+
+- Day 1: a real welcome and the first concrete task (not "settle in").
+- Week 1: the **goals conversation** — what good looks like at 30/60/90.
+- Assign a **buddy** (peer, not the manager) for the "dumb question" channel.
+- **Weekly 1:1 from week one** — the habit that holds the rest together (see rhythm).
+
+A plan with no named manager and no goals conversation is HR talking to itself. The full preboarding / Day-1 checklists and a 30/60/90 with separate manager and new-hire columns live in `references/templates.md`.
+
+## Day-1 legal clock (US — confirm your jurisdiction)
+
+> **Confirm the jurisdiction before you write a date.** The table below is **US**. The EU, UK, and most countries differ, and many are **not at-will** — do not copy this clock into a non-US plan. Defer the actual employment contract to `../contracts/SKILL.md` and employee-record privacy to `../gdpr-privacy/SKILL.md`.
+
+In the US the Day-1 clock is hard-dated, and the fines are per-form (SHRM / USCIS / E-Verify, accessed 2026-06-02):
+
+| Step | Deadline | Who |
+|---|---|---|
+| I-9 **Section 1** | On or before the first day of work (may be done after acceptance) | Employee |
+| I-9 **Section 2** | Within **3 business days** of hire | Employer |
+| **E-Verify** case (where used) | By the **3rd business day** | Employer |
+
+Paperwork errors run **$288–$2,861 per form** — which is exactly why the I-9 belongs in preboarding for Section 1 and on the calendar for Section 2, not improvised on a busy first morning.
+
+## Writing policy / the employee handbook
+
+A handbook is **"not a contract" only if it says so and avoids contractual language.** Courts treat handbooks as implied contracts when they promise guaranteed employment or rigid progressive discipline (MRA / HRMorning / Mosey, accessed 2026-06-02). Required guardrails on every handbook you draft (US at-will — many countries are not at-will; flag it):
+
+1. An explicit **at-will + "this is not a contract"** disclaimer.
+2. A **signed acknowledgment** the employee returns.
+3. **No mandatory terms** — avoid "will / must / shall guarantee," rigid step-by-step discipline you must follow.
+4. **Re-acknowledge with a version + date** on every material change.
+
+**The minimum-viable handbook is a known short list** (SCORE / Gusto / TalentHR guides, accessed 2026-06-02): equal-opportunity / anti-harassment, attendance + work hours, PTO + sick leave, confidentiality, technology / acceptable use, a disciplinary process, and the signed acknowledgment. Add **remote/hybrid even if you have no remote staff today** — you will.
+
+Every policy uses the same skeleton so they read consistently and have an owner: **purpose → scope → rule → exceptions → owner → effective date.** A policy with no owner and no date is already stale.
+
+**Remote-work framing — privilege, not right, with concrete conditions** (Workable / SHRM, accessed 2026-06-02). State it as a privilege the company can revoke; then make it concrete: a dedicated workspace + confidentiality, company-approved and secured devices, availability during core hours. Conduct rules must address hybrid-specific issues — e.g. personal messaging apps vs corporate tools.
+
+The Bad→Good that decides whether your handbook becomes an accidental contract:
+
+```text
+Bad:  The Company shall guarantee continued employment and shall follow the
+      three-step disciplinary process below before any termination.
+Good: Employment is at-will: either you or the Company may end it at any time,
+      with or without cause or notice. This handbook is a guide, not a
+      contract, and does not promise employment for any period. Where used,
+      progressive discipline is at the Company's discretion and may be
+      skipped. (See your signed acknowledgment.)
+```
+
+"Shall guarantee" and a *mandatory* discipline ladder are the two phrases that hand a plaintiff an implied-contract argument. Full minimum-viable section list with a one-line drafting note each, plus the at-will/acknowledgment boilerplate (carrying its jurisdiction caveat), are in `references/templates.md`.
+
+## The operating rhythm
+
+The people rhythm is layered, and the **weekly 1:1 is the non-negotiable**. Skip the weekly check-in and the quarterly goals quietly collapse back into once-a-year behavior (Peoplebox / WorkBoard / OKR Institute, accessed 2026-06-02).
+
+| Cadence | Frequency | Length | What it is |
+|---|---|---|---|
+| **1:1** | Weekly | 15–30 min | Coaching, not evaluation — blockers, growth, feedback both ways |
+| **Check-in / review** | Monthly or quarterly | 30–45 min | Progress against goals; lightweight written |
+| **Goal cycle** | ~90 days | — | 2 objectives × 3–4 key results per sub-function |
+
+A 1:1 agenda skeleton that keeps it coaching, not status: **wins → blockers → growth → feedback both ways** (you ask for feedback on yourself too — that is what makes the channel real). Let the report own the agenda; you own showing up.
+
+**Offboarding** is the moment most teams botch. Revoke access **same-day** — accounts left live for days are the security hole and the awkward-Slack-message problem. Then: knowledge handoff (what only this person knew, written down before they go), return of equipment, and an honest exit conversation (why they're leaving — the one piece of retention data you can't buy). Full checklist in `references/templates.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Fix |
+|---|---|---|
+| Day 1 is a paperwork marathon | Burns the one day that should build belonging; ~40% of onboarding time is compliance | Pull forms + access into preboarding; Day 1 is people + first task |
+| Handbook says "shall guarantee" / mandates a fixed discipline ladder | Hands a plaintiff an implied-contract argument; the handbook stops being "not a contract" | At-will + not-a-contract disclaimer, signed acknowledgment, discretionary discipline |
+| No manager named in the onboarding plan | The 3.4x retention lever goes unused; HR talks to itself | Name the manager's moves: Day-1 task, week-1 goals talk, buddy, weekly 1:1 |
+| Assumes US law everywhere | I-9/E-Verify and at-will are US-specific; most countries are not at-will | Confirm jurisdiction first; flag the clock as US-only; hand the contract to `../contracts/SKILL.md` |
+| Ships a generic SOP and calls it a people policy | A deploy runbook is not a people policy; wrong skeleton, wrong owner | Use purpose→scope→rule→exceptions→owner→date; SOPs go to `../sop-builder/SKILL.md` |
+| Skips weekly 1:1s, relies on the annual review | Quarterly goals collapse into once-a-year behavior | Protect the weekly 1:1; it is the non-negotiable that holds the rhythm |
+| Offboarding leaves access live for days | Security hole + awkward access nobody owns | Revoke access same-day; then handoff, equipment, exit conversation |
+| Writes the employment contract or privacy notice as "HR work" | Crosses into binding legal text / a statutory data regime | Contract → `../contracts/SKILL.md`; employee-data privacy → `../gdpr-privacy/SKILL.md` |
+
+## References
+
+- `references/templates.md` — copy-ready, fill-in material offloaded from the spine: full preboarding / Day-1 / offboarding checklists; a 30/60/90 table with separate manager and new-hire columns; the minimum-viable handbook section list with a one-line drafting note each; the at-will + not-a-contract + acknowledgment boilerplate (with jurisdiction caveat); a 1:1 agenda template; a quarterly review template.

package/skills/people-ops/evals/README.md

@@ -0,0 +1,14 @@
+# people-ops evals
+
+Run these through the repo's eval harness, which feeds each prompt to the skill
+router and grades the result with an LLM. `should_trigger` checks that the listed
+prompts route into `people-ops` (including the non-obvious "the offer's signed,
+now what?" and the Spanish "plan de onboarding ... para el nuevo fichaje" cases);
+`should_not_trigger` checks that adjacent requests route to the named real sibling
+instead (`hiring`, `sop-builder`, `contracts`, `gdpr-privacy`) rather than being
+swallowed here. The single `capability` case is graded against its `must_include`
+rubric — the model must produce an onboarding plan plus a remote-work policy that
+keeps paperwork in preboarding, names the manager's moves, carries the
+at-will/not-a-contract disclaimer, flags the US-only I-9 clock, and defers the
+employment contract to `contracts`. There is no `verify.sh`: this is a
+judgment skill, so its rigor lives in this capability eval, not a script.