@andresmassello/uscha 1.53.0 → 1.55.0

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.55.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,