@andresmassello/uscha 2.1.0 → 2.2.0

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

@@ -19,6 +19,8 @@ shape.** Your job is to interrogate until there is a shared system shape, and to
 the documents as you go — not to ask the human to design the system for you.
 
 <!-- uscha:orientation-block:begin -->
+<!-- uscha kit: 2.2.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
+
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -94,9 +96,16 @@ Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`,
    that makes discovery work: you propose (entities, endpoints, architecture, a default
    decision), the human confirms or corrects. Never dump a list of 20 questions, and
    never ask the human to supply structure you can propose yourself.
-2. **Explore instead of asking.** If a reference doc/URL/PDF, the existing codebase, or
-   an existing `CONTEXT.md`/`docs/adr/` can answer a question, read it first. Only ask
-   the human what genuinely requires their judgment.
+   **Close every question round item by item.** Before moving on, list what YOU decided in
+   that round and ask the human to confirm each one SEPARATELY — an "ok" over a twenty-item
+   summary is a rebound, not a decision, and it is exactly how a global default became a
+   tree-wide rename nobody had asked for. Write the answer onto the item as it arrives
+   (principle 6).
+2. **Explore instead of asking — ask for DECISIONS, never for INFORMATION** (ADR-044). If a
+   reference doc/URL/PDF, the existing codebase, or an existing `CONTEXT.md`/`docs/adr/`
+   can answer a question, read it first. The current version of a tracked file, what a
+   config says, whether a test exists: all information — READ it. Only ask the human what
+   genuinely requires their judgment.
 3. **Propose the shape.** From the idea + references, propose the core entities, the
    operation/API surface, and 2–3 architecture options with trade-offs. Walk the design
    tree branch by branch, resolving dependencies between decisions one at a time.
@@ -105,6 +114,14 @@ Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`,
    failed.
 5. **Write files lazily and inline.** Create a file only when you have something real to
    write, and update it the moment a decision crystallizes — don't batch to the end.
+6. **Mark what YOU decided: `origin: agent`.** Any acceptance criterion, ADR decision item
+   or HANDOFF rule that came from your proposal rather than from a human answer is written
+   with the marker on its own line — `(origin: agent)` while it is unconfirmed, and
+   `(origin: agent, confirmed: YYYY-MM-DD)` the moment the human confirms THAT item. Items
+   with no marker are human-origin by default; nothing already written is retro-tagged. An
+   unconfirmed item is NOT in scope: it is written down so it is visible, never so it is
+   agreed. `spec-check` names the unconfirmed ones with file:line (advisory — it changes no
+   exit code), and your close block lists them.
 
 ## Inputs
 
@@ -137,6 +154,17 @@ answer.
 1. **Purpose / value / why now.** What job does this remove? Cost of not doing it?
 2. **Domain model.** Propose the core entities and their relationships. ("From the domain
    I deduce these core entities: … do they work for you, or is one missing?")
+   Then ask, MANDATORY, before the round closes (ADR-046): **"what input comes from the REAL
+   world, and where is the corpus?"** In greenfield every test payload is invented by the agent
+   that writes the code, so a green suite can be silent about the inputs the world actually
+   produces — one field build shipped a parser that passed every test its author wrote and was
+   96.96 % right on the real corpus. Name the real-input surfaces (files, payloads, messages,
+   documents), ask WHERE a sample with its expected outputs can be obtained, and record the path
+   as `repos[R].corpus` in `uscha.config.json` so `qa_ledger.py corpus-run` can score it.
+   **No corpus on day 1 is not a blocker — it is a HIGH risk in `RISKS.md` with an OWNER and a
+   date.** Do not invent one: a corpus the agent authored is the same invented input this
+   question exists to expose. The percentage gates nothing until the project declares a budget
+   (`corpus_threshold`), which is round 10's decision, not the kit's.
 3. **Operation / API surface.** Propose the endpoints/operations and their
    contracts (idempotency, status codes).
 4. **Stack and lifecycle (MANDATORY — before any stack/architecture decision is
@@ -187,6 +215,18 @@ answer.
     `spike/*` branch and its ONLY legitimate output is an **ADR with lessons**
     (facts that feed the SPEC) — never mergeable code. The contract is executable:
     `phase --require pr-ready` refuses any `spike/*` branch, INV-GOLDEN-01 style.
+12. **Operability — who owns the RUNBOOK and the seed? (kit 2.2.0, ADR-048).** Ask it on
+    DAY 1, with your recommended answer, because the cheapest moment to decide it is before
+    anything is built and the most expensive is the week before go-live: who writes and owns
+    the **RUNBOOK** (start/boot, config, rollback, smoke), who owns the **seed/reset**
+    command that puts a fresh environment into a known state, and who owns the **release
+    workflow** that publishes the artifact. Record the answers as they crystallize:
+    `defaults.operability.seed_command` (or `repos[R].operability.seed_command`) in
+    `uscha.config.json`, and the RUNBOOK at `docs/RUNBOOK.md`. This is MEASURED, not
+    narrated — `qa_ledger.py operability --repo <REPO>` reads the four facts out of the tree,
+    and on risk profiles C/D/E a missing one is a BLOCKER, so a project that defers them
+    cannot reach `pr-ready`. Two field projects discovered all four in their last week; the
+    question costs one minute here.
 
 ## Files to write (lazily, inline)
 
@@ -210,7 +250,9 @@ answer.
   `Rollback / Supersede Criteria`.
 - **`ACCEPTANCE.md`** — Definition of Done as `- [ ]` checkboxes + success metrics. This
   is the file the readiness KPI measures downstream. Give EVERY criterion a stable
-  traceable ID: `- [ ] AC-01 — when X then Y` (sequential, never reused). Downstream,
+  traceable ID: `- [ ] AC-01 — when X then Y` (sequential, never reused); a criterion YOU
+  proposed also carries the `origin: agent` marker of principle 6 until the human confirms
+  it item by item. Downstream,
   a criterion only closes MEASURED when a green testcase carries its tag in the name
   (`test_ac1_x` / `testAC01X` / `"AC-01: ..."`) — write criteria so each one is
   coverable by at least one named test.
@@ -231,6 +273,18 @@ as explicit assumptions), every failure mode has defined behavior, out-of-scope
 explicit, and the DoD is checkable. State plainly that it converged, then write/finalize
 the package and the handoff.
 
+**The close block names what is still unconfirmed.** Before you emit it, run
+
+```bash
+python3 <path-to>/qa_ledger.py spec-check --spec SPEC.md --acceptance ACCEPTANCE.md
+```
+
+and copy the `~ origin: N agent-origin item(s) unconfirmed` list into `Blocks:` — one item
+per line, with its file and line. Those are the decisions the human still owes; converging
+with them silently in the package is the failure this marker exists to prevent. `Produced:`
+still lists the files. If the list is empty, `Blocks:` says `nothing` as it always did:
+silence and an explicit `nothing` are not the same fact.
+
 ## Handoff
 
 End with the implementation handoff (works for a human, an agent, or CI):

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

@@ -18,6 +18,8 @@ Paints the REAL state of the project at a glance. It does not narrate or estimat
 wires the JSON the engine emits into the template. Read-only.
 
 <!-- uscha:orientation-block:begin -->
+<!-- uscha kit: 2.2.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
+
 ## Orientation markers (non-negotiable)
 
 The operator must never have to ask "where am I?" or "what happens now?".

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

@@ -24,6 +24,8 @@ evidence-classed, content-addressed, and promoted to the contract only by a per-
 human verdict (ADR-013).**
 
 <!-- uscha:orientation-block:begin -->
+<!-- uscha kit: 2.2.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
+
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or

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

@@ -22,6 +22,8 @@ the grader — this skill just wraps the neutral prompt so Claude Code users get
 in one command. Never add Claude-specific behavior to the contract.
 
 <!-- uscha:orientation-block:begin -->
+<!-- uscha kit: 2.2.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
+
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or

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

@@ -19,7 +19,47 @@ skill (**pull** — one screen when the human asks), and the **mirador** (bird's
 HTML). This skill exists because some surfaces never show a statusline; the answer
 is the same data, printed in chat when requested.
 
+## Before the readout: are the installed skills older than the kit? (2.2.0)
+
+A field report found `~/.claude/skills/uscha-*` still on 1.54.0 while the kit in the repo was
+1.97.0. An entire discovery ran on prose three months stale and NOTHING said so, because a
+SKILL.md carried no version to compare. Since 2.2.0 every generated orientation block opens with
+`<!-- uscha kit: X.Y.Z ... -->`, so the comparison is mechanical. Do it FIRST, before the
+breadcrumb:
+
+1. Run the engine's own check — it reads the marker out of every installed `SKILL.md` and
+   compares it against the kit's `VERSION`:
+
+   ```
+   python <kit>/.claude/skills/uscha-devloop/qa_ledger.py doctor --json
+   ```
+
+   Read `skills_installed`: one row per install root the installer writes to (Claude
+   `~/.claude/skills/`, Codex `~/plugins/uscha/skills/`, pi `~/.agents/skills/`, and the other
+   Agent-Skills roots), each with `status`, `installed` and `kit`. `doctor` exits 0 whether or
+   not anything is outdated — this reports, it never gates.
+2. If any row reads `outdated`, print exactly ONE line ABOVE the breadcrumb, then continue
+   normally:
+
+   ```
+   SKILLS OUTDATED: installed 1.54.0 < kit 2.2.0 -- run `python install-uscha.py install --target claude`
+   ```
+
+   Where the installed block predates 2.2.0 and carries no marker at all, `installed` is null:
+   say `installed <no kit: marker, pre-2.2.0>` rather than inventing a version.
+3. `not installed` is NOT a finding — the kit installs one agent at a time, and six absent roots
+   are the normal shape of a healthy machine. Say nothing about them.
+
+Advisory, always: the line never blocks the readout, never changes a number, and the block below
+prints exactly as it would have. What it removes is the silence.
+
+Honest limit: an installed skill that predates 2.2.0 does not carry these instructions, so on
+that surface the warning cannot come from the skill itself. The `doctor` seam is the instrument
+that still works there — it runs from any kit checkout and reads the installs from outside.
+
 <!-- uscha:orientation-block:begin -->
+<!-- uscha kit: 2.2.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
+
 ## Orientation markers (non-negotiable)
 
 The operator must never have to ask "where am I?" or "what happens now?".

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

@@ -22,6 +22,8 @@ switch between at any time:
   coverage, known deferred issues.
 
 <!-- uscha:orientation-block:begin -->
+<!-- uscha kit: 2.2.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
+
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or

package/uscha-kit/templates/CLAUDE.md

@@ -33,6 +33,22 @@ each change lives in `SPEC.md` / `docs/adr/` / `ACCEPTANCE.md`, not here.
    forces a SPEC change, version it and go back to Ready.
 9. **Human gate.** Don't merge or release automatically. You stop at the PR; the merge and
    the smoke test in a real environment are decided by a person.
+10. **Ask for DECISIONS, never for INFORMATION — and mark what the agent decided.** What the
+   tree holds (the current version of a tracked file, what a config says, whether a test
+   exists) is READ, never asked. What the human has not decided is never entered silently:
+   every acceptance criterion, ADR decision item or `HANDOFF.md` rule the AGENT introduced
+   carries a trailing marker on its own line —
+
+    ```
+    - [ ] AC-12 — when X then Y. (origin: agent)
+    - [ ] AC-12 — when X then Y. (origin: agent, confirmed: 2026-09-07)
+    ```
+
+   Items with no marker are human-origin by default; nothing existing is retro-tagged. An
+   unconfirmed item is **not in scope**: it is confirmed ITEM BY ITEM, and a package-level
+   "ok" confirms none of them. `qa_ledger.py spec-check` names the unconfirmed ones with
+   file:line and `readiness` counts them on their own line — both advisory: they change no
+   exit code and cap no score.
 
 ## Truth hierarchy
 

package/uscha-kit/templates/CONSTITUTION.md

@@ -154,6 +154,51 @@ enforcing the record is the engine's job. It is never resolved by "working aroun
   asserts and **new dependencies** (the "0 deps without approval" rule, made visible —
   kit 1.30.0) = review (or `--strict`). For high blast-radius a checker
   uncorrelated with the maker (different family/profile) is also required — that is process, not code.
+- The **CI pipeline** is a FACT gate without an invariant of its own: `log-gate --kind ci
+  --verdict <pass|fail|not-run>` records what the pipeline actually did, with `--ref <run URL or
+  id>` as the receipt. A `fail` is a **BLOCKER** — readiness cap ≤ 65 and convergence blocked —
+  exactly like `gate-check`; a `not-run` records absence and leaves the last state standing.
+  `--verdict advisory` is REFUSED on it, as on every FACT gate. It is admitted to the closed
+  `--kind` vocabulary (ADR-014, INV-ADVISORY-01) because a pipeline either went green on a
+  commit or it did not: an LLM judgment does not become a gate by being important.
+- The **Field truth** invariant (greenfield) is measured by `qa_ledger.py corpus-run`: a JSONL
+  corpus of REAL inputs with their real expected outputs, run through the real command, scored
+  as hits/total. In greenfield every test payload was invented by the agent that wrote the code,
+  so a green suite proves nothing about the inputs the world produces — and `characterize` has
+  no answer there, because there is no old code to be the truth. **Advisory by default**: the
+  percentage is measured and gates nothing until the project declares a budget (`--threshold`,
+  else `repos[R].corpus_threshold`, else `defaults.corpus_threshold`). With one declared, a run
+  under it is a **BLOCKER** — readiness cap ≤ 65, convergence blocked — exactly like
+  `gate-check`, persisted as `gate:corpus`. A corpus that is missing, empty or malformed is
+  **exit 2** naming the line, never a scored 0 %. `log-gate --kind corpus` is the parity door
+  for a run measured elsewhere and it DOES accept `--verdict advisory` — the third and last kind
+  that may, because the check's own default mode is advisory; every other FACT kind still
+  refuses it. `--ac AC-nn` stamps criteria on the record: a criterion whose only evidence is a
+  corpus record closes MEASURED iff that record passed (ADR-046).
+- The **Smoke** invariant is measured by `qa_ledger.py smoke-ingest`: the smoke run is a
+  REPORT the project's own tool writes — `{"checks": [{"name": ..., "ok": true|false,
+  "status": ..., "latency_ms": ..., "evidence": ...}]}` — and never a sentence an agent
+  wrote. **Evidence is executed, not narrated**: "the endpoint answered 200" believed on an
+  agent's word is the failure mode this exists to remove, and it has already cost a release
+  (every run returned an empty list because the database had no rows). A failed check is a
+  **BLOCKER** — readiness cap ≤ 65, convergence blocked — persisted as `gate:smoke`, cleared
+  by a later clean report. A report that is missing, malformed, has no `checks`, holds an
+  EMPTY list, or carries a check without a `name` or a boolean `ok` is **exit 2** naming it:
+  a run that verified nothing is not a clean gate. `smoke` joins the closed `--kind`
+  vocabulary (ADR-014, INV-ADVISORY-01) as a FACT, and `--verdict advisory` is REFUSED on it
+  — a smoke check is binary, so there is no budget it could be measured against. A check
+  named `AC-nn ...` closes that criterion MEASURED when it is `ok` and its report passed; a
+  failed one vetoes it (ADR-047).
+- The **Operability** invariant is measured by `qa_ledger.py operability --repo R` (ADR-048): four
+  FACTS read out of the tree — a `.github/workflows` step running the repo's **configured** test
+  command, a workflow that publishes or attaches a release asset, a `RUNBOOK.md` naming
+  start/config/rollback/smoke, and a declared `seed_command` whose script is on disk. Its own exit
+  code is always 0; the verdict is persisted as `gate:operability` and the POSTURE is the risk
+  profile's — **advisory** on A/B (caps nothing, blocks nothing, never counted as `ok`) and a
+  **BLOCKER** on C/D/E, where `defaults.operability.gate` is `true`: readiness cap ≤ 65,
+  convergence blocked, and `phase --require pr-ready` refuses naming the missing check. A CI
+  system this engine does not read is reported `unknown`, never green and never red. Release,
+  reset and the RUNBOOK are part of done, not of the last week.
 - The **Golden (INV-GOLDEN-01)** invariant is measured by `qa_ledger.py golden-diff`: any `.received`
   that does not match its `.approved` (or is unapproved) = **DIVERGE**, cutting the chain before judgment-day.
   The agent does not touch `.approved` (ideally a `PreToolUse` hook makes it impossible).

package/uscha-kit/templates/docs/adr/README.md

@@ -13,6 +13,21 @@ machine-readable `lifecycle:` frontmatter block (component / version / eol / sou
 that `spec-check` compares against the SPEC's declared `go_live` (ADR-040). Advisory: it reports,
 it never gates.
 
+A **decision item the AGENT introduced** — one that came from the agent's proposal rather
+than from a human answer — carries a trailing marker on its own line:
+
+```
+- D-03 — the tree is renamed to English. (origin: agent)
+- D-03 — the tree is renamed to English. (origin: agent, confirmed: 2026-09-07)
+```
+
+Items with no marker are human-origin by default (nothing already written is retro-tagged).
+An unconfirmed item is NOT in scope: it is confirmed one item at a time, never by a
+package-level "ok". `spec-check` lists the unconfirmed ones with file:line and `readiness`
+counts them on a line of their own; both are advisory — no exit code, no score changes. A
+marker inside a fenced block or an inline code span (like the two above) is documentation and
+is skipped.
+
 `Status: Experiment` is for a bounded, reversible hypothesis that needs real feedback.
 It must include: Hypothesis, Feedback Signal, Review By or Review Trigger, Promote
 Criteria, and Rollback / Supersede Criteria. Missing/expired metadata is advisory in

package/uscha-kit/templates/scripts/smoke-report-example.json

@@ -0,0 +1,24 @@
+{
+  "checks": [
+    {
+      "name": "AC-01 the API serves /health under the real database",
+      "ok": true,
+      "status": 200,
+      "latency_ms": 6,
+      "evidence": "curl -sS http://localhost:8080/health -> {\"status\":\"UP\",\"db\":\"UP\"}"
+    },
+    {
+      "name": "the catalogue endpoint returns the seeded rows",
+      "ok": true,
+      "status": 200,
+      "latency_ms": 41,
+      "evidence": "GET /catalogue -> 128 items (the seed loads 128; an EMPTY list is the failure this check exists to catch)"
+    },
+    {
+      "name": "an unauthenticated write is rejected",
+      "ok": true,
+      "status": 401,
+      "evidence": "POST /catalogue with no token -> 401"
+    }
+  ]
+}

package/uscha-kit/uscha.config.json

@@ -1,6 +1,6 @@
 {
   "_comment": "COMPREHENSIVE REFERENCE, not a project config. Every knob the engine and the skills understand, at the kit's own value, so a human can read what can be declared. `uscha init` does NOT copy this file: it GENERATES a minimal project config, because a copied default is an explicit declaration and an explicit declaration outranks the preset named by defaults.risk_profile (ADR-001, as amended). Copy a block from here into your project only when you mean to override the engine default or the preset. NOTE: no version string may be written into this comment -- the release script requires exactly one occurrence of the version in this file (I3), and a second one refuses the next release.",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,
@@ -84,6 +84,11 @@
       "allow_paths": [],
       "gate": false
     },
+    "operability": {
+      "runbook": "docs/RUNBOOK.md",
+      "seed_command": "make seed",
+      "gate": false
+    },
     "execution_policy": {
       "default": {
         "tier": "standard",