@andresmassello/uscha 1.51.3 → 1.54.0

package/README.md

@@ -11,12 +11,26 @@ never what was claimed.
 (essay, 2-day dev course, reference, paper).
 
 ```bash
-npx --yes @andresmassello/uscha@latest install --target claude
-npx --yes @andresmassello/uscha@latest doctor  --target claude
+npx --yes @andresmassello/uscha@latest install --target claude   # Claude Code
+npx --yes @andresmassello/uscha@latest install --target codex    # Codex
+npx --yes @andresmassello/uscha@latest install --target cursor   # Cursor
+npx --yes @andresmassello/uscha@latest install --target copilot  # VS Code / GitHub Copilot
+npx --yes @andresmassello/uscha@latest install --target gemini   # Gemini CLI
+npx --yes @andresmassello/uscha@latest install --target cline    # Cline
+npx --yes @andresmassello/uscha@latest install --target pi       # pi (Earendil)
+npx --yes @andresmassello/uscha@latest install --target all      # every target at once
+
+npx --yes @andresmassello/uscha@latest doctor --target all
 ```
 
-`--target codex` for Codex, `--target pi` for pi (Earendil), `--target all` for all three
-(`both` stays a legacy alias for codex+claude). Then, in your project:
+The nine skills implement the **Agent Skills** standard, so the last five targets are the same
+skills placed under each agent's own documented root. Honest scope: only Claude Code and Codex
+have been exercised against a real agent — for the rest, that they load is a *documented
+expectation, not a measurement*. What is measured is that the files land where each agent
+documents reading them and that `doctor` reads them back. INV-GOLDEN-01 is mechanically
+enforced only on Claude Code (a blocking PreToolUse hook); everywhere else `doctor` reports it
+as `advisory` rather than implying a guard it cannot see.
+(`both` stays a legacy alias for codex+claude.) Then, in your project:
 
 ```bash
 npx --yes @andresmassello/uscha@latest init
@@ -26,8 +40,8 @@ Requires **Python 3.8+** on the machine (the engine is Python stdlib — no pip
 runtime dependencies). The npm package is a thin router; the canonical installer is
 `uscha-kit/install-uscha.py`.
 
-**Kit v1.51.3** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
-[changelog](https://github.com/andresmassello/uscha/blob/main/uscha-kit/CHANGELOG-1.51.3.md)
+**Kit v1.54.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+[changelog](https://github.com/andresmassello/uscha/blob/main/uscha-kit/CHANGELOG-1.54.0.md)
 (the per-release changelogs live in the repo, not in the npm tarball)
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andresmassello/uscha",
-  "version": "1.51.3",
+  "version": "1.54.0",
   "description": "Spec-driven development for LLM coding agents: 9 skills + a stdlib evidence engine. Facts block, guesses advise; the human approves.",
   "bin": {
     "uscha": "bin/uscha.js",

package/uscha-kit/.claude/skills/uscha-adr-refine/SKILL.md

@@ -1,161 +1,231 @@
----
-name: uscha-adr-refine
-description: >
-  Turn a rough idea into a development-ready ADR set + ACCEPTANCE.md by INTERROGATING
-  before generating. Runs a structured Socratic interview (problem, implicit decisions,
-  behavior incl. failure modes, inviolable constraints, out-of-scope, Definition of
-  Done, dependencies), refuses to emit artifacts until the gaps are closed, then
-  distills the conversation into docs/adr/ADR-NNN.md files and an ACCEPTANCE.md. The
-  front-half counterpart to dev-loop. Invoke for "refine the ADR", "let's spec this
-  before coding", "ayudame a definir esto antes de desarrollar".
-allowed-tools: Read, Write, Glob, Grep
-disable-model-invocation: false
----
-
-# adr-refine — interview, then distill
-
-You convert a rough idea into a development-ready specification. You do this in two
-phases. **You are NOT a generator. You are an interrogator that distills.** The value
-is in the questions, not in agreeing.
-
-## Non-negotiable principles
-
-1. **Interrogate, don't agree.** Your job in Phase A is to surface what the human left
-   implicit and to find the holes — not to validate. A refinement where you agreed with
-   everything failed.
-2. **Converge, don't run out of questions.** The interview ends on an objective
-   criterion (below), not when the human seems tired or you run out of ideas. This
-   mirrors dev-loop's "converge, don't chase zero" — the same discipline at the front.
-3. **Do not emit artifacts until convergence.** No ADR, no ACCEPTANCE.md until every
-   exit condition is met. If asked to "just write it" early, name the open gaps first.
-4. **One topic at a time.** Never dump 20 questions. Walk the agenda below, a focused
-   batch at a time, and reflect back what you heard before moving on.
-5. **Record deferrals as explicit assumptions.** If the human says "you decide" on a
-   consequential decision, push back once with the trade-off; if they still defer,
-   record it as an explicit assumption in the ADR, never as a silent default.
-
-## Phase A — The interview (agenda)
-
-Start from the human's initial context. Work the agenda in order; skip a topic only if
-it's already fully answered. Keep a running list of OPEN GAPS and resolved decisions.
-
-1. **Problem and why now.** What job does this remove? What does it cost to NOT do
-   it (money, time, risk)? If "why now" has no answer, the priority is suspect.
-2. **Implicit decisions.** Surface the choices the request assumed: sync vs async,
-   storage, protocol, idempotency, transactional boundaries, who owns state. For each,
-   force an explicit decision and at least one considered alternative.
-3. **Behavior.** Happy path first, then the DIRTY cases: provider/timeout failures,
-   retries and backoff, 4xx vs 5xx, concurrency, partial/terminal states, what must NOT
-   happen. A feature without its failure behavior is half-specified.
-4. **Inviolable constraints (→ `CONSTITUTION.md`).** Domain + security + operation
-   rules that cannot be broken (money to the cent, numbering without gaps, never cross
-   environments/credentials, secrets never logged, auth/authz, data retention). Write/extend
-   `CONSTITUTION.md` (one invariant per line, CWE ref where it maps); these feed the
-   dev-loop severity gate and a breach is a BLOCKER. **An ADR may never contradict the
-   CONSTITUTION** — if a decision would, it's escalated, not recorded.
-5. **Out of scope.** Explicit boundaries, with forward references ("X goes to a later
-   spec"). What you exclude is as important as what you include.
-6. **Definition of Done + how we measure success.** Concrete, checkable acceptance criteria
-   (tests green, documented, metrics published, runbook) AND success metrics (p95,
-   cost ceiling, zero orphaned records). Each item must be verifiable, not a feeling.
-7. **Dependencies.** Which other specs/systems/credentials this needs to exist first.
-
-After each batch, reflect: "Decided: … / Still open: …". Move on only when the
-current topic is closed.
-
-## Convergence — exit conditions (ALL must hold)
-
-- Every decision has a rationale and at least one considered alternative.
-- Every failure mode named has a defined behavior.
-- Out-of-scope is explicit.
-- The Definition of Done exists and every item is checkable.
-- No OPEN GAP you raised remains unresolved (resolved = decided OR recorded as an
-  explicit assumption).
-
-State plainly when you've converged ("Closed: every decision has a rationale, the failures
-have behavior, the scope has a boundary and the DoD is verifiable.") before Phase B.
-
-## Phase B — Distill the artifacts
-
-Only after convergence. Produce (and, if any new project-wide invariant surfaced in
-step 4, append it to **`CONSTITUTION.md`** — never let an inviolable rule slip into an
-ADR where it could later be "traded away"):
-
-1. **One ADR per decision worth recording** at `docs/adr/ADR-NNN-<slug>.md`, format:
-
-```markdown
-# ADR-NNN: <title of the decision>
-## Status: Accepted
-<!-- Use Status: Experiment only for a bounded hypothesis with feedback/review criteria. -->
-## Context
-<the problem + the considered options: A) … B) … C) …>
-## Decision
-<the chosen option>
-## Reasons
-- <why, point by point>
-## Consequences
-+ <the good>
-- <the cost / what it forces on us>
-<!-- If Status: Experiment, also include:
-## Hypothesis
-## Feedback Signal
-## Review By: YYYY-MM-DD  (or ## Review Trigger)
-## Promote Criteria
-## Rollback / Supersede Criteria
--->
-## Implementation Plan
-- Affected paths: <files/dirs>
-- Patterns: <pattern to follow>
-- Tests: <which tests prove the decision>
-## Verification
-- [ ] <criterion checkable by an agent>
-```
-
-   Number ADRs continuing from the highest existing one in `docs/adr/` (glob first).
-   Negative decisions count: "what we are NOT going to use and why" is a valid ADR.
-   Experimental decisions count only when they are explicit hypotheses with feedback signal,
-   review date/trigger, promote criteria and rollback/supersede criteria. Do not use
-   `Status: Experiment` as a polite way to avoid deciding.
-
-2. **`ACCEPTANCE.md`** at the repo root (or the path in `uscha.config.json` →
-   `defaults.acceptance_file`). This is the file dev-loop's readiness measures — it MUST
-   exist and be checkable:
-
-```markdown
-# Acceptance — <feature>
-## Definition of Done
-- [ ] AC-01 — <verifiable criterion>
-- [ ] AC-02 — <verifiable criterion>
-## How we measure success
-- <objective metric: p95, cost, zero orphans, …>
-## Out of scope
-- <boundary> → <future spec>
-## Recorded decisions
-- ADR-NNN — <title>
-```
-
-**Where to write:** with file tools available (Claude Code), write the files to disk.
-In a chat-only context, print each file in a fenced block, clearly labeled with its
-target path, ready to paste — and remind the human these go to `docs/adr/` and the repo
-root before running dev-loop.
-
-**Tracked-markdown protocol:** if any target `.md` already exists and is tracked, ask
-for its current version before overwriting — never silently replace.
-
-## Handoff to dev-loop
-
-Close with the handoff prompt so the build phase starts by planning, not improvising:
-
-> "Read the ADR set and ACCEPTANCE.md. Before touching code: 1) summarize the plan of
-> files to create/modify, 2) confirm which decisions were left implicit, 3)
-> show me the first test you would write."
-
-Two-command flow end to end: `/uscha-adr-refine` → (ADR set + ACCEPTANCE.md) → `/uscha-devloop`.
-
-## Anti-patterns (do not do)
-
-- Generate an ADR from a one-line request without interviewing.
-- Accept "do it however you want" on a consequential decision without recording the
-  assumption.
-- Write an ACCEPTANCE item that isn't objectively checkable ("that it works well").
-- Emit artifacts before the convergence conditions are met.
+---
+name: uscha-adr-refine
+description: >
+  Turn a rough idea into a development-ready ADR set + ACCEPTANCE.md by INTERROGATING
+  before generating. Runs a structured Socratic interview (problem, implicit decisions,
+  behavior incl. failure modes, inviolable constraints, out-of-scope, Definition of
+  Done, dependencies), refuses to emit artifacts until the gaps are closed, then
+  distills the conversation into docs/adr/ADR-NNN.md files and an ACCEPTANCE.md. The
+  front-half counterpart to dev-loop. Invoke for "refine the ADR", "let's spec this
+  before coding", "ayudame a definir esto antes de desarrollar".
+allowed-tools: Read, Write, Glob, Grep
+disable-model-invocation: false
+---
+
+# adr-refine — interview, then distill
+
+You convert a rough idea into a development-ready specification. You do this in two
+phases. **You are NOT a generator. You are an interrogator that distills.** The value
+is in the questions, not in agreeing.
+
+## First contact (show ONCE, then never again)
+
+**Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
+`ACCEPTANCE.md`, no `docs/adr/` -- open with this block, then start working. If any of those
+exist, the operator already knows the method: skip it entirely and go straight to the
+breadcrumb. Repeating it every run would be exactly the ceremony the method forbids.
+
+```
+[uscha · adr-refine · START]
+Method: you bring the idea, the method builds the rest. Facts block, guesses advise;
+        nothing closes on a checkbox, and the human approves the merge.
+Here:   a precision interview on a feature whose shape you already know. I refuse to emit until the gaps close.
+Output: docs/adr/ADR-NNN.md · ACCEPTANCE.md
+Next:   `/uscha-devloop` builds against the ADR + ACCEPTANCE.
+Stop:   say so at any point -- whatever is already written stays.
+```
+
+**Bilingual by construction.** The labels (`START`, `Method`, `Here`, `Output`, `Next`,
+`Stop`) stay VERBATIM in English -- they are the method's vocabulary and the smoke suite checks
+for them mechanically, which is only possible if they never move. The wording after each label
+is the canonical English; **render it in the operator's language**. If they are writing to you
+in Spanish, the whole block reads in Spanish under English labels. Do not translate the labels,
+do not leave the content in English when they are not writing in English.
+
+Unlike the close block, `Next` here MAY name the nominal route: on a first run there is no
+measured state to derive from yet, so the nominal path is the honest answer. From the close
+block onward, derived state wins.
+
+## Orientation markers (non-negotiable)
+
+The operator must never have to ask "where am I?" or "what happens now?". Two markers, always.
+They are navigation, not ceremony: one line per turn, one block at the end.
+
+**Open every turn with a breadcrumb**, then the content:
+
+`[uscha · adr-refine · <step> → <target>]`
+
+- `<step>` — `Q<n>` for a question, `pass <n>` for a loop iteration, `step <n>` otherwise.
+  Count what has actually happened. **Never write a denominator** (`Q4/12`): this phase
+  converges, its length is not known in advance, and an invented total is exactly the kind of
+  narrated number the method forbids. **When the ledger already measures the count** (the QA
+  loop's `loop_count`), use the measured number — never keep a parallel tally of your own.
+- `<target>` — the artifact this turn feeds (`SPEC`, `ADR-003`, `ACCEPTANCE`, `LEDGER`,
+  `RECEIVED`, ...). Drop `→ <target>` only when the turn genuinely feeds none.
+
+**Close with the close block ONCE, when the skill finishes** — not on every turn. Ending
+without it is a defect, even when the phase converged cleanly:
+
+```
+[uscha · adr-refine · CLOSED]
+Produced: <files actually written, or "nothing">
+Blocks:   <what stands between here and the next phase, or "nothing">
+Next:     <the next action, and why it is that one>
+Run:      <the exact command or skill to invoke>
+```
+
+This is **not** the implementation handoff some skills also emit: that one is a prompt for
+whoever implements next, this one is navigation for the human operator, and both can appear.
+
+`Blocks` and `Next` are **derived from the state you just produced** — never copied from a
+fixed route, **including any `Flow:` line in this file**. Those lines are the nominal path;
+open ADR experiments, an unclosed spike, an unapproved golden or a red gate all change what
+genuinely comes next, and the derived answer wins. If the next phase cannot start yet, name it
+and say exactly what unblocks it.
+
+Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
+`Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+
+## Non-negotiable principles
+
+1. **Interrogate, don't agree.** Your job in Phase A is to surface what the human left
+   implicit and to find the holes — not to validate. A refinement where you agreed with
+   everything failed.
+2. **Converge, don't run out of questions.** The interview ends on an objective
+   criterion (below), not when the human seems tired or you run out of ideas. This
+   mirrors dev-loop's "converge, don't chase zero" — the same discipline at the front.
+3. **Do not emit artifacts until convergence.** No ADR, no ACCEPTANCE.md until every
+   exit condition is met. If asked to "just write it" early, name the open gaps first.
+4. **One topic at a time.** Never dump 20 questions. Walk the agenda below, a focused
+   batch at a time, and reflect back what you heard before moving on.
+5. **Record deferrals as explicit assumptions.** If the human says "you decide" on a
+   consequential decision, push back once with the trade-off; if they still defer,
+   record it as an explicit assumption in the ADR, never as a silent default.
+
+## Phase A — The interview (agenda)
+
+Start from the human's initial context. Work the agenda in order; skip a topic only if
+it's already fully answered. Keep a running list of OPEN GAPS and resolved decisions.
+
+1. **Problem and why now.** What job does this remove? What does it cost to NOT do
+   it (money, time, risk)? If "why now" has no answer, the priority is suspect.
+2. **Implicit decisions.** Surface the choices the request assumed: sync vs async,
+   storage, protocol, idempotency, transactional boundaries, who owns state. For each,
+   force an explicit decision and at least one considered alternative.
+3. **Behavior.** Happy path first, then the DIRTY cases: provider/timeout failures,
+   retries and backoff, 4xx vs 5xx, concurrency, partial/terminal states, what must NOT
+   happen. A feature without its failure behavior is half-specified.
+4. **Inviolable constraints (→ `CONSTITUTION.md`).** Domain + security + operation
+   rules that cannot be broken (money to the cent, numbering without gaps, never cross
+   environments/credentials, secrets never logged, auth/authz, data retention). Write/extend
+   `CONSTITUTION.md` (one invariant per line, CWE ref where it maps); these feed the
+   dev-loop severity gate and a breach is a BLOCKER. **An ADR may never contradict the
+   CONSTITUTION** — if a decision would, it's escalated, not recorded.
+5. **Out of scope.** Explicit boundaries, with forward references ("X goes to a later
+   spec"). What you exclude is as important as what you include.
+6. **Definition of Done + how we measure success.** Concrete, checkable acceptance criteria
+   (tests green, documented, metrics published, runbook) AND success metrics (p95,
+   cost ceiling, zero orphaned records). Each item must be verifiable, not a feeling.
+7. **Dependencies.** Which other specs/systems/credentials this needs to exist first.
+
+After each batch, reflect: "Decided: … / Still open: …". Move on only when the
+current topic is closed.
+
+## Convergence — exit conditions (ALL must hold)
+
+- Every decision has a rationale and at least one considered alternative.
+- Every failure mode named has a defined behavior.
+- Out-of-scope is explicit.
+- The Definition of Done exists and every item is checkable.
+- No OPEN GAP you raised remains unresolved (resolved = decided OR recorded as an
+  explicit assumption).
+
+State plainly when you've converged ("Closed: every decision has a rationale, the failures
+have behavior, the scope has a boundary and the DoD is verifiable.") before Phase B.
+
+## Phase B — Distill the artifacts
+
+Only after convergence. Produce (and, if any new project-wide invariant surfaced in
+step 4, append it to **`CONSTITUTION.md`** — never let an inviolable rule slip into an
+ADR where it could later be "traded away"):
+
+1. **One ADR per decision worth recording** at `docs/adr/ADR-NNN-<slug>.md`, format:
+
+```markdown
+# ADR-NNN: <title of the decision>
+## Status: Accepted
+<!-- Use Status: Experiment only for a bounded hypothesis with feedback/review criteria. -->
+## Context
+<the problem + the considered options: A) … B) … C) …>
+## Decision
+<the chosen option>
+## Reasons
+- <why, point by point>
+## Consequences
++ <the good>
+- <the cost / what it forces on us>
+<!-- If Status: Experiment, also include:
+## Hypothesis
+## Feedback Signal
+## Review By: YYYY-MM-DD  (or ## Review Trigger)
+## Promote Criteria
+## Rollback / Supersede Criteria
+-->
+## Implementation Plan
+- Affected paths: <files/dirs>
+- Patterns: <pattern to follow>
+- Tests: <which tests prove the decision>
+## Verification
+- [ ] <criterion checkable by an agent>
+```
+
+   Number ADRs continuing from the highest existing one in `docs/adr/` (glob first).
+   Negative decisions count: "what we are NOT going to use and why" is a valid ADR.
+   Experimental decisions count only when they are explicit hypotheses with feedback signal,
+   review date/trigger, promote criteria and rollback/supersede criteria. Do not use
+   `Status: Experiment` as a polite way to avoid deciding.
+
+2. **`ACCEPTANCE.md`** at the repo root (or the path in `uscha.config.json` →
+   `defaults.acceptance_file`). This is the file dev-loop's readiness measures — it MUST
+   exist and be checkable:
+
+```markdown
+# Acceptance — <feature>
+## Definition of Done
+- [ ] AC-01 — <verifiable criterion>
+- [ ] AC-02 — <verifiable criterion>
+## How we measure success
+- <objective metric: p95, cost, zero orphans, …>
+## Out of scope
+- <boundary> → <future spec>
+## Recorded decisions
+- ADR-NNN — <title>
+```
+
+**Where to write:** with file tools available (Claude Code), write the files to disk.
+In a chat-only context, print each file in a fenced block, clearly labeled with its
+target path, ready to paste — and remind the human these go to `docs/adr/` and the repo
+root before running dev-loop.
+
+**Tracked-markdown protocol:** if any target `.md` already exists and is tracked, ask
+for its current version before overwriting — never silently replace.
+
+## Handoff to dev-loop
+
+Close with the handoff prompt so the build phase starts by planning, not improvising:
+
+> "Read the ADR set and ACCEPTANCE.md. Before touching code: 1) summarize the plan of
+> files to create/modify, 2) confirm which decisions were left implicit, 3)
+> show me the first test you would write."
+
+Two-command flow end to end: `/uscha-adr-refine` → (ADR set + ACCEPTANCE.md) → `/uscha-devloop`.
+
+That route is the **nominal** one, not the answer: the `Next:`/`Run:` you emit in the close block are DERIVED from the state you actually produced, and override it whenever an open experiment, an unclosed spike, an unapproved golden or a red gate stands in between.
+
+## Anti-patterns (do not do)
+
+- Generate an ADR from a one-line request without interviewing.
+- Accept "do it however you want" on a consequential decision without recording the
+  assumption.
+- Write an ACCEPTANCE item that isn't objectively checkable ("that it works well").
+- Emit artifacts before the convergence conditions are met.

package/uscha-kit/.claude/skills/uscha-characterize/SKILL.md

@@ -18,6 +18,74 @@ return, you encode the same partial understanding that loses logic silently. **Y
 what the code DOES, mechanically, by running it — never what it should do.** You may write
 the capture harness; you may NOT create, rename, or edit any `.approved` file.
 
+## First contact (show ONCE, then never again)
+
+**Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
+`ACCEPTANCE.md`, no `docs/adr/` -- open with this block, then start working. If any of those
+exist, the operator already knows the method: skip it entirely and go straight to the
+breadcrumb. Repeating it every run would be exactly the ceremony the method forbids.
+
+```
+[uscha · characterize · START]
+Method: you bring the idea, the method builds the rest. Facts block, guesses advise;
+        nothing closes on a checkbox, and the human approves the merge.
+Here:   I run the ORIGINAL code against real inputs and freeze what it does today.
+Output: tests/golden/*.received -- and I STOP: a HUMAN approves the .approved, never me
+Next:   you approve the goldens, then `/uscha-devloop` migrates against them.
+Stop:   say so at any point -- whatever is already written stays.
+```
+
+**Bilingual by construction.** The labels (`START`, `Method`, `Here`, `Output`, `Next`,
+`Stop`) stay VERBATIM in English -- they are the method's vocabulary and the smoke suite checks
+for them mechanically, which is only possible if they never move. The wording after each label
+is the canonical English; **render it in the operator's language**. If they are writing to you
+in Spanish, the whole block reads in Spanish under English labels. Do not translate the labels,
+do not leave the content in English when they are not writing in English.
+
+Unlike the close block, `Next` here MAY name the nominal route: on a first run there is no
+measured state to derive from yet, so the nominal path is the honest answer. From the close
+block onward, derived state wins.
+
+## Orientation markers (non-negotiable)
+
+The operator must never have to ask "where am I?" or "what happens now?". Two markers, always.
+They are navigation, not ceremony: one line per turn, one block at the end.
+
+**Open every turn with a breadcrumb**, then the content:
+
+`[uscha · characterize · <step> → <target>]`
+
+- `<step>` — `Q<n>` for a question, `pass <n>` for a loop iteration, `step <n>` otherwise.
+  Count what has actually happened. **Never write a denominator** (`Q4/12`): this phase
+  converges, its length is not known in advance, and an invented total is exactly the kind of
+  narrated number the method forbids. **When the ledger already measures the count** (the QA
+  loop's `loop_count`), use the measured number — never keep a parallel tally of your own.
+- `<target>` — the artifact this turn feeds (`SPEC`, `ADR-003`, `ACCEPTANCE`, `LEDGER`,
+  `RECEIVED`, ...). Drop `→ <target>` only when the turn genuinely feeds none.
+
+**Close with the close block ONCE, when the skill finishes** — not on every turn. Ending
+without it is a defect, even when the phase converged cleanly:
+
+```
+[uscha · characterize · CLOSED]
+Produced: <files actually written, or "nothing">
+Blocks:   <what stands between here and the next phase, or "nothing">
+Next:     <the next action, and why it is that one>
+Run:      <the exact command or skill to invoke>
+```
+
+This is **not** the implementation handoff some skills also emit: that one is a prompt for
+whoever implements next, this one is navigation for the human operator, and both can appear.
+
+`Blocks` and `Next` are **derived from the state you just produced** — never copied from a
+fixed route, **including any `Flow:` line in this file**. Those lines are the nominal path;
+open ADR experiments, an unclosed spike, an unapproved golden or a red gate all change what
+genuinely comes next, and the derived answer wins. If the next phase cannot start yet, name it
+and say exactly what unblocks it.
+
+Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
+`Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+
 ## Inputs
 
 - **Target module** + a **corpus source**: a path to input fixtures, or a reference to

package/uscha-kit/.claude/skills/uscha-devloop/SKILL.md

@@ -26,6 +26,74 @@ two tiers: **measured** records (snapshots, ingest-gate, log-gate — parsed fro
 artifacts; these can block) and **self-reported** agent counts (log-step — narration
 recorded for the retrospective; a measured red always overrides a narrated green).
 
+## First contact (show ONCE, then never again)
+
+**Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
+`ACCEPTANCE.md`, no `docs/adr/` -- open with this block, then start working. If any of those
+exist, the operator already knows the method: skip it entirely and go straight to the
+breadcrumb. Repeating it every run would be exactly the ceremony the method forbids.
+
+```
+[uscha · devloop · START]
+Method: you bring the idea, the method builds the rest. Facts block, guesses advise;
+        nothing closes on a checkbox, and the human approves the merge.
+Here:   plan → build → a severity-gated QA loop that converges instead of chasing zero → PR.
+Output: code, tests, and QA-LEDGER.json (every gate recorded with its evidence)
+Next:   the human gate: review the PR and decide the merge. I stop there.
+Stop:   say so at any point -- whatever is already written stays.
+```
+
+**Bilingual by construction.** The labels (`START`, `Method`, `Here`, `Output`, `Next`,
+`Stop`) stay VERBATIM in English -- they are the method's vocabulary and the smoke suite checks
+for them mechanically, which is only possible if they never move. The wording after each label
+is the canonical English; **render it in the operator's language**. If they are writing to you
+in Spanish, the whole block reads in Spanish under English labels. Do not translate the labels,
+do not leave the content in English when they are not writing in English.
+
+Unlike the close block, `Next` here MAY name the nominal route: on a first run there is no
+measured state to derive from yet, so the nominal path is the honest answer. From the close
+block onward, derived state wins.
+
+## Orientation markers (non-negotiable)
+
+The operator must never have to ask "where am I?" or "what happens now?". Two markers, always.
+They are navigation, not ceremony: one line per turn, one block at the end.
+
+**Open every turn with a breadcrumb**, then the content:
+
+`[uscha · devloop · <step> → <target>]`
+
+- `<step>` — `Q<n>` for a question, `pass <n>` for a loop iteration, `step <n>` otherwise.
+  Count what has actually happened. **Never write a denominator** (`Q4/12`): this phase
+  converges, its length is not known in advance, and an invented total is exactly the kind of
+  narrated number the method forbids. **When the ledger already measures the count** (the QA
+  loop's `loop_count`), use the measured number — never keep a parallel tally of your own.
+- `<target>` — the artifact this turn feeds (`SPEC`, `ADR-003`, `ACCEPTANCE`, `LEDGER`,
+  `RECEIVED`, ...). Drop `→ <target>` only when the turn genuinely feeds none.
+
+**Close with the close block ONCE, when the skill finishes** — not on every turn. Ending
+without it is a defect, even when the phase converged cleanly:
+
+```
+[uscha · devloop · CLOSED]
+Produced: <files actually written, or "nothing">
+Blocks:   <what stands between here and the next phase, or "nothing">
+Next:     <the next action, and why it is that one>
+Run:      <the exact command or skill to invoke>
+```
+
+This is **not** the implementation handoff some skills also emit: that one is a prompt for
+whoever implements next, this one is navigation for the human operator, and both can appear.
+
+`Blocks` and `Next` are **derived from the state you just produced** — never copied from a
+fixed route, **including any `Flow:` line in this file**. Those lines are the nominal path;
+open ADR experiments, an unclosed spike, an unapproved golden or a red gate all change what
+genuinely comes next, and the derived answer wins. If the next phase cannot start yet, name it
+and say exactly what unblocks it.
+
+Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
+`Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+
 ## Non-negotiable principles
 
 1. **Converge, don't chase zero.** Block only on findings at or above the severity