@andresmassello/uscha 1.53.0 → 1.54.0

package/README.md

@@ -40,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.53.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
-[changelog](https://github.com/andresmassello/uscha/blob/main/uscha-kit/CHANGELOG-1.53.0.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.53.0",
+  "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

@@ -18,6 +18,34 @@ You convert a rough idea into a development-ready specification. You do this in
 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.

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

@@ -18,6 +18,34 @@ 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.

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

@@ -26,6 +26,34 @@ 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.

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

@@ -18,6 +18,34 @@ The human brings the idea, the constraints and the reference material. **You bri
 shape.** Your job is to interrogate until there is a shared system shape, and to write
 the documents as you go — not to ask the human to design the system for you.
 
+## 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 · discovery · 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 grill you ONE question at a time, each with my recommended answer. You decide.
+Output: CONTEXT.md · SPEC.md · docs/adr/*.md · ACCEPTANCE.md · RISKS.md
+Next:   `/uscha-devloop` builds against the package. No code until the package exists.
+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.

package/uscha-kit/.claude/skills/uscha-reverse-discovery/SKILL.md

@@ -18,6 +18,36 @@ disable-model-invocation: false
 opposite. The system already runs; its observable behavior is the ground truth. **You do
 not invent anything — you characterize what is already there, as facts.**
 
+## 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 · reverse-discovery · 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 EXTRACT facts from the system that already exists. I never invent its spec -- you write that reading my facts.
+Output: SYSTEM-MAP.md · DISCOVERY-SUMMARY.md -- endpoints, contracts, dependency graph,
+        module candidates. Facts only: the SPEC and the ADRs are yours to write.
+Next:   `/uscha-characterize` freezes current behavior and a HUMAN approves the golden;
+        only then do you write the migration SPEC, reading these facts + that golden.
+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.

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

@@ -21,6 +21,34 @@ contract + `qa_ledger.py rubric-ingest` (stdlib, runs anywhere). ANY runner can
 the grader — this skill just wraps the neutral prompt so Claude Code users get it
 in one command. Never add Claude-specific behavior to the contract.
 
+## 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 · rubric · 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 grade what tests cannot: conventions, error handling, API ergonomics, doc quality -- against your versioned RUBRIC.md.
+Output: a graded verdict ingested into the ledger (advisory unless you declared it a gate)
+Next:   back to `/uscha-devloop`, or the human gate if the loop already converged.
+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.

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

@@ -21,6 +21,34 @@ switch between at any time:
 - **Technical track** — architecture, modules, data flow, contracts, QA results,
   coverage, known deferred issues.
 
+## 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 · sysdoc · 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 build a two-track deck (commercial + technical) from what the ledger already measured.
+Output: a single self-contained HTML deck
+Next:   nothing -- this is a read-only artifact you share.
+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.

package/uscha-kit/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "uscha",
-  "version": "1.53.0",
+  "version": "1.54.0",
   "displayName": "Uscha",
   "description": "Spec-driven development for LLM coding agents: 9 skills (discovery, adr-refine, reverse-discovery, characterize, devloop, sysdoc, rubric, mirador, status) + a stdlib measurement engine (qa_ledger.py, 29 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
   "author": {

package/uscha-kit/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "uscha",
-  "version": "1.53.0",
+  "version": "1.54.0",
   "description": "Uscha spec-driven development methodology for coding agents. Includes npm/npx router.",
   "author": {
     "name": "Andres Massello",

package/uscha-kit/README.md

@@ -1,6 +1,6 @@
 # uscha-kit
 
-**Kit version:** v1.53.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.54.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
 
 Spec-driven orchestrator + multi-repo QA for Claude Code, with a deterministic ledger.
 **Nine skills** (`uscha-discovery`, `uscha-adr-refine`, `uscha-devloop`, `uscha-sysdoc`, `uscha-reverse-discovery`,

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 1.53.0
+uscha-kit 1.54.0

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

@@ -18,6 +18,34 @@ You convert a rough idea into a development-ready specification. You do this in
 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.

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

@@ -18,6 +18,34 @@ 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.

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

@@ -26,6 +26,34 @@ 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.

package/uscha-kit/skills/uscha-discovery/SKILL.md

@@ -18,6 +18,34 @@ The human brings the idea, the constraints and the reference material. **You bri
 shape.** Your job is to interrogate until there is a shared system shape, and to write
 the documents as you go — not to ask the human to design the system for you.
 
+## 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 · discovery · 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 grill you ONE question at a time, each with my recommended answer. You decide.
+Output: CONTEXT.md · SPEC.md · docs/adr/*.md · ACCEPTANCE.md · RISKS.md
+Next:   `/uscha-devloop` builds against the package. No code until the package exists.
+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.

package/uscha-kit/skills/uscha-reverse-discovery/SKILL.md

@@ -18,6 +18,36 @@ disable-model-invocation: false
 opposite. The system already runs; its observable behavior is the ground truth. **You do
 not invent anything — you characterize what is already there, as facts.**
 
+## 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 · reverse-discovery · 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 EXTRACT facts from the system that already exists. I never invent its spec -- you write that reading my facts.
+Output: SYSTEM-MAP.md · DISCOVERY-SUMMARY.md -- endpoints, contracts, dependency graph,
+        module candidates. Facts only: the SPEC and the ADRs are yours to write.
+Next:   `/uscha-characterize` freezes current behavior and a HUMAN approves the golden;
+        only then do you write the migration SPEC, reading these facts + that golden.
+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.

package/uscha-kit/skills/uscha-rubric/SKILL.md

@@ -21,6 +21,34 @@ contract + `qa_ledger.py rubric-ingest` (stdlib, runs anywhere). ANY runner can
 the grader — this skill just wraps the neutral prompt so Claude Code users get it
 in one command. Never add Claude-specific behavior to the contract.
 
+## 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 · rubric · 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 grade what tests cannot: conventions, error handling, API ergonomics, doc quality -- against your versioned RUBRIC.md.
+Output: a graded verdict ingested into the ledger (advisory unless you declared it a gate)
+Next:   back to `/uscha-devloop`, or the human gate if the loop already converged.
+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.

package/uscha-kit/skills/uscha-sysdoc/SKILL.md

@@ -21,6 +21,34 @@ switch between at any time:
 - **Technical track** — architecture, modules, data flow, contracts, QA results,
   coverage, known deferred issues.
 
+## 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 · sysdoc · 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 build a two-track deck (commercial + technical) from what the ledger already measured.
+Output: a single self-contained HTML deck
+Next:   nothing -- this is a read-only artifact you share.
+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.

package/uscha-kit/uscha.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.53.0",
+  "version": "1.54.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,