@1aboveio/skills 0.10.0

package/skills/engineering/harness-runtime/native-question-contracts.md

@@ -0,0 +1,37 @@
+# Native structured question contracts
+
+`planStructuredQuestions(capabilities, questions)` is pure. It selects an adapter only when that tool name is present in the current-turn nativeTools input; harness names, static configuration, installed extensions, and these fixtures never establish availability.
+
+## Pinned schemas
+
+The machine-readable summary is `fixtures/native-question-schemas.json`; native response examples are in `fixtures/question-responses.json`.
+
+| Adapter | Pinned source | Native constraints |
+| --- | --- | --- |
+| Pi `ask_user_question` | `@juicesharp/rpiv-ask-user-question@2.4.0`, `tool/types.ts` and `docs/tool-schema.md` | 1-4 questions, 2-4 options, header <=16 characters, option label <=60 characters, multi-select supported |
+| Codex `request_user_input` | `openai/codex@3d4d253f8f4a812c595cd59e2c114c2c3696c293`, `request_user_input_spec.rs` | 1-3 questions, 2-3 options, header <=12 characters, stable snake-case ids, first recommended option suffixed with `(Recommended)`, no advertised multi-select field |
+| Claude Code `AskUserQuestion` | `anthropics/claude-code@54cc51a08a5d3900e5abd02ad75a2ce46f3f008c`, `interactive-commands.md` | 1-4 questions, 2-4 options, header <=12 characters, multi-select supported |
+
+When more than one supported name is advertised, priority is Pi, Codex, then Claude Code. Input order does not alter selection. Questions and recommended options preserve logical order. Codex treats the first recommendation id as the recommended choice, appends its required ` (Recommended)` label suffix in both the payload and response mapping, and leaves later recommendation ids as ordering hints. Capacity overflow produces consecutive calls and `batching: { required: true, reason: "adapter-capacity", callCount }`.
+
+Before emitting a native call, every adapter validates the final labels after adapter-specific transformation. Each emitted label must identify exactly one neutral option id. A collision raises `invalid-question` with reason `native-option-label-collision`, the adapter, question id, native label, and colliding option ids. This includes a Codex recommendation such as `Queue` colliding with a literal `Queue (Recommended)`. Pi and Claude Code currently preserve option labels unchanged; Pi rejects labels longer than 60 characters rather than truncating them. Pi also reserves the native UI labels `Other`, `Type something.`, and `Next`; a neutral option using any of them fails with `reserved-option-label` before invocation.
+
+Claude Code serializes multi-select answers by joining selected labels with `, `. The planner enumerates that bounded native format and rejects any string that could identify more than one option-id sequence with reason `native-answer-format-collision`. For example, separate `A` and `B` options cannot coexist in a multi-select question with a literal `A, B` option.
+
+## Unsupported features
+
+| Adapter | Multi-select | Secret input |
+| --- | --- | --- |
+| Pi | Native | `UnsupportedQuestionError` |
+| Codex | `UnsupportedQuestionError` | `UnsupportedQuestionError` |
+| Claude Code | Native | `UnsupportedQuestionError` |
+
+Secret input always fails closed because none of the advertised model-call schemas above exposes a secret field. The Codex app-server protocol has a separate `isSecret` transport property, but the advertised `request_user_input` tool input does not; the planner does not emit unadvertised fields.
+
+Without a supported tool, one optionless, non-secret, single-select question returns a `concise-free-text` fallback decision. Textual multiple-choice emulation is forbidden: a logical question with options returns `textual-multiple-choice-forbidden` and no prose-choice payload. Multiple free-text questions, secret input, and multi-select never silently degrade.
+
+## Responses
+
+`normalizeQuestionResponses(plan, responses)` accepts one native response per planned call and returns frozen `{ questionId: answers[] }` data. Recognized native labels, including Codex's emitted recommendation suffix, map back to neutral option ids; unrecognized custom text remains literal. Pi's explicit `custom` answer kind always remains literal, even when its text equals an option label. Codex responses must contain exactly one answer because its advertised input is single-select. Pi multi-select arrays and Claude Code's comma-joined multi-select response normalize to the same option-id array. A malformed plan containing duplicate native labels raises `invalid-answers` with reason `ambiguous-option-label`; normalization never chooses the first matching id.
+
+Pi exposes cancellation in `details.cancelled`. Codex interruption and Claude Code cancellation do not provide a successful answer payload, so callers pass the explicit `{ cancelled: true }` sentinel shown in the fixtures. Cancellation of any native call cancels the whole logical gate and returns `{}`; partial gate answers are not acted on. A non-cancelled native call must answer every question in that call. Unknown or missing ids/prompts, empty answers, invalid option labels, response-count mismatches, and malformed native shapes raise `invalid-answers`.

package/skills/engineering/harness-runtime/references/model-catalog-seed.json

@@ -0,0 +1,159 @@
+{
+  "seededAt": "2026-08-14",
+  "models": [
+    {
+      "canonical": "fable",
+      "family": "anthropic",
+      "ids": { "claude-code": "fable" },
+      "tiers": { "claude-code": { "high": "frontier" } },
+      "note": "claude-fable-5, Mythos-class; current-gen frontier — reviewer material. Seeded from the claude-code catalog only; no codex/pi entry exists at this id."
+    },
+    {
+      "canonical": "opus",
+      "family": "anthropic",
+      "ids": { "claude-code": "opus" },
+      "tiers": { "claude-code": { "high": "balanced-coder" } },
+      "note": "Opus 4.8 — balanced-coder at high. BENCHMARK (rule 6), official DeepSWE v1.1: 51.8%±4.6 at high (113 tasks, board updated 2026-08-13). The measured high point overlaps the 53.8%±2.3 balanced-coder reference from Grok 4.5, so it is not tiered from Opus's separate 59.0%±1.8 max run. Seeded from the claude-code catalog only."
+    },
+    {
+      "canonical": "sonnet",
+      "family": "anthropic",
+      "ids": { "claude-code": "sonnet", "pi": "anthropic/claude-sonnet-5" },
+      "tiers": { "claude-code": { "high": "balanced-coder" } },
+      "note": "Confirmed alias: sonnet (claude-code) = anthropic/claude-sonnet-5. Balanced-coder at high: official DeepSWE v1.1 measured 48.2%±4.5 at high (113 tasks, board updated 2026-08-13), overlapping the balanced-coder reference band. No pi catalog entry exists yet at that id, so no pi tier is seeded here — the alias only lets a future pi discovery of anthropic/claude-sonnet-5 resolve to this canonical entry."
+    },
+    {
+      "canonical": "gpt-5.6-sol",
+      "family": "openai",
+      "ids": { "claude-code": "gpt-5.6-sol", "codex": "gpt-5.6-sol", "pi": "openai/gpt-5.6-sol" },
+      "tiers": {
+        "claude-code": { "high": "frontier" },
+        "codex": { "high": "frontier" },
+        "pi": { "high": "frontier" }
+      },
+      "note": "Agrees across all three harnesses: current-gen frontier at high. BENCHMARK (rule 6), official DeepSWE v1.1: 69.4%±1.4 at high (113 tasks, board updated 2026-08-13). The separate xhigh/max runs are not banked because DeepSWE measured high."
+    },
+    {
+      "canonical": "gpt-5.5",
+      "family": "openai",
+      "ids": { "claude-code": "gpt-5.5", "codex": "gpt-5.5", "pi": "openai/gpt-5.5" },
+      "tiers": {
+        "claude-code": { "high": "deep-reasoner" },
+        "codex": { "high": "deep-reasoner" },
+        "pi": { "high": "deep-reasoner" }
+      },
+      "note": "Agrees across all three harnesses: deep-reasoner at high. BENCHMARK (rule 6), official DeepSWE v1.1: 64.4%±3.1 at high (113 tasks, board updated 2026-08-13). The separate xhigh point is not banked because DeepSWE measured high."
+    },
+    {
+      "canonical": "gpt-5.6-terra",
+      "family": "openai",
+      "ids": { "claude-code": "gpt-5.6-terra", "codex": "gpt-5.6-terra", "pi": "openai/gpt-5.6-terra" },
+      "tiers": {
+        "claude-code": { "high": "balanced-coder" },
+        "codex": { "high": "balanced-coder" },
+        "pi": { "high": "balanced-coder" }
+      },
+      "note": "Agrees across all three harnesses: balanced-coder at high. BENCHMARK (rule 6), official DeepSWE v1.1: 53.8%±4.3 at high (113 tasks, board updated 2026-08-13). Its separate xhigh/max runs are not banked because DeepSWE measured high. Codex and pi previously held a max point (deep-reasoner); it was dropped 2026-07-20 in all three catalogs when the team standardized on effort=high, and this seed followed."
+    },
+    {
+      "canonical": "gpt-5.6-luna",
+      "family": "openai",
+      "ids": { "claude-code": "gpt-5.6-luna", "codex": "gpt-5.6-luna", "pi": "openai/gpt-5.6-luna" },
+      "tiers": {
+        "claude-code": { "high": "scoped-coder" },
+        "codex": { "high": "scoped-coder" },
+        "pi": { "high": "scoped-coder" }
+      },
+      "note": "Agrees across all three harnesses: scoped-coder at high. BENCHMARK (rule 6), official DeepSWE v1.1: 44.2%±2.9 at high (113 tasks, board updated 2026-08-13). Its xhigh/max runs are not banked because DeepSWE measured high; a more expensive point that reaches another band is not a default operating point."
+    },
+    {
+      "canonical": "grok-4.5",
+      "family": "xai",
+      "ids": { "claude-code": "grok-4.5", "pi": "xai/grok-4.5" },
+      "tiers": {
+        "claude-code": { "high": "balanced-coder" },
+        "pi": { "high": "balanced-coder" }
+      },
+      "note": "Balanced-coder in both harnesses at high. BENCHMARK (rule 6), official DeepSWE v1.1: 53.8%±2.3 at high (113 tasks, board updated 2026-08-13). Was seeded deep-reasoner under pi; demoted 2026-07-22 on human re-classification — the two harnesses agree, so this is no longer a harness-dependent entry. Not yet confirmed available in claude-code's own discovery (rule 3 applies regardless of this seed entry). Sibling grok-4.6 is a separate entry and does not re-tier 4.5."
+    },
+    {
+      "canonical": "grok-4.6",
+      "family": "xai",
+      "ids": { "claude-code": "grok-4.6", "pi": "xai/grok-4.6" },
+      "tiers": {
+        "claude-code": { "high": "deep-reasoner" },
+        "pi": { "high": "deep-reasoner" }
+      },
+      "note": "Agrees across both harnesses it is seeded from: deep-reasoner at high. BENCHMARK (rule 6), official DeepSWE v1.1: 65.2%±1.5 at high (113 tasks, board updated 2026-08-13). It overlaps gpt-5.5's 64.4%±3.1 high point (deep-reasoner) and is clearly above Grok 4.5's 53.8%±2.3 high point (balanced-coder); the shared deep-reasoner band is the claim, not that it beats gpt-5.5. Its separate xhigh point is not banked because DeepSWE measured high. Codex holds no Grok entry. Availability is still per-harness discovery (rule 3)."
+    },
+    {
+      "canonical": "mimo-v2.5-pro",
+      "family": "xiaomi",
+      "ids": { "claude-code": "mimo-v2.5-pro", "pi": "xiaomi/mimo-v2.5-pro" },
+      "tiers": {
+        "claude-code": { "high": "scoped-coder" },
+        "pi": { "high": "scoped-coder" }
+      },
+      "note": "Agrees across both harnesses it is seeded from: scoped-coder at high. Downgraded under pi from balanced-coder on 2026-08-02 by maintainer instruction, which ended a recorded harness disagreement — it had been the worked example of one (scoped-coder under claude-code, balanced-coder under pi: a mid-size model's ability to hold a long agentic trajectory being a property of the harness loop as much as the weights). That example is now historical; kimi-k2.7-code now agrees across both harnesses too. Not benchmark-backed (rule 6): no published point at high for this model, so both bands are human judgment. As scoped-coder in every harness it carries, this model is now slot-ineligible everywhere — recorded deliberately so it stops being re-asked, not hidden; promotion is a normal re-confirmation if it earns one."
+    },
+    {
+      "canonical": "deepseek-v4-pro",
+      "family": "deepseek",
+      "ids": { "claude-code": "deepseek-v4-pro", "pi": "deepseek/deepseek-v4-pro" },
+      "tiers": {
+        "claude-code": { "max": "deep-reasoner" },
+        "pi": { "max": "deep-reasoner" }
+      },
+      "note": "Agrees across both harnesses it is seeded from: deep-reasoner at max. CHANGED 2026-08-13: 0813 GA replaced the 2026-08-01 preview classification (claude-code high:scoped-coder, pi high:balanced-coder — that disagreement is now historical). BENCHMARK (rule 6), vendor-reported DeepSWE v1.1 62.7 — DeepSeek V4 Pro 0813 Agent comparison table, 2026-08-12/13. BenchLM cites the same 62.7 as DeepSeek V4 Pro (Max); no CI, and DeepSeek did not publish a high-effort DeepSWE number for 0813. Banked at MAX because that is the only published operating point, so it is the model's pushed point, not a throttled seat (same posture as kimi-k3). Do NOT read 62.7 down onto high — measured max\u2192high drops on this board have run 1 to 23 points, and a high point is unclaimed until someone measures it. Like-for-like against the official board's max/xhigh cluster: luna@max 67\u00b14 (balanced-coder at max after the 2026-08-08 reband), gpt-5.5@xhigh 67\u00b16 (deep-reasoner), opus-4.8@max 59\u00b12 (deep-reasoner). 62.7 sits with that deep-reasoner band and above flash's official max 53\u00b14 / vendor 54.4, so the name ordering now tracks the evidence (flash is now also banked at max: 53%\u00b14 official / 54.4 vendor, balanced-coder). Not on the official DeepSWE v1.1 board (last updated 2026-08-07, 21 models) — vendor number, not an independent Datacurve run. No high point is claimed; do not restore the preview high bands from this score."
+    },
+    {
+      "canonical": "deepseek-v4-flash",
+      "family": "deepseek",
+      "ids": { "claude-code": "deepseek-v4-flash", "codex": "deepseek-v4-flash", "pi": "deepseek/deepseek-v4-flash" },
+      "tiers": {
+        "claude-code": { "max": "balanced-coder" },
+        "codex": { "max": "balanced-coder" },
+        "pi": { "max": "balanced-coder" }
+      },
+      "note": "Agrees across all three harnesses: balanced-coder at max. CHANGED 2026-08-13: the 2026-08-01 high:balanced-coder point was a mis-cited effort — DeepSWE v1.1 lists this model as deepseek-v4-flash [max] 53%\u00b14 ($0.10, 108k out, 153 steps; board updated 2026-08-07), and DeepSeek's own 54.4 is the same max-effort run (V4-Flash-0731, DeepSeek Harness minimal, reasoning_effort=max). There is no published high-effort DeepSWE number, so high is unclaimed (rule 6: do not read a max score down to high). Like-for-like against the official max/xhigh cluster: grok-4.5 is 54%\u00b12 at HIGH, not a peer at this effort; luna@max 67\u00b14 is also balanced-coder at max after the 2026-08-08 reband; muse-spark-1.1@xhigh 53\u00b13 sits on the same score. Sibling deepseek-v4-pro is deep-reasoner @max off vendor 62.7 — same effort, name ordering now tracks the evidence. The 55.4 figure previously cited as @high was the vendor max point, not a high measurement."
+    },
+    {
+      "canonical": "kimi-k2.7-code",
+      "family": "moonshot",
+      "ids": { "claude-code": "kimi-k2.7-code", "pi": "kimi-coding/kimi-for-coding" },
+      "tiers": {
+        "claude-code": { "high": "scoped-coder" },
+        "pi": { "high": "scoped-coder" }
+      },
+      "note": "Agrees across Claude Code and Pi: scoped-coder at high."
+    },
+    {
+      "canonical": "gemini-3.5-flash",
+      "family": "google",
+      "ids": { "claude-code": "gemini-3.5-flash" },
+      "tiers": { "claude-code": { "high": "scoped-coder" } },
+      "note": "Seeded from the claude-code catalog only; no confirmed high-effort point exists (the only benchmark observation was at medium)."
+    },
+    {
+      "canonical": "kimi-k3",
+      "family": "moonshot",
+      "ids": { "claude-code": "kimi-k3" },
+      "tiers": { "claude-code": { "max": "frontier" } },
+      "note": "Seeded from the claude-code catalog only. Pi's catalog separately holds `kimi-coding/k3` (deep-reasoner @high) — plausibly the same underlying model, but the id does not plainly normalize (stripping the `kimi-coding/` prefix gives `k3`, not `kimi-k3`) and no human confirmed the pair, so the two stay as separate seed entries rather than a guessed alias. Flagged for human confirmation, not merged."
+    },
+    {
+      "canonical": "kimi-coding/kimi-for-coding-highspeed",
+      "family": "moonshot",
+      "ids": { "pi": "kimi-coding/kimi-for-coding-highspeed" },
+      "tiers": { "pi": { "high": "balanced-coder" } },
+      "note": "Seeded from the pi catalog only."
+    },
+    {
+      "canonical": "kimi-coding/k3",
+      "family": "moonshot",
+      "ids": { "pi": "kimi-coding/k3" },
+      "tiers": { "pi": { "high": "deep-reasoner" } },
+      "note": "Seeded from the pi catalog only. See `kimi-k3`'s note — not merged with claude-code's `kimi-k3` pending human confirmation of the alias."
+    }
+  ]
+}

package/skills/engineering/harness-runtime/references/model-catalog.md

@@ -0,0 +1,57 @@
+# Model catalog (skill-owned baseline, per-harness overrides)
+
+Resolve Issues pre-flight step 2 must classify every discovered model (family · tier) before it can recommend a pick for each slot. The installed `harness-runtime` package provides the shared catalog baseline at `references/model-catalog-seed.json`; the per-harness JSON files below hold only **explicit, human-confirmed overrides**. A skill install or update replaces the shipped baseline, so its newer classifications apply on the next pre-flight wherever no local override exists. It never copies that baseline into a user file or silently changes an override. As the [Resolve Issues pre-flight contract](../../resolve-issues/references/pre-flight.md) states, training-data knowledge is not a discovery source, and neither is this file's *absence* of a model.
+
+**Read and write through [`model-catalog.mjs`](../model-catalog.mjs)** rather than hand-editing the JSON — it single-sources the prune predicate and the write paths. Run `model-catalog.mjs help`; the script is the source of truth for the precedence composition, the write-guards, and the shapes. At pre-flight step 2 **prefer `tiers --seen <ids>`**: it composes all three evidence arms (banked → cross-harness → team seed) with the precedence applied *inside* the command. A precedence or filtering rule stated only in prose is applied by an agent mid-gate from memory, and the failure is silent — exactly how rules 5 and 7 went wrong before 2026-07-20.
+
+## Location — skill baseline plus one override catalog per harness
+
+The skill-owned baseline resolves relative to the installed runtime, so the native Skills CLI refreshes it along with the rest of `harness-runtime`: `~/.agents/skills/harness-runtime/references/model-catalog-seed.json` in the supported global installation. A local override catalog belongs to one harness, at that harness's own user-config location: **Claude Code** `~/.claude/model-catalog.json`, **Codex** `~/.codex/model-catalog.json`, **Pi** `~/.pi/agent/model-catalog.json`, another harness its user-config dir (via `--file`).
+
+**Never merge harnesses into one override file.** The same model carries a different id per harness (`sonnet` in Claude Code is `anthropic/claude-sonnet-5` in Pi) — a shared file conflates id namespaces and lets staleness pruning judge entries a run's discovery was never going to see. Per-harness files make every `id` unambiguous and pruning naturally scoped to the harness actually looking. `--harness` guards writes against the file's own `harness` stamp — a sync or bank aimed at a file stamped for a different harness is refused, not merged. Absence is normal and desirable: with no override, the installed skill baseline supplies the classification; a discovered model absent from both falls through to discovery-source evidence.
+
+## Schema — the fields that carry judgment
+
+The script validates the shape; what follows is the *why* behind the load-bearing fields (see the header comment / `model-catalog.mjs --help` for the full field list).
+
+- `tiers` — **the entry's capability: a map from effort to the tier the model reaches there.** Bands, top to bottom:
+  - **`frontier`** — the current top end; home role: reviewer.
+  - **`deep-reasoner`** — a **capability band, not a chronology**: a deep reasoner below the current top end (a previous generation's frontier is the typical member, but a newly released model that lands in the band belongs here too). The implementer to recommend for a risk-heavy/complex run.
+  - **`balanced-coder`** — fast, capable, non-specialist; deep enough for routine work, not the hardest. The implementer to recommend for a routine run.
+  - **`scoped-coder`** — **executes a change someone else scoped; does not hold a task together across a long agentic trajectory.** It has **no home role and is never proposed for a slot** — that is what it is for. Banking a model as `scoped-coder` records the answer once and keeps a below-floor model out of every slot's candidate list, so it stops getting tagged `unconfirmed — please classify` every run. The exclusion is mechanized (`slotEligible`, wired to `SLOT_ELIGIBLE_TIERS`). **Marked, never filtered** — the classification is a real, useful answer, so what must not happen is it *reaching a slot list*, not the model being hidden. (Until 2026-07-20 `SLOT_ELIGIBLE_TIERS` was a constant nothing read, so the shipped seed handed a fresh install its five scoped-coder entries as team-endorsed slot options. Five is the count at that commit, verified against the file's history, and it is written as history on purpose: the live count moves whenever an entry is re-banded — it has already changed twice since — so quoting today's number here just plants the next stale fact. Count the current seed if you need the current count.) Promotion is a normal re-confirmation if the model later earns it — the band is a classification, not a blacklist.
+
+  A model with **two useful operating points** banks both, and pre-flight offers each as its own slot candidate (`example-coder-2 @ high (balanced-coder)` · `example-coder-2 @ max (deep-reasoner)`) — so one model can be the routine implementer *and*, pushed, the deep reasoner. **The two-point examples in this file and in the [Resolve Issues pre-flight contract](../../resolve-issues/references/pre-flight.md) use a deliberately fictional id.** They named a real model until 2026-07-20, when that model's second point was dropped in every catalog and the docs kept illustrating a two-point entry with a model that no longer had one — an example naming a real model goes stale every time that model is reclassified, and a reader checking their own catalog against it finds a contradiction and can't tell which side is wrong. Efforts are `high | xhigh | max`; **`high` is the floor**, because a point records what a model *reaches when pushed*, never a throttled-down cheap seat — a cheaper operating point is a cheaper **model** (pre-flight step 2). An effort with no banked point is **not claimed**: `tierAt` returns null rather than guessing.
+
+  This is `tier = f(model, effort)` — the shape removed on 2026-07-13, restored on **2026-07-19** with the cost that killed it removed. That removal was right about the *per-slot, per-run* effort question, which bought a confirmation per slot for no benefit; it stays gone. Points are banked **once, at classification**, so pre-flight reads them instead of asking.
+
+**Renamed / reshaped 2026-07-19 — every tier name now describes what a model *is*:** `prior-frontier` → `deep-reasoner` (the old name encoded a *chronology*) and `mid-tier` → `balanced-coder` (encoded an *ordinal position*, and an inaccurate one — with three bands it is the bottom, not the middle); the single-point `tier` (+ optional `effort`) fields became the `tiers` map. All three legacy forms are **accepted, not rejected**: `bank` normalizes them and the `sync` at every pre-flight read migrates entries in place and reports them, so an older catalog heals itself on first use.
+
+## Skill-owned baseline (`references/model-catalog-seed.json`) — read-only, ships with the skill
+
+The three local catalogs above are **override-level** — a teammate installing the skill fresh starts every one empty and immediately reads the skill-owned baseline. The baseline carries the team's accumulated judgment in one file, checked in beside `model-catalog.mjs` under `references/` (not a user-config location — there is exactly one baseline shared by every harness, unlike the per-harness override catalogs). Its fields mirror the per-user schema with two differences that carry judgment:
+
+- `ids` — the map from harness name to **that harness's own id for this model**, resolved once by a human at authoring time (never by live normalization at read time). **Do not add an id pairing beyond what plain `provider/`-prefix normalization gives or what a human has explicitly confirmed** — a wrong alias produces a confident bad slot pick, worse than no pre-fill; when unsure, ship the model as separate per-harness entries instead of guessing a pairing (the seed's `kimi-k3` / `kimi-coding/k3` entries are the worked example: same provider, plausibly the same model, kept separate because the id doesn't plainly normalize and no human confirmed it).
+- `tiers` — **per-harness**, never collapsed to one value: a model's tier is a function of the harness loop as much as the weights (a mid-size model can hold a long agentic trajectory in one harness's loop and not another's), so an entry that disagrees across harnesses states each harness's tier honestly. Of the models this repo seeded from, 0 shared across the three catalogs genuinely disagree per harness (count the seed if you need today's number — models leave this set as they are re-banded). `deepseek-v4-pro` was the last one (claude-code high:scoped-coder vs pi high:balanced-coder) and left on 2026-08-13 when 0813 GA collapsed it to an agreeing max:deep-reasoner point; each entry records what it replaced and is pinned in the seed test, so a drift back has to be deliberate. Collapsing that would silently overrule a real, harness-specific measurement.
+
+`seededAt` is checked-in data and will age; pre-flight surfaces `team seed is N days old` once `seededAt` is more than **~90 days** old as a nudge to an owner, not a hard gate — a stale entry only ever costs the human a correction, never a silent wrong pick, because the seed only ever pre-fills a *proposal*. (No script computes seed age — pre-flight reads `seededAt` and applies the nudge; this is the concrete home for that ~90-day threshold.)
+
+## Lifecycle rules
+
+1. **Read at pre-flight step 2, before classifying.** A discovered model with a catalog entry keeps its banked `family`/`tiers` — pre-fill the proposal from it, don't re-ask. One exception is surfaced, not silent: a `frontier` entry whose provider has since shipped a newer top-line model (that discovery also yielded) may have aged into `deep-reasoner` — propose the demotion for confirmation. Everything else falls through to discovery-source evidence, and failing that `unconfirmed — please classify`.
+2. **Bank at confirmation (pre-flight step 4).** The human's confirmation is the only thing that writes a *classification* (`family`/`tiers`/`note`) — never bank a machine guess. A banked point above `high` in particular is a claim the human has *seen* the model reach that tier when pushed; absent that, bank only `high`. The two maintenance writes rule 4 makes at read time record observation, not judgment, and are the only machine writes allowed.
+3. **Never an availability source.** A cataloged model this run's discovery did not yield is **not proposable** (pre-flight step 1's rule stands). The catalog answers "what is this model," never "what models exist here."
+4. **Auto-prune by staleness, not by single absence.** `sync` deletes every entry unseen for more than 60 days (never silently). One missed run doesn't prune (quota, region, temporary removal); more than 60 days unseen means the model left this user's runtime, and a pruned model that later resurfaces just gets re-classified — one question, the price of a self-cleaning catalog.
+   - **Prune watches `lastSeenAt`; classification-staleness watches `confirmedAt` — two axes, not one.** A model discovered every day never prunes, yet its *tier* can be frozen for weeks: grok-4.5 stayed `deep-reasoner` (confirmed 2026-07-19) long after the seed demoted it to `balanced-coder`, because `lastSeenAt` kept bumping and nothing watched the age of the *judgment*. `tiers --seen` flags any discovered entry whose `confirmedAt` is older than `CLASSIFY_STALE_AFTER_DAYS` (30) as `staleClassifications` — **surfaced for re-confirmation, never auto-changed** (unlike prune, which acts). Staleness of judgment is a nudge; staleness of observation is a delete.
+5. **Another harness's catalog is tiering *evidence*, never more.** When a model is new to *this* harness's catalog, an entry in another catalog whose id **plainly matches** after normalizing the `provider/` prefix (`openai/gpt-5.6-sol` ↔ `gpt-5.6-sol`) supplies its banked `family`/`tiers` as the pre-fill, cited as such — the human still confirms this run, and the confirmation banks into *this* harness's file. Plainly means mechanically: harness-local aliases (`sonnet`) don't normalize and get no cross-harness pre-fill. One thing never transfers: **availability** (rule 3 applies doubly).
+6. **A public benchmark is tiering evidence, never availability — and only at a matching operating point.** A leaderboard (SWE-bench, DeepSWE, …) is discovery-source evidence for `tiers`, the same class as provider docs or pricing under rule 1: it pre-fills a proposal, the human still confirms, and it never says the model is runnable here. Two rules keep it usable:
+   - **Compare like-for-like points.** A leaderboard's headline column is usually each model's *best* effort, while the catalog banks `high`. They are not interchangeable: measured max→high drops have run **1 to 23 points** across models in a single benchmark version, so a max score implies almost nothing about the high point, and a model whose only published number is below `high` cannot be tiered from it at all. Band a point against peers *at the same effort*, or not at all.
+   - **Default to `high` when DeepSWE measured it.** The skill-owned baseline banks the `high` point alone when the board has one; a better `xhigh` or `max` result does not add a second default candidate. When the board has no `high` run, bank the published `xhigh` or `max` point as the model's only measured operating point, and say why in its note. This keeps an effort choice from silently becoming a score-chasing policy while preserving an evidence-backed option for models without a `high` run.
+   - **Cite the source and version in the `note`** (`DeepSWE v1.1 @high 54%±2`), and say plainly when a classification is *not* benchmark-backed. Confidence intervals are part of the evidence, not decoration — where they overlap, the benchmark is not separating those models, and banding on the point estimate is fitting noise.
+7. **The skill-owned baseline is the shared default, never an availability source and never a silent override write — the load-bearing invariant.** When a discovered model has no banked entry (rule 1) and no cross-harness hit (rule 5), `seed-proposals --seen <ids>` supplies its per-harness `tiers` as the pre-fill, cited as such. The human may explicitly confirm a local override, which banks a normal entry (fresh `confirmedAt`) into the human's *own* per-harness file; the baseline itself never accumulates. Four things must hold:
+   - **Rule 3 applies to the seed, and this is the one that fails *open* if missed:** a model the seed carries but this run's discovery did not yield stays unproposable — `seed-proposals` mechanizes this by taking the discovered-id set as an argument and silently excluding everything outside it, never trusting a caller to filter afterward.
+   - **Read-only.** `bank` and `sync` refuse the seed file as a write target (by path and by shape — anything carrying `seededAt` is refused wherever it sits), and rule 4's staleness pruning does **not** apply: the seed records judgment, not observation.
+   - **Precedence, full order:** own banked entry → own other-harness catalog → **team seed** → discovery-source evidence (rule 6's benchmarks) → `unconfirmed — please classify`. A user's own measurement always beats the shipped default, and `seed-proposals` **enforces the order itself** rather than trusting a caller to apply it — a precedence rule a caller applies by hand is a rule that silently stops holding.
+   - **A banked entry outranks the seed per *model*, never per *effort*.** A banked entry is a **complete statement** of that model's operating points in this harness, so a model with any banked point takes no seed pre-fill at all. A per-effort merge would read a human's *deliberate deletion* of a point (banking `example-coder-2` at `{high}` after deciding its `max` point wasn't real) as *silence* and hand the point back from the seed forever. Deletion has to be expressible; per-model suppression makes it stick. `resolveModelTiers` takes whole `tiers` maps for exactly this reason — its predecessor took one scalar tier per source, so the per-model rule survived only as a comment telling callers not to merge point-by-point, and a signature that invites the bug its comment forbids is a trap.
+
+   `seed-proposals` returns `{proposals, suppressed}`; `suppressed` names each model the catalog outranked, flagging `disagrees: true` where the seed differs from what the human banked. Surface a disagreement as a **nudge to a seed owner** — never a proposal, never a reason to re-ask a settled classification. This is the only place seed staleness becomes visible (the seed can't be diffed against user-level catalogs in CI, since those live outside the repo); what CI *does* hold is the seed's internal shape.
+   - **A disagreement is date-aware — which side is stale depends on which is newer.** The default nudge ("your catalog wins; refresh the seed if yours is the better answer") assumes the *seed* went stale relative to the user's measurement. That is backwards when the seed is the fresher answer: `suppressed` also carries `seededAt`, `bankedConfirmedAt`, and `seedNewer` (`disagrees && seededAt > bankedConfirmedAt`). When `seedNewer` is set, the citation flips to **RE-CONFIRM** — the seed may carry a reclassification the banked entry predates, exactly the grok-4.5 case (seed demoted 2026-07-22, banked confirmed 2026-07-19). This changes the *signal*, not the *resolution*: the banked entry still wins the tier (rule 7 precedence, and the human is the only thing that re-banks) — it just stops the loop from silently trusting a classification the seed already superseded.

package/skills/engineering/implement-and-pr/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/engineering/implement-and-pr/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: implement-and-pr
+description: "Implement a GitHub issue, PRD, design doc, or approved plan and open the pull request — the single produce step: TDD for criteria-backed work, tests from criteria, evidence, and a Review Contract on the PR. NOT the full issue-to-merge-ready loop (resolve-issues)."
+dependencies:
+  - ensure-coverage
+  - tdd
+  - e2e-test
+---
+
+# Implement and PR
+
+Use this skill to turn an approved source work item into a tested pull request with clear review evidence.
+
+## Related Skills
+
+This is the *produce* step in the PR chain; it consumes the skills below by name rather than re-deriving their doctrine:
+
+- `resolve-issues` — the **orchestrator** that owns the issue→merge-ready loop and calls this skill as its implement step; reach for this skill directly only for a one-off "implement and open a PR, no review loop" request.
+- `ensure-coverage` — coverage doctrine you implement against: its create-mode criteria are your input (approved **first/upstream**), its `coverage-ledger.mjs` gate is your self-check; source of truth for required levels, the Surface Baseline Contract, and mock/depth rules.
+- `tdd` — the red-green-refactor loop used in TDD Mode.
+- `e2e-test` — Playwright structure + route coverage for browser/journey tests; its render-health tier + presentation sweep is step 6's per-surface render check (distinct from the curated golden-path `smoke` gate step 6 runs when a critical journey is touched).
+- `review-pr` — the **downstream** verify step that consumes this PR and its Review Contract.
+
+## Required Inputs
+
+- Source work item: GitHub issue, Linear issue, PRD, design document, bug brief, technical spec, or approved implementation plan.
+- Test criteria: `/docs/tests/YYYY-MM-DD-<feature-slug>-criteria.md` for non-trivial code changes, or the repository’s current approved test criteria path.
+- Repository context: branch policy, test commands, CI requirements, and PR target branch.
+
+If the source work item is ambiguous, stop and ask for clarification. Do not invent requirements.
+
+If non-trivial implementation lacks test criteria, stop and request them. Test criteria are `ensure-coverage` (create mode) output, approved **before** TDD begins — this skill consumes and proves them, it does not self-author them (they need human sign-off). Only skip for clearly trivial work, marked `Test Criteria: Not required` with a reason in the Review Contract.
+
+**If the work needs a design and none exists, stop and request it.** Two questions, not a checklist: **(1) would two reasonable implementers, given only this source, build materially different things?** **(2) does correctness depend on what must never happen — orderings, failures, retries, partial states — beyond what the ACs state?** Either yes → the unit owes a human-approved **design input**, and the redirect is `/grill-with-docs` where installed. Don't invent it mid-implementation; build against the resulting doc so the reviewer verifies against it instead of reverse-engineering it one finding at a time. Skip freely when the source already pins the decisions — most routine units — because a design demanded for a CRUD tweak is ceremony, not rigor.
+
+**And when a design source DOES exist, consume it — never summarize it.** The rule above covers a *missing* design; this covers the more common failure, a design that is present, cited, and still not built. A cited prototype / mockup / design doc is read **at the source**, rendered, and the deliverable proven against it — not translated once into prose that every downstream artifact then descends from. The moment a summary becomes the spec, whatever the summary dropped is unfindable: nothing later re-reads the source, so the only remaining detector is the user, one correction at a time. For a unit citing a design source: pin it at a commit, write the parity manifest from it (`design-parity.mjs scaffold`, under `ensure-coverage`'s own directory — resolve it the way that skill's "Resolving these scripts" rule says, never against your CWD; its catalog carries the properties a hand-written list forgets), render **source and deliverable side by side** at the floor viewports before requesting review, and carry `design-parity.mjs validate --observed` in the evidence. A presentation-only unit may **not** list visual/parity evidence as a criteria non-goal — that declares out of scope the one axis the unit is entirely about. Doctrine + the named incident: [ensure-coverage → presentation/axis.md](../ensure-coverage/references/presentation/axis.md) → `presentation:fidelity`.
+
+*Under `resolve-issues` this gate has already run at intake, and the elaboration that used to sit here lives there* ([its design gate](../resolve-issues/references/intake.md#intake--scheduling)) *— it is the only party that can stop and ask a human, since a leaf spawn cannot. The two questions stay here because this skill is also used standalone, where nothing upstream asks them.*
+
+## Core Rule
+
+Implement according to the source work item. Test according to the test criteria. Use TDD mode for PRD/spec/test-criteria-backed work unless explicitly exempted. The PR is not ready for review until it includes tests, evidence, CI status, and a complete Review Contract.
+
+Lifecycle: `ensure-coverage` (create) defines obligations **first** → this skill proves them → `review-pr` runs the `ensure-coverage` audit/breadth gate **last**. This skill sits in the middle — it consumes the create-mode criteria and runs the audit gate as a self-check; the authoritative first/last steps belong to the other two.
+
+### Fix rounds
+
+**Trigger: this PR fixes a review finding.** Two rules; method for both: [references/contract-complete-fix-rounds.md](references/contract-complete-fix-rounds.md).
+
+**Every fix round — keep the edit narrow, but not the verification.** A fix round is scoped so it can't regress settled work; that scoping governs the *edit*, not what you re-run. The finding named one cell of a space (a validation point, a rendered state, a contract branch) — re-run **every cell of that space**, plus any cell the edit itself could have moved through something shared. Reporting "focused tests pass" reports the finding's own cell as if it were the space, and is how one fix lands while its neighbor surfaces next round (skyee-ai-risk #1148: four passes over one component's interaction surface, four scope splits, 43 hours). The neighborhood is the surface's own space, not the repo — an isolated helper with one caller has a neighborhood of one cell.
+
+**High-risk state-machine/concurrency findings, additionally.** The fix round is a contract artifact, not a counterexample patch — a single counterexample test never closes the theme.
+
+## Model
+
+This step writes the diff, so run it on a **high-capability coding model**, stated by **tier and role, never a hardcoded name** (names go stale). **Default — proceed, don't ask:** use the session's current model if it's a strong coder; never silently downgrade to save cost; **record the model used in the Review Contract's `Implementation Model` line** (template — a durable, greppable record, not loose prose; under resolve-issues a contract missing it bounces at the pre-spawn check); pause only if no capable coder is available. **Under `resolve-issues`:** use the `implementationModel` confirmed at pre-flight — possibly a *deliberate* balanced-coder pick made with the risk evidence — and don't second-guess it in either direction: no self-upgrade "to be safe," no cost downgrade. The implementer ≠ reviewer rule is `resolve-issues`' concern; this skill only produces the PR.
+
+## Coverage Obligations (defer to ensure-coverage)
+
+The acceptance criteria you were handed are not the whole obligation. Coverage doctrine — the Ledger, the Surface Baseline Contract, depth classifications, boundary/mock rules — lives in `ensure-coverage`; apply it, don't re-derive it. The point that bites coding agents: **every surface you add or change carries an auto-applied baseline test obligation, even when no AC or ADR mentions it.** When your change touches surfaces (routes, API endpoints, write forms, DB tables, events, jobs):
+
+- Regenerate the surface inventory (the repo's inventory adapter) so a new surface is discoverable.
+- Tag every test `// @covers <surface-id>` and `// @level <level>`; add/update the per-requirement `*.coverage.yml` only to deviate from the auto-baseline.
+- Run `coverage-ledger.mjs validate` locally (or the repo wrapper) and record the result in the Obligation Impact block.
+- A self-declared `@level` lands at a blocking `Unverified` until a reviewer attests — attach execution evidence (CI, traces) that lets them promote it.
+- Never satisfy a browser journey with first-party interception (`page.route`/`route.fulfill`/MSW) — that is `Over-mocked`; a write form owes the rendered-form mutation journey (boundary rules: ensure-coverage's Depth section).
+
+## Workflow
+
+1. Collect context: source work item, linked docs/comments, approved test criteria, existing implementation, branch policy, and test/CI commands.
+2. Decide TDD mode: apply it for PRD/spec/test-criteria-backed work unless a valid exception exists.
+3. **Derive coverage obligations (the BEFORE handoff — consult `ensure-coverage`).** Read the approved criteria, then for every surface this change will add or touch (route, API, write form, table, event, job) compute its baseline obligation and required level — a new surface owes coverage even when no AC names it. Do this before you start implementing, so the obligations shape the slices. See Coverage Obligations.
+4. Map work to ACs and obligations: one slice per AC **and per changed-surface obligation**; identify test levels, mock/fake policy, code areas, and evidence needed. **Write this map down before implementing and keep it current** — see [Incremental plan](#incremental-plan-the-work-list-outlives-the-run).
+5. Implement in the right loop: TDD vertical slices when TDD mode applies; otherwise minimal scoped implementation plus required tests. Tag tests `@covers`/`@level`.
+6. **Close out — verify, smoke-validate, gate, and open the PR.** The full sequence, once, at handoff: [references/closeout.md](references/closeout.md). A fix round runs a subset of it.
+
+   Four are load-bearing enough to state here, because skipping any one buys a review round rather than a review:
+
+   *The gate scripts named below live under their **owning** skill, not this one — `scope-class.mjs` / `coverage-checklist.mjs` under `ensure-coverage/scripts/`, `scan-diff.mjs` under `review-pr/scripts/`, each beside the `SKILL.md` you read it from. Invoke each at that absolute path, not a CWD-relative `scripts/…` (your working directory is the target repo); never locate one with `find` over `$HOME` / `/Users`.*
+
+   - **Run the surface.** Green tests are not a booting app; a route that 500s on first load passes every unit test it has.
+   - **Resolve over-mock before review, never ship it.** It is static and decidable, so a reviewer finding it is a round nobody needed to spend.
+   - **Classify the scope class first** (`scope-class.mjs classify` over the net diff) — it decides whether the checklist/ledger/sweep artifacts apply at all, and a `no-surface` unit owes its matched class's **oracle** instead. Deny-by-default; it changes no review-depth obligation.
+   - **Generate + validate the Coverage Checklist** (`coverage-checklist.mjs generate`, then `validate <checklist.md> --diff <merge-base>`) — no row prose-only or `TODO`. **The `--diff` is not optional garnish:** it exempts the paths this PR deletes, and it is what turns a missing cited file from a warning into a decision — without the diff a deletion you made and a locator left behind by a rebase look identical, so the check declines to block on a guess. Two rows it now rejects, both of which used to reach the reviewer as an evidence finding: a `gate-lint` row citing the gate's *command* with no *result* (the generated skeleton with `PASS` typed over it), and a `file:line` that does not resolve. *(Inapplicable on a recorded `no-surface` unit — see above.)*
+   - **Attach the reviewer-parity proof**: `scan-diff.mjs` findings-channel output (empty) + `coverage-checklist.mjs validate` (passing). The screens run every round; pasting the proof against the final HEAD is the terminal-round part.
+
+## Incremental plan: the work list outlives the run
+
+**Every unit writes the plan** (workflow step 4) — the trigger below is for the *detail*, not the obligation. Read it for a multi-slice unit, or when resuming a spawn that died mid-flight. The artifact's shape and update discipline: [references/incremental-plan.md](references/incremental-plan.md).
+
+Three rules stay here because a replacement spawn depends on them: **write the plan before the first slice**, **update it as each slice lands** (a plan refreshed only at the end is a plan that never survived anything), and **point a replacement spawn at the same path** so it resumes instead of restarting — a partial artifact is worth more than a clean slate, and is never itself proof.
+
+## TDD Mode
+
+**Trigger: a PRD, design doc, feature spec, bug brief or approved test criteria — or the user asked for test-first work.** A bug brief carries no AC bullets and still owes its repro test first, which is the case a narrower trigger routes around. The red-green loop, its evidence, and the characterization-test path: [references/tdd-mode.md](references/tdd-mode.md).
+
+The rule that does not move: **write the failing test first and show it failing.** A test written after the code it tests is a test shaped by the code — it passes because it was fitted, not because the behaviour is right, and no later reviewer can tell the difference from the diff.
+
+## Self-Review Before Handoff (adversarial pass)
+
+**Run the pass on a high-risk diff.** What it hunts is the *depth* — the hazard-catalogue hunt against auth/authz/token/session, money/tax/pricing, tenancy/org-scope, DB migration/schema — and the *mandatory* Self-Review block. Method and the hazard catalogue: [references/self-review.md](references/self-review.md).
+
+*The evidence that shaped this scoping, both directions.* An audit of 20 Self-Review blocks across merged PRs could not find one on a high-risk unit, and its clearest catch — a `undefined === undefined` fail-open (#411) — was on a routine surface, with another producer recording that they ran it on a routine diff *deliberately* because it governed a production traffic shift (#445). That is a real argument that the four named surfaces are the narrower set, and it is why this is scoped rather than deleted. What settled it the other way is that the pass is no longer the only adversarial read: with an independent review required before merge, a routine diff still gets attacked — just once, by a different model, instead of twice. **If that review requirement is ever removed or is not wired in a consumer repo, this scoping should be revisited, because then nothing replaces it.**
+
+Coverage gates prove the tests exist and are honest; they do **not** prove the code is *correct*. The recurring reason a fresh PR fails independent review is a domain-semantic bug the happy-path implementer never thought to attack.
+
+**Proof-of-execution:** a short **Self-Review** block in the PR body — the axes checked, each high-risk surface with its hazard items cleared, and any counterexample found and fixed. A high-risk diff whose PR carries no Self-Review block is a producer step that did not run.
+
+## Required PR Review Contract
+
+Every implementation PR includes the Review Contract in its body. The **canonical schema** is `ensure-coverage` → `references/process/review-contract-template.md` — producer and verifier point at that one file so the contract can't drift. Fill every section; a surface-changing PR's **Obligation Impact** block is mandatory, plus the **presentation sweep** result for changed browser routes. A **`presentation:visual`** surface also includes the `visual-gate` result and the committed baseline link — never claim a local visual run (visual is CI-only in a pinned container; baselines are minted only by the regen job). Trivial docs-only changes keep the contract with unavailable sections marked `Not applicable` + a reason.
+
+## Testing Rules
+
+- Map every required AC to an automated test or approved exception, and every changed surface to its baseline obligation (see Coverage Obligations).
+- Tag tests with `// @covers <surface-id>` and `// @level <level>` so the Coverage Ledger resolves evidence to the surface.
+- In TDD mode, include RED/GREEN evidence for each implemented behavior slice or explain why RED was not possible.
+- Use the test level required by the test criteria; do not substitute mock-only tests where integration is required.
+- Prefer behavior/state assertions over implementation-detail assertions.
+- Include negative cases and misuse paths required by the test criteria.
+- For async/pub-sub/orchestrator work, assert final durable state, emitted events, retries, and correlation IDs.
+- For money/security/idempotency/concurrency work, include integration coverage unless explicitly approved otherwise.
+- If a test cannot be automated, document why and include the approval reference in `Known Gaps`.
+
+## Evidence Rules
+
+**Trigger: the round that requests the terminal review** — for the *attestation*. Two obligations inside are earlier than that and are not deferred: **a design input's citations must resolve before you build against it** (`git cat-file -e <sha>:<path>`), and the PR body owes its evidence list at PR open, not at exit. Full rules — how to generate the block, the citation and stale-locator rules, the design-input check: [references/evidence-rules.md](references/evidence-rules.md).
+
+What every round owes, regardless:
+
+- **Never claim tests passed without command output or CI evidence.** If tests cannot run locally, say so and rely on CI only if that is acceptable for the repo.
+- **Generate volatile evidence; never transcribe it.** Scan counts, CI tables and SHAs come from `evidence-block.mjs collect`, which stamps them to the HEAD they describe. (Named incident: a hand-written attestation claiming `leadCount=0` for a diff whose real scan had 1,749 leads — a full review round spent on a transcription error.)
+- **Cite tests by stable identity, never by line range.** `@covers` tags and test names survive an edit; `foo.test.ts:252-274` goes stale the moment anything above line 252 moves, and under `resolve-issues` the fix rounds edit exactly those files.
+
+**Exact-head evidence is a terminal-round obligation, not a per-round one** — the screens run every round, the *attestation* is produced once, when the unit is otherwise ready to exit. What this must never be read as: the screens are terminal-round-only. A reviewer must still be unable to receive a PR whose findings channel is non-empty, on any round.
+
+## CI And Review Gate
+
+Do not ask for review until:
+
+- Review Contract is complete, including the Obligation Impact block for any changed surface.
+- Required tests have been added or updated, tagged `@covers`/`@level`.
+- **Each CHANGED NON-BROWSER surface** (service, API, CLI, job) has been run: started with the repo's documented run command, happy path responds, runtime-smoke Coverage Checklist row filled with command + output. **Browser surfaces are no longer smoke-validated here** — CI covers them (`frontend-smoke`, `frontend-smoke-shard`, `coverage-presentation`, `coverage-functional`, and the repo's journey gates, all required by `all-gates`), and `resolve-issues` kicks CI *in parallel with the review*, so a producer-side duplicate bought a fraction of a round and cost an action every round. The carve-out is not symmetry: CI has only "smoke CLI import path" steps for non-browser surfaces, which is weaker than boot-and-exercise-the-happy-path, so that case keeps its check. **"Changed", not "new"**, deliberately: `coverage-checklist.mjs`'s `depth.runtime-smoke` row is defined over *each changed* non-browser surface and is validated every round, so a spine saying "new" would send a producer past a row the same spine then fails them on.
+- The `ensure-coverage` coverage gate (`coverage-ledger.mjs validate`) is clean, or every finding is resolved/explicitly accepted.
+- **Every round:** the mechanized **screens** are green — `scan-diff.mjs`'s findings channel empty, `coverage-checklist.mjs validate` passing, `evidence-block.mjs collect` run. These cost seconds and each one prevents a wasted review round, so they never move.
+- **Terminal round only:** `evidence-block.mjs validate` is green **at the SHA you are about to push**. The stamped block is an *attestation*, not a screen: it is a whole-document rewrite that the next commit invalidates, so producing it every round buys nothing and each rewrite is a fresh chance to overclaim. Produce it once, when the unit is otherwise ready to exit. (Under `resolve-issues` the orchestrator does not gate a reviewer spawn on it on an ordinary round — **but on the round you flag terminal it does**, re-running this same `validate` before it spawns the reviewer, because otherwise the one round that owes the stamp is the one round nothing checks it on. Your green here is what makes that check a formality; see its step 2.)
+- **High-risk diffs only:** the [adversarial Self-Review pass](#self-review-before-handoff-adversarial-pass) has run and its **Self-Review block** is in the PR body, including the fails-if-broken spot-check evidence for high-risk ACs. **It is no longer a routine obligation** — an independent review does the same job with a different model and fresh context, so on a routine diff the pass was buying "catch it one round earlier", not catching what nothing else would. That trade stops being worth an action every round once the review is guaranteed to run.
+- The **reviewer-parity proof** is in the PR body — `scan-diff.mjs` findings-channel output (empty) + `coverage-checklist.mjs validate` (passing), see step 6. The *screens* run every round and a non-empty findings channel blocks the handoff every round; what is terminal-round-only is **pasting the proof block against the final HEAD**, which is the part that goes stale on the next commit.
+- Local checks have run, or a blocker is documented.
+- CI has passed, or CI failure is fixed/clearly reported as blocking. (This gates the *standalone producer* requesting its own review; under `resolve-issues` the orchestrator spawns the review itself, in parallel with CI — this bullet never serializes that loop.)
+- **This skill's own home repo only (the skills-authoring repo these skills are developed in — no analogue in a consumer repo):** a PR changing first-party skill content owes `distribution.mjs generate`, committed, before the PR opens. Rule, mechanism, traps: `skills/distribution/README.md` in that repo — stated as a path rather than linked, because `skills/distribution/` doesn't exist in a consumer install and the repo it lives in is private.
+
+If CI is pending and review is urgent, state that explicitly and mark the PR as not merge-ready.
+
+**In-loop enforcement (hooks).** These same gates run *earlier* as Claude Code hooks when the repo wires them: a `PreToolUse` hook denies an edit that adds a skip/fixed-timeout to a test file, and a `Stop` hook blocks finishing while `lint-tests --diff`/`coverage-ledger validate` is red. Treat a hook block as the gate telling you the truth sooner — fix the cause, don't reach for the `TEST_GATE_OFF` escape hatch to land a real skip. Doctrine + install: `ensure-coverage` → `references/enforcement/hooks.md`.
+
+## CI Iteration Discipline
+
+**Trigger: CI failed.** Read [references/ci-iteration.md](references/ci-iteration.md) before pushing a fix — a CI failure is a bug to *diagnose*, not a config to *guess at*. The one number that must not be exceeded without a human: **after 3 consecutive attempts failing on the same infrastructure/config error, stop pushing and escalate**, with what you tried, the current error, and your hypothesis.
+
+## Anti-Patterns
+
+Every item that used to sit here restated a rule stated above, which made this a second place for those rules to drift from — the list is gone rather than duplicated. Two are kept because this was their only statement:
+
+- **Calling a PR ready on green tests alone without ever running the surface** — shipping a build that won't boot, or a route that 500s on first load.
+- **Broad unrelated refactors in the same PR** — they enlarge the diff a reviewer must hold in mind to find the change that matters.
+
+## Output
+
+When reporting back, include:
+
+- PR link.
+- CI status.
+- Tests/evidence summary.
+- Implementation model used (so the capability tier is auditable downstream).
+- Known gaps or blockers.

package/skills/engineering/implement-and-pr/references/ci-iteration.md

@@ -0,0 +1,10 @@
+# CI iteration discipline — diagnose, don't push-to-debug
+
+Read this when a CI check fails on your PR (SKILL.md "CI Iteration Discipline" forces this read before you push a fix).
+
+A CI failure is a bug to *diagnose*, not a config to *guess at*. The failure mode to avoid is push-to-debug: a chain of `fix(ci): …` commits that each test a single guess against the remote — slow, history-polluting, and usually a sign the environment was never understood.
+
+- **Reproduce the failure locally before you push a fix.** Run the same command the failing job runs against the same dependencies (service container / DB image / browser deps, e.g. via the CI service definition or `act`). Push only once you have reproduced the failure and confirmed the fix locally. Reading the remote log is diagnosis input, not the iteration loop.
+- **Batch infrastructure fixes.** When a failure is environmental (service networking, ports, runner setup, system deps), fix the whole class in one repro-informed commit — not one knob per push.
+- **A pipeline gap is not your PR's problem to fix in-place.** When diagnosis shows CI *structurally* cannot pass this class of PR (a docs-only diff failing gates that assume code; a generated-artifact PR with no matching lane), do not edit workflow files inside the content PR — that changes the PR's scope class, voids prior review, and puts CI policy through a review not scoped for it. Surface the gap as its own issue/PR and raise it to the human; check the current base first — the gap may already be fixed there (observed: a docs-only ADR PR carried three workflow commits for a gap the base had already closed).
+- **Retry ceiling → escalate to a human.** **After 3 consecutive CI attempts that fail on the same infrastructure/config error** (networking, ports, runner/service setup, missing system deps — *not* test-logic failures), **stop pushing and raise for human intervention**, reporting what you've tried, the current error, and your leading hypothesis. Crossing this ceiling means the environment isn't understood from the logs alone, and a human with runner access resolves it faster.

package/skills/engineering/implement-and-pr/references/closeout.md

@@ -0,0 +1,27 @@
+# The close-out — everything between "the code works" and "ready for review"
+
+Read this at handoff, once. It is the full form of SKILL.md's workflow steps 6-7: verify, smoke-validate, run the coverage gate, resolve over-mock, generate and validate the checklist, self-review, attach the reviewer-parity proof, and open or update the PR.
+
+**A fix round runs a subset.** Intermediate rounds owe the fixes and their RED/GREEN plus green screens; the exact-head attestation belongs to the round that requests the terminal review (SKILL.md § Evidence Rules).
+
+6. **Verify, smoke-validate, then run the coverage gate (the AFTER handoff — back to `ensure-coverage`).** Local checks, RED/GREEN evidence when applicable. **Then smoke-validate the running surface:** run what you built once and capture that it runs — the "tests pass but the app won't boot / the route 500s on first load" class; a failed boot or happy path blocks readiness regardless of green tests. Route by surface kind (a plain action against the repo, never a named agent/harness feature):
+   - **Browser surface** → **no producer-side run** (#471): CI covers it (`frontend-smoke`,
+     `frontend-smoke-shard`, `coverage-presentation`, `coverage-functional` and the journey gates,
+     all required by `all-gates`), and `resolve-issues` kicks CI in parallel with the review, so a
+     producer-side duplicate bought a fraction of a round and cost an action every round.
+   - **Non-browser surface (service/API/CLI/job)** → start it with the repo's documented run command, exercise the changed surface's happy path, capture the command + observed output (boot log, HTTP status + body snippet, exit code).
+   - **Golden path touched?** → a critical do-not-ship journey added/altered owes a `smoke.manifest.json` entry and the curated **E2E smoke gate at ALIVE** before handoff: boot the app, drive the selected paths into `smoke-results.json`, run `<smoke>/scripts/smoke.mjs verdict --target local --results smoke-results.json` (read the `smoke` skill's SKILL.md from the same skills root and follow it); attach `smoke-verdict.json` to the PR. This is the per-PR **golden-path liveness floor** (`ensure-coverage` gate 8), stronger than the per-surface boot check. A new critical flow with **no manifest entry** is itself a gap.
+   - Write the run-it results to a small JSON (`{surface, status}` list) for the checklist step's `--smoke` input. A changed non-browser surface with no smoke results leaves `depth.runtime-smoke` at `TODO`, which `coverage-checklist.mjs validate` and CI reject; `fail`/`error`/`blocked` fills it `FAIL`; `N/A` with a reason only for a docs/config-only change. Enforcement lives in the repo's checklist + CI, not in any agent.
+
+   Then close out the gate before handoff:
+   - **Classify the scope FIRST — it decides which of the rows below even apply.** Run `ensure-coverage`'s `scope-class.mjs classify` over the net diff you already computed: `git diff $(git merge-base <target-branch> HEAD)...HEAD | node <ensure-coverage>/scripts/scope-class.mjs classify --stdin --json`. It is **deny-by-default**: `no-surface` only when *every* path matches a configured non-runtime pattern (CI/policy config, docs, lockfiles, generated files, tests), and one unmatched path ⇒ `surface-bearing` and the full gates below. Then:
+     - **`surface-bearing`** (the normal case) — nothing changes; run everything below.
+     - **`no-surface`** — **return the classifier's `--json` payload verbatim in your result, under `scopeClass`** (the whole object — `scopeClass`, `reason`, `highRisk`, `inapplicable`, `smokeNotApplicableReason` — not a summary of it). Do **not** write it to the run manifest yourself: the orchestrator is the manifest's only writer (ADR 0001 decision 5 (`docs/adr/0001-interference-is-the-scheduling-primitive.md`)), and it records the field in the turn your result lands. Its step-2 pre-spawn check then accepts an absent checklist **only** on the recorded field, never on your say-so — so a `no-surface` unit whose result omits `scopeClass` bounces exactly as one that was never classified. Fill the Review Contract's `Scope Class` line and its inapplicable rows **from the classifier's `inapplicable` output**, verbatim — the reason is derived, not written per run. Then **run each matched class's declared ORACLE and report its result**: the oracle replaces the checklist, it is not a waiver, and a matched class with no declared oracle is a blocking finding you fix by declaring one (or by declaring the class unproven-by-design and saying so in the Contract). Smoke keeps the existing `not-applicable` + reason path with the reason the classifier derived — it is not skipped.
+     - Either way the class **changes no review-depth obligation** — same reviewer spawn, same model-diversity rule, same verdict bar — and `scan-diff`'s findings channel stays zero-tolerance. `no-surface` ≠ low-risk: merge/CI/deploy/IAM paths set `highRisk: true` *alongside* it. Doctrine: `ensure-coverage` → [process/scope-class.md](../../ensure-coverage/references/process/scope-class.md).
+   - **Coverage gate** — run `ensure-coverage`'s `coverage-ledger.mjs validate` (or the repo wrapper) and complete the Obligation Impact block.
+   - **Resolve over-mock — don't ship it to review.** Over-mock is static and decidable, so it is the producer's to catch, not the reviewer's to discover. Run `ensure-coverage`'s `lint-tests.mjs --rules mock-internal-seam` (diff **and** whole-tree) and clear every hit by making the seam real or faking only the external; a `vi`/`jest.mock` of a first-party internal seam (store/engine/action/DB) is `Over-mocked` — zero-tolerance, no waiver. (The same screen also runs at edit-time as a `PreToolUse` hook and at the per-PR CI gate.) Boundary doctrine: `ensure-coverage` → [depth/mock-policy.md](../../ensure-coverage/references/depth/mock-policy.md).
+   - **Generate + validate the Coverage Checklist** — `coverage-checklist.mjs generate --diff <base> --ci <ci> --ledger --sweep <results> --smoke <runtime-smoke-results>` auto-fills the gate rows (`--smoke` fills the runtime-smoke row); complete every lead/judgment row with a `file:line`/`` `command` ``/#issue locator, then `coverage-checklist.mjs validate <checklist> --diff <base>` so no row is prose-only or `TODO`. **Reuse the same `--diff <base>` you generated with.** `validate` resolves every cited `file:line` against the tree and needs the diff to know which unresolvable ones are honest (the paths you deleted); without it you get the shape check, which passes a locator into a file that is gone. Two rows it rejects that the shape check accepted, both of which used to come back as a review finding: a gate row left carrying its command with no result (the skeleton with `PASS` typed over it), and a stale `file:line` left behind by a rebase.
+   - **Adversarial self-review before handoff — high-risk diffs only** (#471; it is no longer a routine obligation, because an independent review now does the same job with a different model). Run the [Self-Review pass](../SKILL.md#self-review-before-handoff-adversarial-pass) over the net diff and record its **Self-Review block** in the PR body — for any diff touching a high-risk surface (auth/money/tenancy/migration). This is where the domain-semantic bug that would otherwise burn a review round gets caught.
+   - **Attach reviewer-parity proof — terminal round, against the final HEAD.** The independent review mechanically demands two artifacts before it reads anything: review-pr's `scripts/scan-diff.mjs` **findings-channel output** over the net `merge-base...HEAD` diff, and the `coverage-checklist.mjs validate` result. Run scan-diff by **piping the net diff into it** — `git diff $(git merge-base <target-branch> HEAD)...HEAD | node <skillsRoot>/engineering/review-pr/scripts/scan-diff.mjs` (or `--diff <file>` for a saved patch); it reads a unified diff from stdin and has **no `--base`/`--head` flags** — invent those and it now hard-fails (exit 2) rather than scanning empty stdin and stamping a vacuous "findings [] / leads []" proof. Run both yourself and paste both outputs into the PR body's evidence section, **stamped with the HEAD SHA they were computed against** (`git rev-parse HEAD`, the same SHA the PR serves; the reviewer independently recomputes the merge-base and range with review-pr's `pr-context.mjs`, so the stamp is evidence, never authorization). Ordering matters: this runs *after* the self-review, because a self-review counterexample fix is a new commit that invalidates a proof computed earlier — **any commit after the proof (a self-review fix, a rebase, a late tweak) means re-running it**; a proof whose SHA doesn't match the PR HEAD is stale, and the orchestrator treats it as missing. **Cadence — the distinction #464 turns on.** The two *screens* run every round and bounce a handoff every round: a non-empty findings channel or a failing `validate` never reaches a reviewer. The *stamped proof block* is owed only by the round that requests the terminal review — an intermediate fix round owes green screens, not a fresh attestation, because a stamp regenerated per round is a document the next commit voids. Under `resolve-issues` the orchestrator gates its reviewer spawn on the screens on an ordinary round — **and on the stamp as well on the round you flag terminal**, re-running `evidence-block.mjs validate` before it spawns. That is not a second cadence: it is the same terminal-round obligation, checked on the one round where nothing else would. A stale stamp discovered by the terminal reviewer costs the fix *plus* a fresh re-review to exit, so your green here is what keeps that check a formality.
+   - Gather CI status, test files/names, logs/screenshots/traces.
+7. Open/update the PR with the Review Contract, then handle CI/review feedback by updating code, tests, and evidence. **A review finding carrying a `hazard_candidate` is fixed in two parts: the code fix and the candidate's row written into `docs/domain-hazards.md`** (creating file + `AGENTS.md` index pointer if absent; `covered_by` findings cite the existing row) — both in the same fix commit; the re-review verifies the row, and a code-only fix reconciles as `Partially resolved`. **And a fix diff is a diff:** before requesting re-review, re-run the step-6 close-out on it — scan screens, coverage gate, self-review (with the fails-if-broken spot-check where it applies), green screens (the `scan-diff` findings channel and `coverage-checklist validate` run on every round; the SHA-stamped attestation is the terminal round's, not this one's — SKILL.md § Evidence Rules); a fix that clears the prior findings while shipping a new unscreened blocker is how round 2 becomes round 3. **Fix the class, not the cited instance.** A finding names one instance; the obligation is the rule behind it. Before calling a finding fixed, close the adjacent members too — the sibling union, the column beside it, the second concurrent writer — and name in the commit and the Review Contract which class you closed and what you checked. A narrow fix doesn't hide the bug, it *delays* it: the same invariant returns two rounds later at a wider scope, at the cost of a full fix + re-review + CI round each time. Size it to the finding, though — most findings are their own class (a typo, a copy string, the one field with a null case), and "class = this call site, no siblings exist" is a complete answer in one line. The obligation is to state the boundary, not to manufacture one. The PR **must** carry the Review Contract (with the Obligation Impact block on any surface-changing diff) and the completed Coverage Checklist — mechanized, not honor-system: `coverage-checklist.mjs validate` runs here and as a blocking CI job, and `review-pr` independently rejects a PR with no usable contract.

package/skills/engineering/implement-and-pr/references/contract-complete-fix-rounds.md

@@ -0,0 +1,34 @@
+# Contract-complete fix rounds
+
+Read when this PR fixes a review finding. Two rules, with different triggers: **neighborhood re-verification** applies to every fix round; the **contract-complete matrix** applies to state-machine/concurrency findings on a high-risk unit.
+
+### Neighborhood re-verification (every fix round)
+
+**Keep the edit narrow; do not keep the verification narrow.** A fix round is scoped — "change only X, do not touch already-resolved behavior" — and that scoping is correct: it is what stops a fix round regressing settled work. But scoping the *edit* and scoping the *verification* are different decisions, and collapsing them is why a fix round lands one repair and exposes its neighbor.
+
+After the edit, before handoff, re-run the **enumerated space the surface belongs to** — not the whole suite, and not only the finding's own test:
+
+- The finding named a cell of some space (a validation point, a rendered state, a branch of a contract). Re-run **every cell of that space**, not the one that was reported. When the reviewer ran a round-1 sweep it names the space explicitly (`review-pr` → `references/round1-depth.md`) — reuse that enumeration. Otherwise derive it from the finding's own kind: a rule that must hold in several places implies every place it must hold; a user-visible state implies every dimension that state varies over.
+- Re-run the cells the *edit* could have moved, even where no finding pointed. A change to a shared component, a shared lifecycle, or a shared validator's signature reaches every cell that shared thing serves — which is exactly the reach that made the narrow fix attractive.
+- Record which cells you re-ran and their results in the fix-round artifact. "Focused tests pass" is the finding's own cell, reported as if it were the space.
+
+*Named incident: skyee-ai-risk #1144 / PR #1148. Round 7 fixed pointer-hover/focus perceivability for disabled row actions; round 8 found the touch cell of the same affordance still hidden; round 9 found post-mutation list reconciliation broken by the same shared data-fetch migration; a later pass found the destructive-button contrast cell failing. Each fix was correct and narrowly verified. Four passes over one component's interaction surface, four scope splits, and a 43-hour unit — because nothing re-ran the neighborhood.*
+
+**The guard against over-application:** the neighborhood is the surface's own space, not the repo. A one-line fix to an isolated helper with one caller has a neighborhood of one cell — say so and move on. Re-running the full suite to satisfy this rule is the process-weight failure, not compliance.
+
+### Contract-complete fix rounds (high-risk state-machine/concurrency findings)
+
+When this PR fixes a **state-machine or concurrency** finding on a high-risk
+unit (`resolve-issues/references/high-risk.md`), the fix round is a contract
+artifact, not a counterexample patch: carry the finding's durable `theme.id`
+and general violated contract into the round, enumerate the governing
+contract's `state × taskKind` cells with a test + execution-evidence locator
+each, and self-review every adjacent state under the same rule — a single
+counterexample test never closes the theme. **Return that matrix in your result
+as `fixRound`** — theme id, violated contract, and the enumerated cells with
+their locators. Do not persist it yourself: the orchestrator is the run
+manifest's only writer (ADR 0001 decision 5 (`docs/adr/0001-interference-is-the-scheduling-primitive.md`)),
+and on a long or contested run it banks what you return, fail-closed.
+For any other finding, a normal cause-fix plus
+its test is the whole *edit* obligation — neighborhood re-verification above
+still applies.