@andresmassello/uscha 1.95.0 → 1.97.0

package/README.md

@@ -40,81 +40,12 @@ 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.95.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.97.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)
 
 ---
 
-## The diamond — specs are the source code, end to end
-
-Uscha closes a cycle most spec-driven tools only walk halfway. The **spec package plus its
-behavior ledger** is the canonical asset of a system; the code is a regenerable build artifact.
-An LLM compiles the package into code under a validated contract; reverse discovery decompiles
-existing code back into *curated* specs — passing, mandatorily, through the one step no
-automatic tool can perform: a human verdict.
-
-```
-                THE ASSET (solid) ── it appreciates with every model generation
-          ┌───────────────────────────────────────────────────────────────┐
-          │   SPEC PACKAGE  +  BEHAVIOR LEDGER  +  IR                     │
-          │   SPEC · ADRs · ACCEPTANCE · CONSTITUTION                     │
-          │   verdicts: preserve · fix · undefined                        │
-          └──────────────┬─────────────────────────────▲──────────────────┘
-                         │                             │
-        FORWARD          │                             │          REVERSE
-        the LLM compiles │                             │   reverse discovery
-                         ▼                             │
-   ┌─────────────────────────────────────┐   ┌─────────┴─────────────────────┐
-   │ compile-validate — output contract, │   │ CURATION · the human gate     │
-   │   mechanical only, model-blind      │   │ candidate ─▶ verdict ─▶ ledger │
-   │ withheld ORACLE — authored BEFORE   │   │ no verdict → PR blocked,      │
-   │   compiling, never in the prompt    │   │   the candidate is NAMED      │
-   └─────────────────┬───────────────────┘   └─────────▲─────────────────────┘
-                     │                                 │
-                     ▼                                 │
-   ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐   ┌─────────────┴─────────────────────┐
-     CODE (dashed) — build artifact,      │ discover · golden capture         │
-     regenerable, disposable          ───▶│ candidates: typed evidence        │
-   └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘   │   + confidence                    │
-                                          └───────────────────────────────────┘
-                                            ▲ also enters here: any LEGACY
-                                              system (= 100% drift)
-
-   round trip · bench-roundtrip — how much of the asset the reverse organs re-anchor
-   from the compiled code: 0.828 measured (12 archetypes) — names AND behaviour
-```
-
-**What each arrow is, in the engine (kit 1.95.0, 53 subcommands, all measured):**
-
-| Leg | Subcommands | What it establishes |
-|---|---|---|
-| Asset → typed graph | `ir-extract`, `ir-render` | the whole package becomes one canonical IR (M2, ADR-015) — deterministic, `UNTYPED` is a measurement not an error |
-| Forward, the compiler | `compile-validate`, `compile-ingest` | any model produces code; the engine validates the output contract and never compiles (M3, ADR-016) |
-| Forward, is it the *same* system? | `bootstrap-oracle`, `bootstrap-variance`, `bench` | a withheld oracle judges blind compilations — **12 archetypes, 9 PASS · 3 PARTIAL**, three Claude-family models (Haiku · Sonnet · Opus — one vendor; cross-vendor not yet measured), JS included (M4/M5, ADR-017/018/028/029) |
-| Reverse, facts | `discover`, `golden-diff` (+ the `/uscha-characterize` skill) | system map + mechanically captured golden; typed candidate observations with evidence class (M1, ADR-013) |
-| Reverse, the human gate | `curate`, `promote`, `curation-check`, `bench-curate` | one verdict per candidate, append-only ledger verified against git; unjudged → `pr-ready` blocked naming it (ADR-009/010, INV-CURATION-01) |
-| Fidelity, honestly | `fidelity`, `roundtrip`, `bench-roundtrip`, `bench-r2` | per-compiler fidelity vector, id-level round trip, recoverability **0.828**, and the **noise floor** under every variance claim (ADR-014/022/027/030) |
-
-**Read the numbers the way the repo does.** 9 of 12 archetypes regenerate to the same system
-under an oracle the compilers never saw — that is the closed loop working. 0.828 is the mean
-*recoverability* of the asset from compiled code counting only static and behavioural
-footing. It read **0.062** until 1.90.0, with the behaviour dimension `UNMEASURED`, because no
-oracle case carried an AC tag — a named absence, not a zero. The 12 bench oracles are now
-curated per case (`ORACLE-TAGS-CURATED.json`, human-authored; payloads and expectations
-untouched), so the dimension is measured and the number says the reverse organs anchor **names
-and behaviour**. Both numbers are published rather than smoothed, and what moved between them
-was the tagging, not the code under test. And `bench-r2` measured
-that same-model reruns differ structurally about as much as different models do (aggregate
-`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.
-
-→ The full thesis, with before/after diagrams and the REAL vs VISION table:
-**[uscha.dev/diamond](https://uscha.dev/diamond)** · the mechanism, in three diagrams:
-**[uscha.dev/how](https://uscha.dev/how)**
-
----
-
 ## The problem it solves
 
 An agent will tell you the tests pass. It will tell you the feature is done. It is often
@@ -202,6 +133,75 @@ else `doctor` reports `advisory` rather than implying a guard it cannot see.
 - **Model-agnostic.** The engine never reads tokens, model names or vendor telemetry. Any
   model-reported number enters through an adapter, never the engine.
 
+## The diamond — specs are the source code, end to end
+
+Uscha closes a cycle most spec-driven tools only walk halfway. The **spec package plus its
+behavior ledger** is the canonical asset of a system; the code is a regenerable build artifact.
+An LLM compiles the package into code under a validated contract; reverse discovery decompiles
+existing code back into *curated* specs — passing, mandatorily, through the one step no
+automatic tool can perform: a human verdict.
+
+```
+                THE ASSET (solid) ── it appreciates with every model generation
+          ┌───────────────────────────────────────────────────────────────┐
+          │   SPEC PACKAGE  +  BEHAVIOR LEDGER  +  IR                     │
+          │   SPEC · ADRs · ACCEPTANCE · CONSTITUTION                     │
+          │   verdicts: preserve · fix · undefined                        │
+          └──────────────┬─────────────────────────────▲──────────────────┘
+                         │                             │
+        FORWARD          │                             │          REVERSE
+        the LLM compiles │                             │   reverse discovery
+                         ▼                             │
+   ┌─────────────────────────────────────┐   ┌─────────┴─────────────────────┐
+   │ compile-validate — output contract, │   │ CURATION · the human gate     │
+   │   mechanical only, model-blind      │   │ candidate ─▶ verdict ─▶ ledger │
+   │ withheld ORACLE — authored BEFORE   │   │ no verdict → PR blocked,      │
+   │   compiling, never in the prompt    │   │   the candidate is NAMED      │
+   └─────────────────┬───────────────────┘   └─────────▲─────────────────────┘
+                     │                                 │
+                     ▼                                 │
+   ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐   ┌─────────────┴─────────────────────┐
+     CODE (dashed) — build artifact,      │ discover · golden capture         │
+     regenerable, disposable          ───▶│ candidates: typed evidence        │
+   └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘   │   + confidence                    │
+                                          └───────────────────────────────────┘
+                                            ▲ also enters here: any LEGACY
+                                              system (= 100% drift)
+
+   round trip · bench-roundtrip — how much of the asset the reverse organs re-anchor
+   from the compiled code: 0.828 measured (12 archetypes) — names AND behaviour
+```
+
+**What each arrow is, in the engine (kit 1.96.0, 53 subcommands, all measured):**
+
+| Leg | Subcommands | What it establishes |
+|---|---|---|
+| Asset → typed graph | `ir-extract`, `ir-render` | the whole package becomes one canonical IR (M2, ADR-015) — deterministic, `UNTYPED` is a measurement not an error |
+| Forward, the compiler | `compile-validate`, `compile-ingest` | any model produces code; the engine validates the output contract and never compiles (M3, ADR-016) |
+| Forward, is it the *same* system? | `bootstrap-oracle`, `bootstrap-variance`, `bench` | a withheld oracle judges blind compilations — **12 archetypes, 9 PASS · 3 PARTIAL**, three Claude-family models (Haiku · Sonnet · Opus — one vendor; cross-vendor not yet measured), JS included (M4/M5, ADR-017/018/028/029) |
+| Reverse, facts | `discover`, `golden-diff` (+ the `/uscha-characterize` skill) | system map + mechanically captured golden; typed candidate observations with evidence class (M1, ADR-013) |
+| Reverse, the human gate | `curate`, `promote`, `curation-check`, `bench-curate` | one verdict per candidate, append-only ledger verified against git; unjudged → `pr-ready` blocked naming it (ADR-009/010, INV-CURATION-01) |
+| Fidelity, honestly | `fidelity`, `roundtrip`, `bench-roundtrip`, `bench-r2` | per-compiler fidelity vector, id-level round trip, recoverability **0.828**, and the **noise floor** under every variance claim (ADR-014/022/027/030) |
+
+**Read the numbers the way the repo does.** 9 of 12 archetypes regenerate to the same system
+under an oracle the compilers never saw — that is the closed loop working. 0.828 is the mean
+*recoverability* of the asset from compiled code counting only static and behavioural
+footing. It read **0.062** until 1.90.0, with the behaviour dimension `UNMEASURED`, because no
+oracle case carried an AC tag — a named absence, not a zero. The 12 bench oracles are now
+curated per case (`ORACLE-TAGS-CURATED.json`, human-authored; payloads and expectations
+untouched), so the dimension is measured and the number says the reverse organs anchor **names
+and behaviour**. Both numbers are published rather than smoothed, and what moved between them
+was the tagging, not the code under test. And `bench-r2` measured
+that same-model reruns differ structurally about as much as different models do (aggregate
+`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.
+
+→ The full thesis, with before/after diagrams and the REAL vs VISION table:
+**[uscha.dev/diamond](https://uscha.dev/diamond)** · the mechanism, in three diagrams:
+**[uscha.dev/how](https://uscha.dev/how)**
+
+---
+
 ## Documentation
 
 - **[`uscha-kit/INSTALL.md`](uscha-kit/INSTALL.md)** — full install guide (npm, git, plugin)
@@ -209,6 +209,8 @@ else `doctor` reports `advisory` rather than implying a guard it cannot see.
   subcommand, the readiness KPI, the simplicity and rebuild gates
 - **[`docs/`](docs/)** — the long deck, the operator's playbook, a skills reference and a
   one-pager (ES + EN)
+- **[`docs/adr/INDEX.md`](docs/adr/INDEX.md)** — every architecture decision, grouped by who
+  needs it, with a five-ADR reading order for a newcomer
 - **[`docs/paper/`](docs/paper/)** — the method written up as a paper
 
 Each release ships a `uscha-kit/CHANGELOG-X.Y.Z.md` explaining what changed and why.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andresmassello/uscha",
-  "version": "1.95.0",
+  "version": "1.97.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

@@ -18,6 +18,7 @@ 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.
 
+<!-- uscha:orientation-block:begin -->
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -85,6 +86,7 @@ and say exactly what unblocks it.
 
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+<!-- uscha:orientation-block:end -->
 
 ## Non-negotiable principles
 

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

@@ -18,6 +18,7 @@ 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.
 
+<!-- uscha:orientation-block:begin -->
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -85,6 +86,7 @@ and say exactly what unblocks it.
 
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+<!-- uscha:orientation-block:end -->
 
 ## Inputs
 

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

@@ -26,6 +26,7 @@ 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).
 
+<!-- uscha:orientation-block:begin -->
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -93,6 +94,7 @@ and say exactly what unblocks it.
 
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+<!-- uscha:orientation-block:end -->
 
 ## Non-negotiable principles
 

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

@@ -7251,13 +7251,46 @@ def _derive_facts():
     }
 
 
+# Spelled-out counts are claims too, and the paper writes both forms in one sentence -- "nine
+# agent skills and a dependency-free Python engine with 53 subcommands". A gate that only sees
+# digits reads half of that sentence and calls the file green. 1..99 covers every count this repo
+# derives, with room; above it the number is written in digits everywhere it appears.
+_ONES = ("zero", "one", "two", "three", "four", "five", "six", "seven", "eight", "nine",
+         "ten", "eleven", "twelve", "thirteen", "fourteen", "fifteen", "sixteen",
+         "seventeen", "eighteen", "nineteen")
+_TENS = ("", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy", "eighty", "ninety")
+
+
+def _spell(n):
+    """1..99 in English words, hyphenated ("fifty-three"); None outside that range."""
+    if not 1 <= n <= 99:
+        return None
+    if n < 20:
+        return _ONES[n]
+    return _TENS[n // 10] + ("-" + _ONES[n % 10] if n % 10 else "")
+
+
+_SPELLED = dict((_spell(n), n) for n in range(1, 100))
+# longest alternative first: an alternation offering "six" before "sixty-three" matches the prefix
+_NUM_ALT = "|".join(sorted(_SPELLED, key=len, reverse=True))
+# the leading \b so that "someone skills" cannot be read as the claim "one skills"
+_COUNT = r"\b(\d+|" + _NUM_ALT + r")\s+"
+
+
+def _unspell(token):
+    """The integer a spelled-out count names, or None when the token is not one."""
+    return _SPELLED.get(token.lower())
+
+
 _CLAIM_PATTERNS = (
     # (fact key path, regex over one line, needs-context substring or None)
     ("version", r"v(\d+\.\d+\.\d+)", "kit"),
     ("version", r"uscha-kit\s+v?(\d+\.\d+\.\d+)", None),
-    ("subcommands.count", r"(\d+)\s+sub-?comm?ands", None),
+    ("subcommands.count", _COUNT + r"sub-?comm?ands", None),
     ("subcommands.count", r"(\d+)\s+subcomandos", None),
-    ("skills.count", r"(\d+)\s+skills", None),
+    # "agent skills" is the kit's own noun phrase and the paper's; nothing wider is let in,
+    # because a WRITER that guessed at "two other skills" would corrupt the sentence it fixed.
+    ("skills.count", _COUNT + r"(?:agent\s+)?skills", None),
 )
 
 
@@ -7268,6 +7301,110 @@ def _fact_value(facts, dotted):
     return str(cur)
 
 
+def _claim_norm(token):
+    """The comparable form of a claimed token: a spelled-out count normalises to its digits, so
+    "nine skills" and "9 skills" are one claim compared against one fact."""
+    n = _unspell(token)
+    return token if n is None else str(n)
+
+
+def _claim_rewrite(token, actual):
+    """The replacement for one claimed token, in the AUTHOR's notation: a spelled-out claim is
+    rewritten spelled out and keeps its leading capital, a numeric one numerically. Rewriting
+    "nine skills" as "10 skills" would fix the fact and break the sentence."""
+    if _unspell(token) is None:
+        return actual
+    word = _spell(int(actual)) if actual.isdigit() else None
+    if word is None:
+        return actual
+    return word[0].upper() + word[1:] if token[:1].isupper() else word
+
+
+def _iter_claims(line):
+    """Every recognised claim on ONE line, as (fact key, start, end, token).
+
+    ONE recogniser, two consumers: `--check` reports what this yields and `--write` rewrites
+    exactly what this yields. A writer that re-implemented the patterns could disagree with the
+    checker, and the disagreement would surface as a release that refuses after fixing itself.
+
+    HTML comment spans are SKIPPED rather than deleted -- a comment is not a published claim
+    (the first live run flagged a section marker reading "2 Skills"), and `--write` needs offsets
+    into the ORIGINAL line. Overlapping matches collapse: the two version patterns can name the
+    same digits, and rewriting one span twice would corrupt the line."""
+    spans = [m.span() for m in re.finditer(r"<!--.*?-->", line)]
+    low = line.lower()
+    found = []
+    for key, pat, ctx in _CLAIM_PATTERNS:
+        if ctx and ctx not in low:
+            continue
+        for m in re.finditer(pat, line, re.I):
+            if any(a <= m.start() < b for a, b in spans):
+                continue
+            found.append((m.start(1), m.end(1), key, m.group(1)))
+    out, taken = [], []
+    for start, end, key, token in sorted(found):
+        if any(start < e and s < end for s, e in taken):
+            continue
+        taken.append((start, end))
+        out.append((key, start, end, token))
+    return out
+
+
+def _write_claims(facts, paths):
+    """Rewrite every recognised STALE claim in `paths` to the derived fact, byte for byte
+    otherwise. Line endings are preserved PER FILE (newline="" on both ends): the gated set mixes
+    LF sources with CRLF-checked-out HTML, and normalising them would turn a one-token fix into a
+    whole-file diff nobody can review.
+
+    What it deliberately does NOT touch: anything the patterns do not recognise. A missing
+    subcommand table row, a count spelled outside 1..99, a claim phrased in prose -- those stay
+    for the human, and the --check that follows still fails on them."""
+    changed, total, problems = 0, 0, 0
+    for path in paths:
+        try:
+            with open(path, encoding="utf-8", newline="") as fh:
+                body = fh.read()
+        except OSError as exc:
+            print("  !! %s: unreadable: %s" % (path, exc))
+            problems += 1
+            continue
+        except UnicodeDecodeError as exc:
+            # `--check` reads this file with errors="replace" and still reports its claims, so
+            # nothing is hidden. `--write` must NOT read it that way: writing a replaced byte
+            # back would destroy data to fix a version number, and a writer that corrupts a file
+            # to correct a claim is worse than the claim. Named, skipped, and the --check that
+            # follows still fails on whatever is stale in it.
+            print("  !! %s: not valid UTF-8 (%s) -- left untouched; --check still reads it"
+                  % (path, exc))
+            problems += 1
+            continue
+        lines = body.split("\n")
+        n = 0
+        for i, line in enumerate(lines):
+            claims = _iter_claims(line)
+            if not claims:
+                continue
+            # right to left: an earlier rewrite must not move the offsets of a later one
+            for key, start, end, token in sorted(claims, key=lambda c: c[1], reverse=True):
+                actual = _fact_value(facts, key)
+                if _claim_norm(token) == actual:
+                    continue
+                line = line[:start] + _claim_rewrite(token, actual) + line[end:]
+                n += 1
+            lines[i] = line
+        if not n:
+            continue
+        with open(path, "w", encoding="utf-8", newline="") as fh:
+            fh.write("\n".join(lines))
+        print("%s: %d claim(s) rewritten" % (path, n))
+        changed += 1
+        total += n
+    print("FACTS --write: %d claim(s) rewritten in %d of %d file(s)%s"
+          % (total, changed, len(paths),
+             "" if not problems else "; %d file(s) could not be read" % problems))
+    return problems
+
+
 def cmd_facts(args):
     """Generate SYSTEM-FACTS.json, or --check published claims against the derived facts.
 
@@ -7276,6 +7413,24 @@ def cmd_facts(args):
     about factual drift. A claim that CI does not compare against a derived fact will
     drift; this makes the comparison mechanical and the drift a named red."""
     facts = _derive_facts()
+    if args.write is not None:
+        # Until 1.97.0 there was no writer, so every bump was ~25 hand edits across ~13 files and
+        # the release script could only refuse and hand them back. `--write` rewrites the claims
+        # the SAME recogniser finds, then runs the SAME --check: a writer that reported its own
+        # success would be exactly the self-graded evidence this engine exists to refuse.
+        if args.check is not None:
+            # Before 1.97.0 this combination silently dropped --check's files: --write set
+            # args.check to ITS list. Two file sets given, one measured, no word about it.
+            print("[qa_ledger] facts: --check and --write are alternatives, not a pair -- "
+                  "--write already re-checks exactly the files it wrote.", file=sys.stderr)
+            sys.exit(2)
+        if not args.write:
+            print("[qa_ledger] facts: --write needs at least one file.", file=sys.stderr)
+            sys.exit(2)
+        if _write_claims(facts, args.write):
+            # an unreadable file is an UNMEASURED claim set, and unmeasured is not green
+            sys.exit(2)
+        args.check = list(args.write)
     if args.check:
         problems = []
         # 1) the committed facts file must match a fresh derivation (stale facts are drift)
@@ -7301,21 +7456,17 @@ def cmd_facts(args):
             table_names = []
             table_start = 0
             for n, line in enumerate(lines, 1):
-                # an HTML comment is not a published claim -- the first live run flagged a
-                # section marker (a comment reading "2 Skills") as a drifted count
-                line = re.sub(r"<!--.*?-->", "", line)
-                low = line.lower()
-                for key, pat, ctx in _CLAIM_PATTERNS:
-                    if ctx and ctx not in low:
-                        continue
-                    for m in re.finditer(pat, line, re.I):
-                        claimed = m.group(1)
-                        actual = _fact_value(facts, key)
-                        if claimed != actual:
-                            problems.append((path, n, key, claimed, actual))
+                # the claims come from the SHARED recogniser (`_iter_claims`), which skips HTML
+                # comment spans -- a comment is not a published claim
+                for key, _s, _e, claimed in _iter_claims(line):
+                    actual = _fact_value(facts, key)
+                    if _claim_norm(claimed) != actual:
+                        problems.append((path, n, key, claimed, actual))
                 # the parser-surface table (Subcommand/Subcomando header, one `<td class="t">`
                 # row per subcommand) is a claim too, just not a numeric one -- a row can go
                 # missing while the count beside it stays correct (the `top` row did, once).
+                # This half reads the comment-STRIPPED line: a commented-out row is not a row.
+                line = re.sub(r"<!--.*?-->", "", line)
                 if not in_table:
                     if re.search(r"<th>Sub ?comm?ando?s?</th>", line, re.I):
                         in_table, table_names, table_start = True, [], n
@@ -12288,6 +12439,10 @@ def build_parser():
     pfa.add_argument("--out", default="SYSTEM-FACTS.json")
     pfa.add_argument("--check", nargs="*", default=None,
                      help="files whose claims must match the derived facts; exit 1 on drift")
+    pfa.add_argument("--write", nargs="*", default=None,
+                     help="files whose recognised claims are REWRITTEN to the derived facts "
+                          "(spelled-out claims stay spelled out), then re-checked: exit 1 if "
+                          "anything still disagrees")
     pfa.set_defaults(func=cmd_facts)
 
     prt = sub.add_parser("roundtrip",

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

@@ -18,6 +18,7 @@ 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.
 
+<!-- uscha:orientation-block:begin -->
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -85,6 +86,7 @@ and say exactly what unblocks it.
 
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+<!-- uscha:orientation-block:end -->
 
 ## Non-negotiable principles
 

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

@@ -17,6 +17,7 @@ allowed-tools: Read, Write, Glob, Grep, Bash
 Paints the REAL state of the project at a glance. It does not narrate or estimate: it
 wires the JSON the engine emits into the template. Read-only.
 
+<!-- uscha:orientation-block:begin -->
 ## Orientation markers (non-negotiable)
 
 The operator must never have to ask "where am I?" or "what happens now?".
@@ -40,6 +41,7 @@ Run:  <the exact command or skill to invoke>
 including any `Flow:` line in this file. If nothing is actionable, say that plainly rather
 than inventing a step. Keep the CONTENT in the conversation's language and the labels
 (`Next`, `Run`) verbatim — the smoke suite checks for them.
+<!-- uscha:orientation-block:end -->
 
 ## Contract
 

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

@@ -23,6 +23,7 @@ first, always — and what cannot be fact yet becomes an OBSERVATION in quaranti
 evidence-classed, content-addressed, and promoted to the contract only by a per-observation
 human verdict (ADR-013).**
 
+<!-- uscha:orientation-block:begin -->
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -92,6 +93,7 @@ and say exactly what unblocks it.
 
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+<!-- uscha:orientation-block:end -->
 
 ## The one non-negotiable: quarantine, not judgment (ADR-009)
 

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

@@ -21,6 +21,7 @@ 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.
 
+<!-- uscha:orientation-block:begin -->
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -88,6 +89,7 @@ and say exactly what unblocks it.
 
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+<!-- uscha:orientation-block:end -->
 
 ## Protocol
 

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

@@ -19,6 +19,7 @@ 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.
 
+<!-- uscha:orientation-block:begin -->
 ## Orientation markers (non-negotiable)
 
 The operator must never have to ask "where am I?" or "what happens now?".
@@ -42,6 +43,7 @@ Run:  <the exact command or skill to invoke>
 including any `Flow:` line in this file. If nothing is actionable, say that plainly rather
 than inventing a step. Keep the CONTENT in the conversation's language and the labels
 (`Next`, `Run`) verbatim — the smoke suite checks for them.
+<!-- uscha:orientation-block:end -->
 
 ## Contract
 

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

@@ -21,6 +21,7 @@ switch between at any time:
 - **Technical track** — architecture, modules, data flow, contracts, QA results,
   coverage, known deferred issues.
 
+<!-- uscha:orientation-block:begin -->
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -88,6 +89,7 @@ and say exactly what unblocks it.
 
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+<!-- uscha:orientation-block:end -->
 
 ## Inputs
 

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.95.0",
+  "version": "1.97.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, 53 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.95.0",
+  "version": "1.97.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.95.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.97.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.95.0
+uscha-kit 1.97.0

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

@@ -18,6 +18,7 @@ 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.
 
+<!-- uscha:orientation-block:begin -->
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -85,6 +86,7 @@ and say exactly what unblocks it.
 
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+<!-- uscha:orientation-block:end -->
 
 ## Non-negotiable principles
 

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

@@ -18,6 +18,7 @@ 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.
 
+<!-- uscha:orientation-block:begin -->
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -85,6 +86,7 @@ and say exactly what unblocks it.
 
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+<!-- uscha:orientation-block:end -->
 
 ## Inputs
 

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

@@ -26,6 +26,7 @@ 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).
 
+<!-- uscha:orientation-block:begin -->
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -93,6 +94,7 @@ and say exactly what unblocks it.
 
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+<!-- uscha:orientation-block:end -->
 
 ## Non-negotiable principles
 

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

@@ -7251,13 +7251,46 @@ def _derive_facts():
     }
 
 
+# Spelled-out counts are claims too, and the paper writes both forms in one sentence -- "nine
+# agent skills and a dependency-free Python engine with 53 subcommands". A gate that only sees
+# digits reads half of that sentence and calls the file green. 1..99 covers every count this repo
+# derives, with room; above it the number is written in digits everywhere it appears.
+_ONES = ("zero", "one", "two", "three", "four", "five", "six", "seven", "eight", "nine",
+         "ten", "eleven", "twelve", "thirteen", "fourteen", "fifteen", "sixteen",
+         "seventeen", "eighteen", "nineteen")
+_TENS = ("", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy", "eighty", "ninety")
+
+
+def _spell(n):
+    """1..99 in English words, hyphenated ("fifty-three"); None outside that range."""
+    if not 1 <= n <= 99:
+        return None
+    if n < 20:
+        return _ONES[n]
+    return _TENS[n // 10] + ("-" + _ONES[n % 10] if n % 10 else "")
+
+
+_SPELLED = dict((_spell(n), n) for n in range(1, 100))
+# longest alternative first: an alternation offering "six" before "sixty-three" matches the prefix
+_NUM_ALT = "|".join(sorted(_SPELLED, key=len, reverse=True))
+# the leading \b so that "someone skills" cannot be read as the claim "one skills"
+_COUNT = r"\b(\d+|" + _NUM_ALT + r")\s+"
+
+
+def _unspell(token):
+    """The integer a spelled-out count names, or None when the token is not one."""
+    return _SPELLED.get(token.lower())
+
+
 _CLAIM_PATTERNS = (
     # (fact key path, regex over one line, needs-context substring or None)
     ("version", r"v(\d+\.\d+\.\d+)", "kit"),
     ("version", r"uscha-kit\s+v?(\d+\.\d+\.\d+)", None),
-    ("subcommands.count", r"(\d+)\s+sub-?comm?ands", None),
+    ("subcommands.count", _COUNT + r"sub-?comm?ands", None),
     ("subcommands.count", r"(\d+)\s+subcomandos", None),
-    ("skills.count", r"(\d+)\s+skills", None),
+    # "agent skills" is the kit's own noun phrase and the paper's; nothing wider is let in,
+    # because a WRITER that guessed at "two other skills" would corrupt the sentence it fixed.
+    ("skills.count", _COUNT + r"(?:agent\s+)?skills", None),
 )
 
 
@@ -7268,6 +7301,110 @@ def _fact_value(facts, dotted):
     return str(cur)
 
 
+def _claim_norm(token):
+    """The comparable form of a claimed token: a spelled-out count normalises to its digits, so
+    "nine skills" and "9 skills" are one claim compared against one fact."""
+    n = _unspell(token)
+    return token if n is None else str(n)
+
+
+def _claim_rewrite(token, actual):
+    """The replacement for one claimed token, in the AUTHOR's notation: a spelled-out claim is
+    rewritten spelled out and keeps its leading capital, a numeric one numerically. Rewriting
+    "nine skills" as "10 skills" would fix the fact and break the sentence."""
+    if _unspell(token) is None:
+        return actual
+    word = _spell(int(actual)) if actual.isdigit() else None
+    if word is None:
+        return actual
+    return word[0].upper() + word[1:] if token[:1].isupper() else word
+
+
+def _iter_claims(line):
+    """Every recognised claim on ONE line, as (fact key, start, end, token).
+
+    ONE recogniser, two consumers: `--check` reports what this yields and `--write` rewrites
+    exactly what this yields. A writer that re-implemented the patterns could disagree with the
+    checker, and the disagreement would surface as a release that refuses after fixing itself.
+
+    HTML comment spans are SKIPPED rather than deleted -- a comment is not a published claim
+    (the first live run flagged a section marker reading "2 Skills"), and `--write` needs offsets
+    into the ORIGINAL line. Overlapping matches collapse: the two version patterns can name the
+    same digits, and rewriting one span twice would corrupt the line."""
+    spans = [m.span() for m in re.finditer(r"<!--.*?-->", line)]
+    low = line.lower()
+    found = []
+    for key, pat, ctx in _CLAIM_PATTERNS:
+        if ctx and ctx not in low:
+            continue
+        for m in re.finditer(pat, line, re.I):
+            if any(a <= m.start() < b for a, b in spans):
+                continue
+            found.append((m.start(1), m.end(1), key, m.group(1)))
+    out, taken = [], []
+    for start, end, key, token in sorted(found):
+        if any(start < e and s < end for s, e in taken):
+            continue
+        taken.append((start, end))
+        out.append((key, start, end, token))
+    return out
+
+
+def _write_claims(facts, paths):
+    """Rewrite every recognised STALE claim in `paths` to the derived fact, byte for byte
+    otherwise. Line endings are preserved PER FILE (newline="" on both ends): the gated set mixes
+    LF sources with CRLF-checked-out HTML, and normalising them would turn a one-token fix into a
+    whole-file diff nobody can review.
+
+    What it deliberately does NOT touch: anything the patterns do not recognise. A missing
+    subcommand table row, a count spelled outside 1..99, a claim phrased in prose -- those stay
+    for the human, and the --check that follows still fails on them."""
+    changed, total, problems = 0, 0, 0
+    for path in paths:
+        try:
+            with open(path, encoding="utf-8", newline="") as fh:
+                body = fh.read()
+        except OSError as exc:
+            print("  !! %s: unreadable: %s" % (path, exc))
+            problems += 1
+            continue
+        except UnicodeDecodeError as exc:
+            # `--check` reads this file with errors="replace" and still reports its claims, so
+            # nothing is hidden. `--write` must NOT read it that way: writing a replaced byte
+            # back would destroy data to fix a version number, and a writer that corrupts a file
+            # to correct a claim is worse than the claim. Named, skipped, and the --check that
+            # follows still fails on whatever is stale in it.
+            print("  !! %s: not valid UTF-8 (%s) -- left untouched; --check still reads it"
+                  % (path, exc))
+            problems += 1
+            continue
+        lines = body.split("\n")
+        n = 0
+        for i, line in enumerate(lines):
+            claims = _iter_claims(line)
+            if not claims:
+                continue
+            # right to left: an earlier rewrite must not move the offsets of a later one
+            for key, start, end, token in sorted(claims, key=lambda c: c[1], reverse=True):
+                actual = _fact_value(facts, key)
+                if _claim_norm(token) == actual:
+                    continue
+                line = line[:start] + _claim_rewrite(token, actual) + line[end:]
+                n += 1
+            lines[i] = line
+        if not n:
+            continue
+        with open(path, "w", encoding="utf-8", newline="") as fh:
+            fh.write("\n".join(lines))
+        print("%s: %d claim(s) rewritten" % (path, n))
+        changed += 1
+        total += n
+    print("FACTS --write: %d claim(s) rewritten in %d of %d file(s)%s"
+          % (total, changed, len(paths),
+             "" if not problems else "; %d file(s) could not be read" % problems))
+    return problems
+
+
 def cmd_facts(args):
     """Generate SYSTEM-FACTS.json, or --check published claims against the derived facts.
 
@@ -7276,6 +7413,24 @@ def cmd_facts(args):
     about factual drift. A claim that CI does not compare against a derived fact will
     drift; this makes the comparison mechanical and the drift a named red."""
     facts = _derive_facts()
+    if args.write is not None:
+        # Until 1.97.0 there was no writer, so every bump was ~25 hand edits across ~13 files and
+        # the release script could only refuse and hand them back. `--write` rewrites the claims
+        # the SAME recogniser finds, then runs the SAME --check: a writer that reported its own
+        # success would be exactly the self-graded evidence this engine exists to refuse.
+        if args.check is not None:
+            # Before 1.97.0 this combination silently dropped --check's files: --write set
+            # args.check to ITS list. Two file sets given, one measured, no word about it.
+            print("[qa_ledger] facts: --check and --write are alternatives, not a pair -- "
+                  "--write already re-checks exactly the files it wrote.", file=sys.stderr)
+            sys.exit(2)
+        if not args.write:
+            print("[qa_ledger] facts: --write needs at least one file.", file=sys.stderr)
+            sys.exit(2)
+        if _write_claims(facts, args.write):
+            # an unreadable file is an UNMEASURED claim set, and unmeasured is not green
+            sys.exit(2)
+        args.check = list(args.write)
     if args.check:
         problems = []
         # 1) the committed facts file must match a fresh derivation (stale facts are drift)
@@ -7301,21 +7456,17 @@ def cmd_facts(args):
             table_names = []
             table_start = 0
             for n, line in enumerate(lines, 1):
-                # an HTML comment is not a published claim -- the first live run flagged a
-                # section marker (a comment reading "2 Skills") as a drifted count
-                line = re.sub(r"<!--.*?-->", "", line)
-                low = line.lower()
-                for key, pat, ctx in _CLAIM_PATTERNS:
-                    if ctx and ctx not in low:
-                        continue
-                    for m in re.finditer(pat, line, re.I):
-                        claimed = m.group(1)
-                        actual = _fact_value(facts, key)
-                        if claimed != actual:
-                            problems.append((path, n, key, claimed, actual))
+                # the claims come from the SHARED recogniser (`_iter_claims`), which skips HTML
+                # comment spans -- a comment is not a published claim
+                for key, _s, _e, claimed in _iter_claims(line):
+                    actual = _fact_value(facts, key)
+                    if _claim_norm(claimed) != actual:
+                        problems.append((path, n, key, claimed, actual))
                 # the parser-surface table (Subcommand/Subcomando header, one `<td class="t">`
                 # row per subcommand) is a claim too, just not a numeric one -- a row can go
                 # missing while the count beside it stays correct (the `top` row did, once).
+                # This half reads the comment-STRIPPED line: a commented-out row is not a row.
+                line = re.sub(r"<!--.*?-->", "", line)
                 if not in_table:
                     if re.search(r"<th>Sub ?comm?ando?s?</th>", line, re.I):
                         in_table, table_names, table_start = True, [], n
@@ -12288,6 +12439,10 @@ def build_parser():
     pfa.add_argument("--out", default="SYSTEM-FACTS.json")
     pfa.add_argument("--check", nargs="*", default=None,
                      help="files whose claims must match the derived facts; exit 1 on drift")
+    pfa.add_argument("--write", nargs="*", default=None,
+                     help="files whose recognised claims are REWRITTEN to the derived facts "
+                          "(spelled-out claims stay spelled out), then re-checked: exit 1 if "
+                          "anything still disagrees")
     pfa.set_defaults(func=cmd_facts)
 
     prt = sub.add_parser("roundtrip",

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

@@ -18,6 +18,7 @@ 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.
 
+<!-- uscha:orientation-block:begin -->
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -85,6 +86,7 @@ and say exactly what unblocks it.
 
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+<!-- uscha:orientation-block:end -->
 
 ## Non-negotiable principles
 

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

@@ -17,6 +17,7 @@ allowed-tools: Read, Write, Glob, Grep, Bash
 Paints the REAL state of the project at a glance. It does not narrate or estimate: it
 wires the JSON the engine emits into the template. Read-only.
 
+<!-- uscha:orientation-block:begin -->
 ## Orientation markers (non-negotiable)
 
 The operator must never have to ask "where am I?" or "what happens now?".
@@ -40,6 +41,7 @@ Run:  <the exact command or skill to invoke>
 including any `Flow:` line in this file. If nothing is actionable, say that plainly rather
 than inventing a step. Keep the CONTENT in the conversation's language and the labels
 (`Next`, `Run`) verbatim — the smoke suite checks for them.
+<!-- uscha:orientation-block:end -->
 
 ## Contract
 

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

@@ -23,6 +23,7 @@ first, always — and what cannot be fact yet becomes an OBSERVATION in quaranti
 evidence-classed, content-addressed, and promoted to the contract only by a per-observation
 human verdict (ADR-013).**
 
+<!-- uscha:orientation-block:begin -->
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -92,6 +93,7 @@ and say exactly what unblocks it.
 
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+<!-- uscha:orientation-block:end -->
 
 ## The one non-negotiable: quarantine, not judgment (ADR-009)
 

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

@@ -21,6 +21,7 @@ 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.
 
+<!-- uscha:orientation-block:begin -->
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -88,6 +89,7 @@ and say exactly what unblocks it.
 
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+<!-- uscha:orientation-block:end -->
 
 ## Protocol
 

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

@@ -19,6 +19,7 @@ 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.
 
+<!-- uscha:orientation-block:begin -->
 ## Orientation markers (non-negotiable)
 
 The operator must never have to ask "where am I?" or "what happens now?".
@@ -42,6 +43,7 @@ Run:  <the exact command or skill to invoke>
 including any `Flow:` line in this file. If nothing is actionable, say that plainly rather
 than inventing a step. Keep the CONTENT in the conversation's language and the labels
 (`Next`, `Run`) verbatim — the smoke suite checks for them.
+<!-- uscha:orientation-block:end -->
 
 ## Contract
 

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

@@ -21,6 +21,7 @@ switch between at any time:
 - **Technical track** — architecture, modules, data flow, contracts, QA results,
   coverage, known deferred issues.
 
+<!-- uscha:orientation-block:begin -->
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -88,6 +89,7 @@ and say exactly what unblocks it.
 
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
+<!-- uscha:orientation-block:end -->
 
 ## Inputs
 

package/uscha-kit/uscha.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.95.0",
+  "version": "1.97.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,