@andresmassello/uscha 2.2.0 → 2.4.0

package/README.md

@@ -42,9 +42,10 @@ npx --yes @andresmassello/uscha@latest init
 
 Requires **Python 3.8+** on the machine (the engine is Python stdlib — no pip installs, no
 runtime dependencies). The npm package is a thin router; the canonical installer is
-`uscha-kit/install-uscha.py`.
+`uscha-kit/install-uscha.py`. `init` also writes a minimal, per-repo-type `.gitignore` when the
+project has none (kit 2.4.0) — it never lists `reports/`, the ledger's own evidence.
 
-**Kit v2.2.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v2.4.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
 [changelog](https://github.com/andresmassello/uscha/blob/main/uscha-kit/CHANGELOG.md)
 (the per-release changelogs live in the repo, not in the npm tarball)
 
@@ -218,6 +219,11 @@ that same-model reruns differ structurally about as much as different models do
 `NOISY`) — so one earlier variance narrative was **retracted**. Every claim above is a subcommand
 you can run; every unmeasured part is labeled. That honesty is the method applied to itself.
 
+Every verdict above is tied to a named criterion, and every one a human judged is tied to the
+person who signed it — the ledger itself, `bench-curate --human` for the compiled artifacts, and
+the `origin: agent` markers that record which specification items the agent proposed versus the
+human decided.
+
 → The full thesis, with before/after diagrams and the REAL vs VISION vs REJECTED table:
 **[uscha.dev/diamond](https://uscha.dev/diamond)** · the mechanism, in three diagrams:
 **[uscha.dev/how](https://uscha.dev/how)**

package/package.json

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

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

@@ -19,7 +19,7 @@ phases. **You are NOT a generator. You are an interrogator that distills.** The
 is in the questions, not in agreeing.
 
 <!-- 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) -->
+<!-- uscha kit: 2.4.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)
 
@@ -54,6 +54,14 @@ block onward, derived state wins.
 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.
 
+**No statusline (kit 2.4.0): the visible reply IS the statusline.** On a surface with no live
+statusline — Codex, pi, a plain terminal — these markers are the only signal the operator gets,
+so they MUST appear in the visible reply text, never only inside a collapsed tool-call log the
+operator may not expand. On such a surface, the FINAL message of every turn STARTS with the
+compact `uscha-status` block (derived phase · loop · measured acceptance · next criterion, read
+from the ledger — see the `uscha-status` skill), immediately before the breadcrumb/close marker
+below.
+
 **Open every turn with a breadcrumb**, then the content:
 
 `[uscha · adr-refine · <step> → <target>]`

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

@@ -19,7 +19,7 @@ what the code DOES, mechanically, by running it — never what it should do.** Y
 the capture harness; you may NOT create, rename, or edit any `.approved` file.
 
 <!-- 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) -->
+<!-- uscha kit: 2.4.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)
 
@@ -54,6 +54,14 @@ block onward, derived state wins.
 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.
 
+**No statusline (kit 2.4.0): the visible reply IS the statusline.** On a surface with no live
+statusline — Codex, pi, a plain terminal — these markers are the only signal the operator gets,
+so they MUST appear in the visible reply text, never only inside a collapsed tool-call log the
+operator may not expand. On such a surface, the FINAL message of every turn STARTS with the
+compact `uscha-status` block (derived phase · loop · measured acceptance · next criterion, read
+from the ledger — see the `uscha-status` skill), immediately before the breadcrumb/close marker
+below.
+
 **Open every turn with a breadcrumb**, then the content:
 
 `[uscha · characterize · <step> → <target>]`

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

@@ -27,7 +27,7 @@ artifacts; these can block) and **self-reported** agent counts (log-step — nar
 recorded for the retrospective; a measured red always overrides a narrated green).
 
 <!-- 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) -->
+<!-- uscha kit: 2.4.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)
 
@@ -62,6 +62,14 @@ block onward, derived state wins.
 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.
 
+**No statusline (kit 2.4.0): the visible reply IS the statusline.** On a surface with no live
+statusline — Codex, pi, a plain terminal — these markers are the only signal the operator gets,
+so they MUST appear in the visible reply text, never only inside a collapsed tool-call log the
+operator may not expand. On such a surface, the FINAL message of every turn STARTS with the
+compact `uscha-status` block (derived phase · loop · measured acceptance · next criterion, read
+from the ledger — see the `uscha-status` skill), immediately before the breadcrumb/close marker
+below.
+
 **Open every turn with a breadcrumb**, then the content:
 
 `[uscha · devloop · <step> → <target>]`
@@ -239,15 +247,22 @@ For each repo, decide whether a safety net exists before any refactoring:
 
 ```bash
 python3 $QL snapshot --repo <REPO> --phase pre
-python3 $QL check-coverage --repo <REPO>     # exit 0 = OK, exit 1 = BELOW threshold
+python3 $QL check-coverage --repo <REPO>
+# exit 0 = OK, exit 1 = BELOW threshold (a real report), exit 2 = UNMEASURED (no report)
 ```
 
 - **Coverage >= threshold:** the existing suite is the guardrail. Skip to Phase 2.
-- **Coverage < threshold (or no report):** write **characterization / contract tests
-  at the boundary** (public API, endpoints, input→output behavior) — NOT internals.
+- **Coverage < threshold (a real report, exit 1):** write **characterization / contract
+  tests at the boundary** (public API, endpoints, input→output behavior) — NOT internals.
   These must survive refactoring. The ADR acceptance criteria are the spec for these.
   **Have the human review these tests before trusting them as a gate** — a test that
-  passes for the wrong reason poisons the whole loop.
+  passes for the wrong reason poisons the whole loop. Characterization tests are for
+  EXISTING code nobody has tested yet, not for code that has not been run at all.
+- **UNMEASURED (exit 2, no report found):** on a greenfield repo this means the test
+  command has never been run with coverage — not that the code failed a test. Produce
+  the report first: run the repo's test command with coverage, then re-run
+  `check-coverage`. Only if a real report then shows coverage below threshold does the
+  characterization path above apply.
 - **Migration/legacy (profile E): capture the golden BEFORE touching anything.** Run
   the `uscha-characterize` skill (or `uscha-reverse-discovery` for a whole-system map first): it
   executes the ORIGINAL code against a real input corpus, emits `.received` fixtures,
@@ -521,6 +536,13 @@ python3 $QL snapshot --repo <REPO> --phase post   # for every repo + integration
 
 Full suite must be green and coverage at/above threshold before proceeding.
 
+**`reports/` is EVIDENCE, not build noise (kit 2.4.0).** JUnit XML, coverage reports
+(JaCoCo/Cobertura/lcov/go cover), and `reports/smoke.json` are what `snapshot`,
+`check-coverage` and `smoke-ingest` read to turn "we ran tests" into a measured fact.
+Keep it, commit it, and never delete or `.gitignore` it to get a clean-looking commit —
+a repo with no `reports/` reads UNMEASURED, not "clean". (`uscha init`'s generated
+`.gitignore`, kit 2.4.0, never lists `reports/` for exactly this reason.)
+
 ## Phase 5b — Rebuild test (optional; risk profile C+/E or periodic CI)
 
 Completeness of the SPEC, not correctness of the build: is the spec package enough to
@@ -549,6 +571,10 @@ is a spec gap, not a code bug.
 python3 $QL phase --repo <REPO> --require pr-ready   # exit 1 = the facts say no
 ```
 
+`pr-ready` is a PHASE VALUE, not a subcommand — there is no `qa_ledger.py pr-ready`.
+It is always read through `phase --repo <REPO> --require pr-ready` as shown above
+(`qa_ledger.py pr-ready` alone is an argparse error).
+
 The state is COMPUTED from the ledger (converged + green tests + zero
 BLOCKER/CRITICAL + no open escalation), never self-declared — if it exits 1, the
 output lists exactly which facts are missing; do NOT open the PR, close the gap.
@@ -664,6 +690,16 @@ count, plateau flag per repo — to `ledger["measured"]` (what the statusline re
 Without it the trail starves: the mirador shows "no history yet" and the statusline
 falls back to counting checkboxes. Recording is append-only facts, never a gate.
 
+**Tick measured-but-unchecked boxes before closing (kit 2.4.0).** `readiness` reports
+`measured_unchecked` (`--json`) / a `· measured but unticked: AC-...` line (default view):
+AC-IDs the ledger already closed with a green, name-tagged test but whose `ACCEPTANCE.md`
+checkbox is still `[ ]`. For every ID it lists, flip that box to `[x]` in `ACCEPTANCE.md` —
+the engine measured it; ticking is bookkeeping, never the other way round. Then re-run
+`readiness` and confirm the list is empty before the close block. This is ONE-DIRECTIONAL:
+never tick a box the ledger has not closed (that would be narrating, and `readiness`
+already reports narrated-but-unmeasured boxes separately as `narrated_only`) — a tick
+without a green test stays narrated-only, not measured.
+
 Right after readiness, run the spec-maintenance advisory (kit 1.66.0):
 
 ```bash

package/uscha-kit/.claude/skills/uscha-devloop/qa_ledger.py

@@ -19,7 +19,8 @@ Stdlib only. Python 3.8+.
 Usage (see `--help` on each subcommand):
   qa_ledger.py init        --config uscha.config.json [--out QA-LEDGER.json]
   qa_ledger.py snapshot    --repo backend-api    [--phase pre|post]
-  qa_ledger.py check-coverage --repo backend-api [--threshold 60]   # exit 0 >=, 1 <
+  qa_ledger.py check-coverage --repo backend-api [--threshold 60]
+                                        # exit 0 >= threshold, 1 < threshold, 2 UNMEASURED (no report)
   qa_ledger.py log-step    --repo backend-api --tool code-review --iteration 1 \
                            --reported 12 --gated-reported 4 --fixed 9 \
                            --deferred 2 --suppressed 1 --tests-passed true \
@@ -399,6 +400,24 @@ def coverage(repo_path, repo_type):
     return flutter_coverage(repo_path)
 
 
+_COVERAGE_REPORT_HINT = {
+    "ant": "target/site/jacoco/jacoco.xml (or -aggregate)",
+    "maven": "target/site/jacoco/jacoco.xml (or -aggregate)",
+    "gradle": "target/site/jacoco/jacoco.xml (or -aggregate)",
+    "python": "coverage.xml or reports/coverage.xml (Cobertura)",
+    "rust": "coverage.xml or reports/coverage.xml (Cobertura)",
+    "dotnet": "coverage.xml or reports/coverage.xml (Cobertura)",
+    "cpp": "coverage.xml or reports/coverage.xml (Cobertura)",
+    "go": "coverage.out, cover.out or reports/coverage.out",
+}
+
+
+def _coverage_report_hint(repo_type):
+    """Human-readable hint of where `coverage()` looked, for an UNMEASURED message --
+    never invents a single path, since several report types glob multiple locations."""
+    return _COVERAGE_REPORT_HINT.get(repo_type, "coverage/lcov.info")
+
+
 # --------------------------------------------------------------------------- #
 # measurement: test counts
 # --------------------------------------------------------------------------- #
@@ -2404,15 +2423,18 @@ def cmd_check_coverage(args):
         threshold = ledger["config"].get("defaults", {}).get("coverage_threshold", 60)
     cov = coverage(cfg["path"], cfg["type"])
     pct = cov["pct"]
+    if not cov["report_found"]:
+        # No coverage report at all is UNMEASURED, not a below-threshold verdict: on a
+        # greenfield repo pct 0.0 + report_found False means no report was ever produced,
+        # never that the code was tested and failed. Fail closed (exit 2) -- distinct from
+        # exit 1 (a real report that reads below threshold) -- so callers do not confuse
+        # "never measured" with "measured and failing".
+        print(f"[qa_ledger] {args.repo}: coverage UNMEASURED -- no coverage report found "
+              f"(looked for {_coverage_report_hint(cfg['type'])}). "
+              f"Run the test command with coverage first to produce a report.")
+        sys.exit(2)
     below = pct < threshold
     state = "BELOW" if below else "OK"
-    if not cov["report_found"]:
-        # No coverage report at all == treat as below threshold (needs char tests),
-        # but flag loudly so the skill knows tests simply haven't been run yet.
-        print(f"[qa_ledger] {args.repo}: NO coverage report found "
-              f"(threshold {threshold}%) -> treat as BELOW. "
-              f"Run the test command first if a report was expected.")
-        sys.exit(1)
     print(f"[qa_ledger] {args.repo}: coverage {pct}% vs threshold {threshold}% -> {state}")
     sys.exit(1 if below else 0)
 

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

@@ -19,7 +19,7 @@ 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) -->
+<!-- uscha kit: 2.4.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)
 
@@ -54,6 +54,14 @@ block onward, derived state wins.
 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.
 
+**No statusline (kit 2.4.0): the visible reply IS the statusline.** On a surface with no live
+statusline — Codex, pi, a plain terminal — these markers are the only signal the operator gets,
+so they MUST appear in the visible reply text, never only inside a collapsed tool-call log the
+operator may not expand. On such a surface, the FINAL message of every turn STARTS with the
+compact `uscha-status` block (derived phase · loop · measured acceptance · next criterion, read
+from the ledger — see the `uscha-status` skill), immediately before the breadcrumb/close marker
+below.
+
 **Open every turn with a breadcrumb**, then the content:
 
 `[uscha · discovery · <step> → <target>]`
@@ -112,6 +120,12 @@ Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`,
 4. **Grill, don't agree.** Surface contradictions, fuzzy/overloaded terms, missing
    failure modes and unstated constraints. A discovery where you agreed with everything
    failed.
+   Two habits, both advisory (unmeasured, kept because they are cheap): **every magnitude
+   carries a number or a range** -- "many tasks", "fast", "large files" are not scope;
+   "20 to 100 tasks", "under 200 ms", "up to 50 MB" are -- and **rules are written as
+   constraints, not wishes**: "no partial implementations, no TODO left in the diff" is
+   checkable; "remember to finish things" is not. A magnitude without a number and a rule
+   without a boundary are questions you still owe the human.
 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
@@ -238,7 +252,8 @@ answer.
   you proposed and the human approved). Distinct from the glossary: this is the model, not
   the vocabulary.
 - **`SPEC.md`** — objective/value, risk, scope/out-of-scope, behavior,
-  inputs/outputs/errors, acceptance, test plan, operation, rollback.
+  inputs/outputs/errors, acceptance, test plan, operation, rollback. Magnitudes with numbers
+  or ranges; rules as constraints with a boundary, never as reminders.
 - **`docs/adr/ADR-NNN-<slug>.md`** — one per durable decision. Format: Status
   (proposed/accepted/**experiment**/deprecated/superseded) · Context · Alternatives · Decision ·
   Consequences · **Implementation Plan** (affected paths, patterns to follow, tests to

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

@@ -18,7 +18,7 @@ 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) -->
+<!-- uscha kit: 2.4.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
 
 ## Orientation markers (non-negotiable)
 
@@ -28,6 +28,10 @@ This skill is a **one-shot read-only readout**: its block IS the answer. It ther
 take the conversational close block — that would be exactly the padding this skill forbids.
 It carries the two minimal markers instead.
 
+**No statusline (kit 2.4.0): the visible reply IS the statusline.** On a surface with no live
+statusline — Codex, pi, a plain terminal — this readout IS the operator's only signal, so it
+MUST appear in the visible reply text, never only inside a collapsed tool-call log.
+
 **Open with a breadcrumb:**
 
 `[uscha · mirador · step <n> → <target>]`

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

@@ -24,7 +24,7 @@ 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) -->
+<!-- uscha kit: 2.4.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)
 
@@ -61,6 +61,14 @@ block onward, derived state wins.
 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.
 
+**No statusline (kit 2.4.0): the visible reply IS the statusline.** On a surface with no live
+statusline — Codex, pi, a plain terminal — these markers are the only signal the operator gets,
+so they MUST appear in the visible reply text, never only inside a collapsed tool-call log the
+operator may not expand. On such a surface, the FINAL message of every turn STARTS with the
+compact `uscha-status` block (derived phase · loop · measured acceptance · next criterion, read
+from the ledger — see the `uscha-status` skill), immediately before the breadcrumb/close marker
+below.
+
 **Open every turn with a breadcrumb**, then the content:
 
 `[uscha · reverse-discovery · <step> → <target>]`

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

@@ -22,7 +22,7 @@ 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) -->
+<!-- uscha kit: 2.4.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)
 
@@ -57,6 +57,14 @@ block onward, derived state wins.
 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.
 
+**No statusline (kit 2.4.0): the visible reply IS the statusline.** On a surface with no live
+statusline — Codex, pi, a plain terminal — these markers are the only signal the operator gets,
+so they MUST appear in the visible reply text, never only inside a collapsed tool-call log the
+operator may not expand. On such a surface, the FINAL message of every turn STARTS with the
+compact `uscha-status` block (derived phase · loop · measured acceptance · next criterion, read
+from the ledger — see the `uscha-status` skill), immediately before the breadcrumb/close marker
+below.
+
 **Open every turn with a breadcrumb**, then the content:
 
 `[uscha · rubric · <step> → <target>]`

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

@@ -58,7 +58,7 @@ that surface the warning cannot come from the skill itself. The `doctor` seam is
 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) -->
+<!-- uscha kit: 2.4.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
 
 ## Orientation markers (non-negotiable)
 
@@ -68,6 +68,10 @@ This skill is a **one-shot read-only readout**: its block IS the answer. It ther
 take the conversational close block — that would be exactly the padding this skill forbids.
 It carries the two minimal markers instead.
 
+**No statusline (kit 2.4.0): the visible reply IS the statusline.** On a surface with no live
+statusline — Codex, pi, a plain terminal — this readout IS the operator's only signal, so it
+MUST appear in the visible reply text, never only inside a collapsed tool-call log.
+
 **Open with a breadcrumb:**
 
 `[uscha · status · step <n> → <target>]`

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

@@ -22,7 +22,7 @@ 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) -->
+<!-- uscha kit: 2.4.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)
 
@@ -57,6 +57,14 @@ block onward, derived state wins.
 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.
 
+**No statusline (kit 2.4.0): the visible reply IS the statusline.** On a surface with no live
+statusline — Codex, pi, a plain terminal — these markers are the only signal the operator gets,
+so they MUST appear in the visible reply text, never only inside a collapsed tool-call log the
+operator may not expand. On such a surface, the FINAL message of every turn STARTS with the
+compact `uscha-status` block (derived phase · loop · measured acceptance · next criterion, read
+from the ledger — see the `uscha-status` skill), immediately before the breadcrumb/close marker
+below.
+
 **Open every turn with a breadcrumb**, then the content:
 
 `[uscha · sysdoc · <step> → <target>]`

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

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "uscha",
-  "version": "2.2.0",
+  "version": "2.4.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, 56 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": "2.2.0",
+  "version": "2.4.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:** v2.2.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v2.4.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`,
@@ -532,6 +532,11 @@ of six. Every other knob is absent on purpose and resolves to the engine default
 `uscha-kit/uscha.config.json` is the **comprehensive reference** — every knob at the kit's
 value, to read and copy from — and is no longer copied into projects.
 
+`uscha init` also writes a minimal `.gitignore` (kit 2.4.0), scoped to the detected repo type
+(`__pycache__/`, `*.pyc`, `.pytest_cache/`, `.coverage` for python; `node_modules/` for node; and
+so on) — never `reports/`, which is the ledger's own evidence (JUnit, coverage, smoke). An
+existing `.gitignore` is always left untouched, even with `--force`.
+
 That matters because of one rule: **a knob you declare > the preset named by
 `defaults.risk_profile` > the engine default**. A copied default is an explicit declaration, so
 a project holding the whole reference leaves its risk profile nothing to decide.

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 2.2.0
+uscha-kit 2.4.0

package/uscha-kit/install-uscha.py

@@ -805,6 +805,37 @@ def project_config_bytes(repo):
     return (json.dumps(config, indent=2, ensure_ascii=False) + "\n").encode("utf-8")
 
 
+# Minimal, per repo type (kit 2.4.0). Deliberately tiny: build/cache artifacts a fresh
+# clone regenerates, never source. `reports/` (JUnit, coverage, smoke) is EVIDENCE the
+# ledger reads -- it must NEVER appear here, in this list or any other repo's.
+GITIGNORE_PATTERNS = {
+    "python": ("__pycache__/", "*.pyc", ".pytest_cache/", ".coverage"),
+    "node": ("node_modules/",),
+    "flutter": (".dart_tool/", "build/"),
+    "maven": ("target/",),
+    "gradle": ("build/", ".gradle/"),
+    "rust": ("target/",),
+    "swift": (".build/",),
+    "cpp": ("build/",),
+    "dotnet": ("bin/", "obj/"),
+}
+
+
+def gitignore_bytes(repo_type):
+    """The project's .gitignore, generated for a RECOGNISED repo type only -- like
+    `detect_repo_type`, this never guesses. `None` means `init` writes nothing (the
+    human declares one by hand). LF explicitly, like every other artifact `init` writes,
+    so the same bytes are produced on every run for the same repo type."""
+    patterns = GITIGNORE_PATTERNS.get(repo_type)
+    if not patterns:
+        return None
+    lines = ["# Minimal .gitignore, generated by `uscha init` for a %s repo." % repo_type,
+              "# reports/ is evidence the ledger reads (JUnit, coverage, smoke) -- never "
+              "ignored here."]
+    lines.extend(patterns)
+    return ("\n".join(lines) + "\n").encode("utf-8")
+
+
 def cmd_init(args):
     repo, operations, conflicts = Path(args.repo).expanduser().resolve(), [], []
     # (source path or None, payload bytes or None, target): the config is generated, the rest
@@ -845,6 +876,25 @@ def cmd_init(args):
                 target.write_bytes(want)
             else:
                 shutil.copy2(source, target)
+    # .gitignore (kit 2.4.0): written ONLY when the repo has none yet, for a recognised
+    # repo type. Unlike the templates above, an EXISTING .gitignore is never a conflict and
+    # is never touched even with --force -- it is the human's file, `init` only fills the
+    # gap on a repo that has none. That also makes a second `init` report "unchanged".
+    gi_target = repo / ".gitignore"
+    gi_bytes = gitignore_bytes(detect_repo_type(repo))
+    gitignore_wrote = False
+    if gi_bytes is not None:
+        if gi_target.exists():
+            operations.append({"action": "unchanged", "path": str(gi_target),
+                                "note": "existing .gitignore left untouched"})
+        elif args.dry_run:
+            operations.append({"action": "copy-file", "path": str(gi_target),
+                                "source": "<generated>"})
+        else:
+            gi_target.write_bytes(gi_bytes)
+            operations.append({"action": "copy-file", "path": str(gi_target),
+                                "source": "<generated>"})
+            gitignore_wrote = True
     # wire the statusline (kit 1.46.0): merge statusLine + Stop hook into the project's
     # settings.json so the user never edits it by hand -- never clobbering existing keys.
     sl_ops, sl_wrote, sl_conflicts = _wire_statusline_settings(repo, args.force, args.dry_run)
@@ -856,6 +906,8 @@ def cmd_init(args):
     else:
         status = "planned" if args.dry_run else "initialized"
     wrote = [str(t) for _, _, t in copies] if not args.dry_run else []
+    if gitignore_wrote:
+        wrote.append(str(gi_target))
     if sl_wrote:
         wrote.append(str(repo / ".claude" / "settings.json"))
     emit({"status": status, "dry_run": args.dry_run, "repo": str(repo),

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

@@ -19,7 +19,7 @@ phases. **You are NOT a generator. You are an interrogator that distills.** The
 is in the questions, not in agreeing.
 
 <!-- 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) -->
+<!-- uscha kit: 2.4.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)
 
@@ -54,6 +54,14 @@ block onward, derived state wins.
 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.
 
+**No statusline (kit 2.4.0): the visible reply IS the statusline.** On a surface with no live
+statusline — Codex, pi, a plain terminal — these markers are the only signal the operator gets,
+so they MUST appear in the visible reply text, never only inside a collapsed tool-call log the
+operator may not expand. On such a surface, the FINAL message of every turn STARTS with the
+compact `uscha-status` block (derived phase · loop · measured acceptance · next criterion, read
+from the ledger — see the `uscha-status` skill), immediately before the breadcrumb/close marker
+below.
+
 **Open every turn with a breadcrumb**, then the content:
 
 `[uscha · adr-refine · <step> → <target>]`

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

@@ -19,7 +19,7 @@ what the code DOES, mechanically, by running it — never what it should do.** Y
 the capture harness; you may NOT create, rename, or edit any `.approved` file.
 
 <!-- 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) -->
+<!-- uscha kit: 2.4.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)
 
@@ -54,6 +54,14 @@ block onward, derived state wins.
 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.
 
+**No statusline (kit 2.4.0): the visible reply IS the statusline.** On a surface with no live
+statusline — Codex, pi, a plain terminal — these markers are the only signal the operator gets,
+so they MUST appear in the visible reply text, never only inside a collapsed tool-call log the
+operator may not expand. On such a surface, the FINAL message of every turn STARTS with the
+compact `uscha-status` block (derived phase · loop · measured acceptance · next criterion, read
+from the ledger — see the `uscha-status` skill), immediately before the breadcrumb/close marker
+below.
+
 **Open every turn with a breadcrumb**, then the content:
 
 `[uscha · characterize · <step> → <target>]`

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

@@ -27,7 +27,7 @@ artifacts; these can block) and **self-reported** agent counts (log-step — nar
 recorded for the retrospective; a measured red always overrides a narrated green).
 
 <!-- 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) -->
+<!-- uscha kit: 2.4.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)
 
@@ -62,6 +62,14 @@ block onward, derived state wins.
 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.
 
+**No statusline (kit 2.4.0): the visible reply IS the statusline.** On a surface with no live
+statusline — Codex, pi, a plain terminal — these markers are the only signal the operator gets,
+so they MUST appear in the visible reply text, never only inside a collapsed tool-call log the
+operator may not expand. On such a surface, the FINAL message of every turn STARTS with the
+compact `uscha-status` block (derived phase · loop · measured acceptance · next criterion, read
+from the ledger — see the `uscha-status` skill), immediately before the breadcrumb/close marker
+below.
+
 **Open every turn with a breadcrumb**, then the content:
 
 `[uscha · devloop · <step> → <target>]`
@@ -239,15 +247,22 @@ For each repo, decide whether a safety net exists before any refactoring:
 
 ```bash
 python3 $QL snapshot --repo <REPO> --phase pre
-python3 $QL check-coverage --repo <REPO>     # exit 0 = OK, exit 1 = BELOW threshold
+python3 $QL check-coverage --repo <REPO>
+# exit 0 = OK, exit 1 = BELOW threshold (a real report), exit 2 = UNMEASURED (no report)
 ```
 
 - **Coverage >= threshold:** the existing suite is the guardrail. Skip to Phase 2.
-- **Coverage < threshold (or no report):** write **characterization / contract tests
-  at the boundary** (public API, endpoints, input→output behavior) — NOT internals.
+- **Coverage < threshold (a real report, exit 1):** write **characterization / contract
+  tests at the boundary** (public API, endpoints, input→output behavior) — NOT internals.
   These must survive refactoring. The ADR acceptance criteria are the spec for these.
   **Have the human review these tests before trusting them as a gate** — a test that
-  passes for the wrong reason poisons the whole loop.
+  passes for the wrong reason poisons the whole loop. Characterization tests are for
+  EXISTING code nobody has tested yet, not for code that has not been run at all.
+- **UNMEASURED (exit 2, no report found):** on a greenfield repo this means the test
+  command has never been run with coverage — not that the code failed a test. Produce
+  the report first: run the repo's test command with coverage, then re-run
+  `check-coverage`. Only if a real report then shows coverage below threshold does the
+  characterization path above apply.
 - **Migration/legacy (profile E): capture the golden BEFORE touching anything.** Run
   the `uscha-characterize` skill (or `uscha-reverse-discovery` for a whole-system map first): it
   executes the ORIGINAL code against a real input corpus, emits `.received` fixtures,
@@ -521,6 +536,13 @@ python3 $QL snapshot --repo <REPO> --phase post   # for every repo + integration
 
 Full suite must be green and coverage at/above threshold before proceeding.
 
+**`reports/` is EVIDENCE, not build noise (kit 2.4.0).** JUnit XML, coverage reports
+(JaCoCo/Cobertura/lcov/go cover), and `reports/smoke.json` are what `snapshot`,
+`check-coverage` and `smoke-ingest` read to turn "we ran tests" into a measured fact.
+Keep it, commit it, and never delete or `.gitignore` it to get a clean-looking commit —
+a repo with no `reports/` reads UNMEASURED, not "clean". (`uscha init`'s generated
+`.gitignore`, kit 2.4.0, never lists `reports/` for exactly this reason.)
+
 ## Phase 5b — Rebuild test (optional; risk profile C+/E or periodic CI)
 
 Completeness of the SPEC, not correctness of the build: is the spec package enough to
@@ -549,6 +571,10 @@ is a spec gap, not a code bug.
 python3 $QL phase --repo <REPO> --require pr-ready   # exit 1 = the facts say no
 ```
 
+`pr-ready` is a PHASE VALUE, not a subcommand — there is no `qa_ledger.py pr-ready`.
+It is always read through `phase --repo <REPO> --require pr-ready` as shown above
+(`qa_ledger.py pr-ready` alone is an argparse error).
+
 The state is COMPUTED from the ledger (converged + green tests + zero
 BLOCKER/CRITICAL + no open escalation), never self-declared — if it exits 1, the
 output lists exactly which facts are missing; do NOT open the PR, close the gap.
@@ -664,6 +690,16 @@ count, plateau flag per repo — to `ledger["measured"]` (what the statusline re
 Without it the trail starves: the mirador shows "no history yet" and the statusline
 falls back to counting checkboxes. Recording is append-only facts, never a gate.
 
+**Tick measured-but-unchecked boxes before closing (kit 2.4.0).** `readiness` reports
+`measured_unchecked` (`--json`) / a `· measured but unticked: AC-...` line (default view):
+AC-IDs the ledger already closed with a green, name-tagged test but whose `ACCEPTANCE.md`
+checkbox is still `[ ]`. For every ID it lists, flip that box to `[x]` in `ACCEPTANCE.md` —
+the engine measured it; ticking is bookkeeping, never the other way round. Then re-run
+`readiness` and confirm the list is empty before the close block. This is ONE-DIRECTIONAL:
+never tick a box the ledger has not closed (that would be narrating, and `readiness`
+already reports narrated-but-unmeasured boxes separately as `narrated_only`) — a tick
+without a green test stays narrated-only, not measured.
+
 Right after readiness, run the spec-maintenance advisory (kit 1.66.0):
 
 ```bash

package/uscha-kit/skills/uscha-devloop/qa_ledger.py

@@ -19,7 +19,8 @@ Stdlib only. Python 3.8+.
 Usage (see `--help` on each subcommand):
   qa_ledger.py init        --config uscha.config.json [--out QA-LEDGER.json]
   qa_ledger.py snapshot    --repo backend-api    [--phase pre|post]
-  qa_ledger.py check-coverage --repo backend-api [--threshold 60]   # exit 0 >=, 1 <
+  qa_ledger.py check-coverage --repo backend-api [--threshold 60]
+                                        # exit 0 >= threshold, 1 < threshold, 2 UNMEASURED (no report)
   qa_ledger.py log-step    --repo backend-api --tool code-review --iteration 1 \
                            --reported 12 --gated-reported 4 --fixed 9 \
                            --deferred 2 --suppressed 1 --tests-passed true \
@@ -399,6 +400,24 @@ def coverage(repo_path, repo_type):
     return flutter_coverage(repo_path)
 
 
+_COVERAGE_REPORT_HINT = {
+    "ant": "target/site/jacoco/jacoco.xml (or -aggregate)",
+    "maven": "target/site/jacoco/jacoco.xml (or -aggregate)",
+    "gradle": "target/site/jacoco/jacoco.xml (or -aggregate)",
+    "python": "coverage.xml or reports/coverage.xml (Cobertura)",
+    "rust": "coverage.xml or reports/coverage.xml (Cobertura)",
+    "dotnet": "coverage.xml or reports/coverage.xml (Cobertura)",
+    "cpp": "coverage.xml or reports/coverage.xml (Cobertura)",
+    "go": "coverage.out, cover.out or reports/coverage.out",
+}
+
+
+def _coverage_report_hint(repo_type):
+    """Human-readable hint of where `coverage()` looked, for an UNMEASURED message --
+    never invents a single path, since several report types glob multiple locations."""
+    return _COVERAGE_REPORT_HINT.get(repo_type, "coverage/lcov.info")
+
+
 # --------------------------------------------------------------------------- #
 # measurement: test counts
 # --------------------------------------------------------------------------- #
@@ -2404,15 +2423,18 @@ def cmd_check_coverage(args):
         threshold = ledger["config"].get("defaults", {}).get("coverage_threshold", 60)
     cov = coverage(cfg["path"], cfg["type"])
     pct = cov["pct"]
+    if not cov["report_found"]:
+        # No coverage report at all is UNMEASURED, not a below-threshold verdict: on a
+        # greenfield repo pct 0.0 + report_found False means no report was ever produced,
+        # never that the code was tested and failed. Fail closed (exit 2) -- distinct from
+        # exit 1 (a real report that reads below threshold) -- so callers do not confuse
+        # "never measured" with "measured and failing".
+        print(f"[qa_ledger] {args.repo}: coverage UNMEASURED -- no coverage report found "
+              f"(looked for {_coverage_report_hint(cfg['type'])}). "
+              f"Run the test command with coverage first to produce a report.")
+        sys.exit(2)
     below = pct < threshold
     state = "BELOW" if below else "OK"
-    if not cov["report_found"]:
-        # No coverage report at all == treat as below threshold (needs char tests),
-        # but flag loudly so the skill knows tests simply haven't been run yet.
-        print(f"[qa_ledger] {args.repo}: NO coverage report found "
-              f"(threshold {threshold}%) -> treat as BELOW. "
-              f"Run the test command first if a report was expected.")
-        sys.exit(1)
     print(f"[qa_ledger] {args.repo}: coverage {pct}% vs threshold {threshold}% -> {state}")
     sys.exit(1 if below else 0)
 

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

@@ -19,7 +19,7 @@ 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) -->
+<!-- uscha kit: 2.4.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)
 
@@ -54,6 +54,14 @@ block onward, derived state wins.
 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.
 
+**No statusline (kit 2.4.0): the visible reply IS the statusline.** On a surface with no live
+statusline — Codex, pi, a plain terminal — these markers are the only signal the operator gets,
+so they MUST appear in the visible reply text, never only inside a collapsed tool-call log the
+operator may not expand. On such a surface, the FINAL message of every turn STARTS with the
+compact `uscha-status` block (derived phase · loop · measured acceptance · next criterion, read
+from the ledger — see the `uscha-status` skill), immediately before the breadcrumb/close marker
+below.
+
 **Open every turn with a breadcrumb**, then the content:
 
 `[uscha · discovery · <step> → <target>]`
@@ -112,6 +120,12 @@ Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`,
 4. **Grill, don't agree.** Surface contradictions, fuzzy/overloaded terms, missing
    failure modes and unstated constraints. A discovery where you agreed with everything
    failed.
+   Two habits, both advisory (unmeasured, kept because they are cheap): **every magnitude
+   carries a number or a range** -- "many tasks", "fast", "large files" are not scope;
+   "20 to 100 tasks", "under 200 ms", "up to 50 MB" are -- and **rules are written as
+   constraints, not wishes**: "no partial implementations, no TODO left in the diff" is
+   checkable; "remember to finish things" is not. A magnitude without a number and a rule
+   without a boundary are questions you still owe the human.
 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
@@ -238,7 +252,8 @@ answer.
   you proposed and the human approved). Distinct from the glossary: this is the model, not
   the vocabulary.
 - **`SPEC.md`** — objective/value, risk, scope/out-of-scope, behavior,
-  inputs/outputs/errors, acceptance, test plan, operation, rollback.
+  inputs/outputs/errors, acceptance, test plan, operation, rollback. Magnitudes with numbers
+  or ranges; rules as constraints with a boundary, never as reminders.
 - **`docs/adr/ADR-NNN-<slug>.md`** — one per durable decision. Format: Status
   (proposed/accepted/**experiment**/deprecated/superseded) · Context · Alternatives · Decision ·
   Consequences · **Implementation Plan** (affected paths, patterns to follow, tests to

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

@@ -18,7 +18,7 @@ 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) -->
+<!-- uscha kit: 2.4.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
 
 ## Orientation markers (non-negotiable)
 
@@ -28,6 +28,10 @@ This skill is a **one-shot read-only readout**: its block IS the answer. It ther
 take the conversational close block — that would be exactly the padding this skill forbids.
 It carries the two minimal markers instead.
 
+**No statusline (kit 2.4.0): the visible reply IS the statusline.** On a surface with no live
+statusline — Codex, pi, a plain terminal — this readout IS the operator's only signal, so it
+MUST appear in the visible reply text, never only inside a collapsed tool-call log.
+
 **Open with a breadcrumb:**
 
 `[uscha · mirador · step <n> → <target>]`

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

@@ -24,7 +24,7 @@ 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) -->
+<!-- uscha kit: 2.4.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)
 
@@ -61,6 +61,14 @@ block onward, derived state wins.
 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.
 
+**No statusline (kit 2.4.0): the visible reply IS the statusline.** On a surface with no live
+statusline — Codex, pi, a plain terminal — these markers are the only signal the operator gets,
+so they MUST appear in the visible reply text, never only inside a collapsed tool-call log the
+operator may not expand. On such a surface, the FINAL message of every turn STARTS with the
+compact `uscha-status` block (derived phase · loop · measured acceptance · next criterion, read
+from the ledger — see the `uscha-status` skill), immediately before the breadcrumb/close marker
+below.
+
 **Open every turn with a breadcrumb**, then the content:
 
 `[uscha · reverse-discovery · <step> → <target>]`

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

@@ -22,7 +22,7 @@ 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) -->
+<!-- uscha kit: 2.4.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)
 
@@ -57,6 +57,14 @@ block onward, derived state wins.
 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.
 
+**No statusline (kit 2.4.0): the visible reply IS the statusline.** On a surface with no live
+statusline — Codex, pi, a plain terminal — these markers are the only signal the operator gets,
+so they MUST appear in the visible reply text, never only inside a collapsed tool-call log the
+operator may not expand. On such a surface, the FINAL message of every turn STARTS with the
+compact `uscha-status` block (derived phase · loop · measured acceptance · next criterion, read
+from the ledger — see the `uscha-status` skill), immediately before the breadcrumb/close marker
+below.
+
 **Open every turn with a breadcrumb**, then the content:
 
 `[uscha · rubric · <step> → <target>]`

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

@@ -58,7 +58,7 @@ that surface the warning cannot come from the skill itself. The `doctor` seam is
 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) -->
+<!-- uscha kit: 2.4.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
 
 ## Orientation markers (non-negotiable)
 
@@ -68,6 +68,10 @@ This skill is a **one-shot read-only readout**: its block IS the answer. It ther
 take the conversational close block — that would be exactly the padding this skill forbids.
 It carries the two minimal markers instead.
 
+**No statusline (kit 2.4.0): the visible reply IS the statusline.** On a surface with no live
+statusline — Codex, pi, a plain terminal — this readout IS the operator's only signal, so it
+MUST appear in the visible reply text, never only inside a collapsed tool-call log.
+
 **Open with a breadcrumb:**
 
 `[uscha · status · step <n> → <target>]`

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

@@ -22,7 +22,7 @@ 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) -->
+<!-- uscha kit: 2.4.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)
 
@@ -57,6 +57,14 @@ block onward, derived state wins.
 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.
 
+**No statusline (kit 2.4.0): the visible reply IS the statusline.** On a surface with no live
+statusline — Codex, pi, a plain terminal — these markers are the only signal the operator gets,
+so they MUST appear in the visible reply text, never only inside a collapsed tool-call log the
+operator may not expand. On such a surface, the FINAL message of every turn STARTS with the
+compact `uscha-status` block (derived phase · loop · measured acceptance · next criterion, read
+from the ledger — see the `uscha-status` skill), immediately before the breadcrumb/close marker
+below.
+
 **Open every turn with a breadcrumb**, then the content:
 
 `[uscha · sysdoc · <step> → <target>]`

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.2.0",
+  "version": "2.4.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,