@andresmassello/uscha 2.0.0 → 2.2.0

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "uscha",
-  "version": "2.0.0",
+  "version": "2.2.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.",
+  "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": {
     "name": "Andres Massello",
     "url": "https://github.com/andresmassello"

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

@@ -1,6 +1,6 @@
 {
   "name": "uscha",
-  "version": "2.0.0",
+  "version": "2.2.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.0.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v2.2.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`,
@@ -108,6 +108,11 @@ older spec still covers newer code is a relevance judgment, and a guess advises.
 python qa_ledger.py spec-drift --repo <name> --json   # advisory report; exit 0 always
 ```
 
+It searches `repos[<name>].path` first and the **config root** (where `uscha.config.json` and the
+ledger live) second, and the report NAMES which of the two it read (`spec_source`). A monorepo
+keeps ONE `SPEC.md` at the root and it governs every repo — before 2.2.0 that case answered "no
+spec documents", which reads exactly like "no drift".
+
 Map specs to code with a `governs:` glob list in the frontmatter of `SPEC.md` and each
 `docs/adr/*.md`:
 
@@ -128,6 +133,44 @@ decision that governs no source (negative ADRs) — a declaration, not an omissi
 mirador can surface it. No readiness impact, no exit-code gate: a stale spec is a prompt for
 a human conversation, not a blocked pipeline.
 
+## Operability (ADR-048) — release, reset and the RUNBOOK are part of done
+
+A field finding, twice: release by CI, the reset/seed script and the RUNBOOK arrived in the
+**last week** of two projects. The devloop named all four in phase 8 prose, and a narrated
+dimension is not a weak gate — it is an absent one. `operability` reads them as FACTS in the tree:
+
+```bash
+python qa_ledger.py operability --repo <name> [--json]   # exit 0 always
+```
+
+| check | `ok` when |
+|---|---|
+| `ci` | a `.github/workflows/*.yml` step runs the repo's **configured** test command (`repos[R].test_command`, else `defaults.test_command_<type>`) — verbatim, or its first token beside a test-ish subcommand |
+| `release` | a workflow publishes or attaches an asset: `softprops/action-gh-release`, `actions/upload-release-asset`, `gh release create`, `gh release upload`, `gh release`, `npm publish`, `twine upload` |
+| `runbook` | `docs/RUNBOOK.md` (or `RUNBOOK.md`, or `defaults.operability.runbook`) exists AND names start/boot, config, rollback and smoke — EN or ES, case-insensitive; the absent ones are NAMED |
+| `seed` | `repos[R].operability.seed_command` or `defaults.operability.seed_command` is declared, and its script is on disk when the command names a path |
+
+Repo path first, **config root** second (`realpath` on both sides), and the output NAMES which it
+read. It never executes anything. A CI system it does not read — GitLab, Jenkins, Azure — is
+reported `unknown`, never green and never red.
+
+The POSTURE is your risk profile's, not the kit's. `defaults.operability.gate` is `false` by the
+engine's default and `true` on presets **C, D and E**:
+
+- **advisory** (A, B, or no profile): the record caps nothing, blocks nothing, and never joins the
+  `N ok` count in `readiness`;
+- **gate** (C, D, E): a `missing` check is a BLOCKER — readiness capped ≤ 65, convergence blocked,
+  and `phase --require pr-ready` refuses **naming** the missing check.
+
+`readiness` prints one conditional line and stays silent with no record:
+
+```
+--- operability: ci ok · release missing · runbook ok · seed missing (advisory)
+```
+
+Nothing is graded. The engine can see that a `## Rollback` heading exists; whether the procedure
+under it is correct is yours.
+
 ## Evidence origin (ADR-007) - green, but green at *what*?
 
 Freshness compares file mtimes, so the ledger could say "tests green" without being able to
@@ -436,12 +479,47 @@ python uscha-kit/install-uscha.py doctor --target both
 ```
 
 It checks: Python >=3.8 · git · the 9 skills alongside the engine (frontmatter
-verified) · the INV-GOLDEN-01 hook (present + registered in settings.json +
+verified) · **whether the INSTALLED skills are older than this kit** (2.2.0, ADR-045) · the
+INV-GOLDEN-01 hook (present + registered in settings.json +
 powershell/pwsh interpreter) · and if there is a `uscha.config.json` in the cwd:
 config parseable, ACCEPTANCE with AC-IDs, ledger integrity, the QA skills
 from `qa_tools_order` (the loop orchestrates them without bringing them in) and the
 primary toolchain of each repo by type (its absence is a WARNING — it may live only in CI).
 
+**Are the installed skills older than the kit?** (2.2.0, ADR-045.) Every generated `SKILL.md`
+orientation block now opens with `<!-- uscha kit: X.Y.Z -->`, rendered from `uscha-kit/VERSION`
+and re-rendered by the release script at every bump, so an installed skill can be dated. `doctor`
+reads that marker out of each install root the installer writes to — or the ones you name — and
+reports both versions:
+
+```bash
+python3 ~/.claude/skills/uscha-devloop/qa_ledger.py doctor --json
+# -> "kit_version" and "skills_installed": [{target, root, status, installed, kit}]
+python3 .../qa_ledger.py doctor --installed /some/other/skills   # repeatable
+```
+
+`status` is `current`, `outdated` (with **both** versions; `installed: null` when the blocks
+predate 2.2.0 and carry no marker at all) or `not installed` — which is not a fault, since the kit
+installs one agent at a time. This is **advisory**: an outdated install is a warning, never an
+error, and `doctor`'s exit code is unchanged. It exists because a discovery once ran on skills
+from 1.54.0 while the kit was at 1.97.0 and nothing said a word. `/uscha-status` prints the same
+finding as one line above its readout.
+
+The comparison needs BOTH halves, so the installer ships the second one: `install` copies
+`uscha-kit/VERSION` beside the installed skills as **`.uscha-kit-VERSION`**
+(`~/.claude/skills/.uscha-kit-VERSION`, and the equivalent root for `pi`, `cursor`, `copilot`,
+`gemini` and `cline`; the Codex plugin carries the same file at its plugin root), and `uninstall`
+removes it. The name is namespaced on purpose: `~/.claude/skills/` is a directory the kit does not
+own, and a copy called `VERSION` would overwrite whatever else lived under that name and delete it
+on uninstall. **A foreign `VERSION` is never written and never removed** (`AC-SK-08`).
+
+Without that copy an INSTALLED engine has no kit version to compare against and `doctor` says so —
+`installed-skill freshness is UNMEASURED`, naming the directories it read, never a silent
+`current`. Two other sources answer first where they can: the kit checkout itself, reached through
+the engine's REALPATH so a `--mode link` install resolves the kit its skills point into
+(`AC-SK-09`), and `uscha-install.json`'s `version` where the copy was removed by hand. Found by
+running the first-use walkthrough end to end; pinned by `AC-SK-07`, which installs for real.
+
 ## Configure
 
 `uscha init` **generates** a minimal `uscha.config.json` for the project: its name, the repo it
@@ -549,6 +627,9 @@ QL=".claude/skills/uscha-devloop/qa_ledger.py"
 
 python3 $QL --help                                  # see subcommands
 python3 $QL init --config uscha.config.json      # creates QA-LEDGER.json
+# later, a new service joins an existing loop — this APPENDS and re-seals the checksum,
+# it never rebuilds the ledger (2.2.0):
+python3 $QL init --add-repo web-app --path web-app --type node --test-command "npm test"
 
 # run your build with the reports, then:
 python3 $QL snapshot      --repo backend-api --phase pre
@@ -593,6 +674,10 @@ python3 $QL spec-change-request --repo backend-api --source SD-001 --requested-c
   close measured (documented limitation).
 - A lintable repo whose static gate **never ran** scores that dimension UNMEASURED (0.0)
   — silence is not success.
+- **Agent-origin items (kit 2.2.0, ADR-044)**: when `ACCEPTANCE.md`, `docs/adr/*.md` or
+  `HANDOFF.md` carry unconfirmed `(origin: agent)` markers, readiness prints one line of its own
+  — `--- origin: N agent-origin item(s) unconfirmed` — outside the gates rollup. Advisory: it
+  caps nothing and blocks nothing. See below.
 - **Hard caps** (they override the ceiling): tests in red → ≤35, open BLOCKER/CRITICAL → ≤65,
   unresolved escalation → ≤75 (holds until `resolve-escalation`, a recorded event).
 - Bands: `<50 NOT READY` · `50–79 IN PROGRESS` · `80–94 RELEASE CANDIDATE` · `95–100 READY`.
@@ -621,9 +706,9 @@ python3 $QL rebuild --mode compare --baseline REBUILD-BASELINE.json --json   # c
 - Verdicts: `COVERS ≥90` · `PARTIAL ≥70` · `DIVERGE <70`. The score lists the concrete
   **gaps** — feed them back into the SPEC and re-run. Divergence is a spec hole, not a code bug.
 
-## Simplicity gate — "Reduce" (minimality of the change)
+## Simplicity check — "Reduce" (minimality of the change) — ADVISORY by default
 
-The **Simplicity** invariant of the CONSTITUTION made a deterministic gate: it scores the *diff*
+The **Simplicity** invariant of the CONSTITUTION made deterministic: it scores the *diff*
 (not CC by AST — they are measurable proxies: minimality, nesting, new abstractions).
 
 ```bash
@@ -634,21 +719,174 @@ python3 $QL simplicity-check --diff changes.diff --json        # consumed by usc
 
 - Dimensions/weights: diff_size 35, nesting 30, net_growth 20, fan_out 8, blob 7
   (abstraction does NOT weigh in the score — it's a guessy proxy, kept as a metric + advisory flag).
-- Verdicts: `SIMPLE ≥85` · `ACCEPTABLE ≥65` · `OVERBUILT <65` (exit 1 = BLOCKER: trim and re-run).
+- Verdicts: `SIMPLE ≥85` · `ACCEPTABLE ≥65` · `OVERBUILT <65`.
   A gross excess (2× budget, or very deep nesting) caps the score at 60 no matter what.
+- **Advisory by default, exit 0** (kit 2.1.0, ADR-043): every budget above is the KIT's opinion
+  until you declare your own, and an opinion that exits 1 is a gate nobody asked for. It
+  **gates** — OVERBUILT = exit 1 = BLOCKER — only with at least one budget declared in
+  `defaults.simplicity` **AND** `defaults.simplicity.gate: true` (or `--gate`). `gate: true`
+  with no budget declared is a config error, exit 2: a gate with no budget is not a gate.
+  `log-gate --kind simplicity --verdict advisory` persists an advisory run as an advisory —
+  readiness prints `N ok · 1 advisory` and the mirador reads `ADVISORY`, never `OK`.
+- **`max_nesting` is an INDENTATION-DEPTH proxy**, not AST nesting: it reads leading
+  indentation on added lines, so a wrapped argument, JSX, or a multi-line Java literal inflates
+  it with no control flow present. It is named as a proxy in the report rather than made
+  language-aware. 2-space codebase → `--indent-width 2`.
 - **Tests OUT of the budget** (kit 1.11.0): the test files (conventions of the
   9 stacks) are counted and reported separately (`test_lines_added`) but do not gate — writing
   tests never pushes the diff to OVERBUILT (deleting them is already blocked by gate-check).
 - The flags tell you what to trim (guard clauses, speculative types/layers, giant hunks).
-- Budgets in `defaults.simplicity`; adjustable per risk profile. 2-space → `--indent-width 2`.
+- Budgets in `defaults.simplicity`. No risk profile owns them: the gate is a human declaration
+  under every profile A–E.
 
-## Ledger subcommands
+## Agent-origin markers — ask for DECISIONS, never for INFORMATION (ADR-044)
+
+Two field findings, one rule. **Information the tree holds is READ, never asked**: the current
+version of a tracked `.md`, what a config says, whether a test exists. And **a decision the human
+never made never enters scope silently** — an agent turned a global default into a tree-wide
+rename that was approved by rebound inside a twenty-item summary, and had to be cancelled after
+112 files had moved.
 
-`bench - bench-curate - bench-r2 - bench-roundtrip - bootstrap-oracle - bootstrap-variance - check-coverage - check-terminado - cleanroom - compile-ingest - compile-validate - converged - curate - curation-check - dashboard - discover - doctor - escalate - execution-policy - facts - fastpath-eval - fidelity - flag-blocker - gate-check - golden-coverage - golden-diff - ingest-gate - init - ir-extract - ir-render - lang-compare - log-gate - log-step - oscillation - phase - pit-check - production-finding - promote - readiness - rebuild - regression-check - resolve-escalation - roundtrip - rubric-ingest - simplicity-check - snapshot - spec-change-request - spec-check - spec-doubt - spec-drift - summary - top - waste-check` - the exact current `qa_ledger.py` parser surface (53 subcommands, derived from `SYSTEM-FACTS.json`, itself introspected from `build_parser()`); each supports `--help`.
+So anything the AGENT introduced — an acceptance criterion, an ADR decision item, a `HANDOFF.md`
+rule — carries one trailing marker on its own line:
+
+```
+- [ ] AC-12 — when X then Y. (origin: agent)
+- [ ] AC-12 — when X then Y. (origin: agent, confirmed: 2026-09-07)
+```
+
+- **No marker = human origin.** That is the default, so nothing already written is retro-tagged.
+- **Confirmation is PER ITEM**, recorded as `confirmed: YYYY-MM-DD` on the same line. A
+  package-level "ok" confirms none of them, which is the whole point.
+- **An unconfirmed item is not in scope**: it is not implemented, not gated on, not quoted as
+  agreed.
+- A `confirmed:` that is not a real `YYYY-MM-DD` date counts as **unconfirmed** and is named — a
+  typo must never read as a human's approval.
+- A marker inside a fenced block or an inline code span (like the two above) is documentation and
+  is skipped, so a file that DEFINES the grammar is not read as a finding.
+
+What the engine does with it, on the files it already reads plus `ACCEPTANCE.md`, `docs/adr/*.md`
+and `HANDOFF.md`:
+
+```bash
+python3 $QL spec-check --spec SPEC.md --acceptance ACCEPTANCE.md
+#   ~ origin: 2 agent-origin item(s) unconfirmed -- AC-07 (ACCEPTANCE.md:41), D-03 (docs/adr/ADR-002-x.md:57)
+python3 $QL readiness
+#   --- origin: 2 agent-origin item(s) unconfirmed   (spec-check names them)
+```
+
+**ADVISORY, both of them.** `spec-check` keeps the exit code it had; `readiness` prints its line
+outside the gates rollup and caps nothing, blocks nothing, and changes no score. A gate here would
+need a budget the project adopted, and nobody has declared one (the 2.1.0 posture, ADR-043).
+`spec-check --json` carries `agent_origin: {unconfirmed: [...], confirmed: n}`; `readiness --json`
+carries the same object when there is anything to report. A tree with no marker anywhere prints
+exactly what it printed before.
+
+## Field truth for greenfield — `corpus-run` (ADR-046)
+
+From a live greenfield build: *the parser passed every test the agent wrote, and it was wrong.*
+Running the REAL corpus is what exposed it — 96.96 % before the fix, 99.645 % after. In greenfield
+every test payload is invented by the agent that writes the code, so a green suite can be silent
+about the inputs the world actually produces; and `characterize`/`golden-diff` have no answer
+there, because their doctrine is *the old code is the truth* and there is no old code.
+
+The corpus is **JSONL** — one object per line, `input` and `expected` required, `id` optional:
+
+```jsonl
+{"id": "inv-2019-03", "input": "...raw payload...", "expected": {"total": 1042, "currency": "EUR"}}
+```
+
+Each case runs the command once with its input on **stdin** (verbatim when it is a string,
+JSON-encoded otherwise); the trimmed **stdout** is compared to `expected` — string compare, then
+JSON-equal when both sides parse as JSON. A non-zero exit is a miss named with its code; a case
+past `--timeout` (default 30 s) is a miss named `timeout`. File order is run order, so two runs
+over one corpus report the same misses in the same places.
+
+```bash
+python3 $QL corpus-run --repo <REPO> --corpus corpus/real.jsonl --command "python -m myparser"   --threshold 99 --ac AC-FIELD-01
+#   [qa_ledger] backend-api/gate:corpus: FAIL 96.96 % (3195/3295) — threshold 99 % from --threshold
+python3 $QL readiness
+#   --- field backend-api: corpus 96.96 % (3195/3295) < 99 % FAIL
+```
+
+- **The threshold is yours**: `--threshold`, else `repos[R].corpus_threshold`, else
+  `defaults.corpus_threshold`. With **none declared the run is ADVISORY** — measured, persisted,
+  gating nothing, and never counted as an `ok` gate (the 2.1.0 posture, ADR-043). With one
+  declared, a run under it caps readiness ≤65 and blocks convergence like any fact gate.
+- **A corpus that cannot be read is exit 2, naming the line** — missing, empty, malformed, or
+  missing an `input`/`expected` key. An unreadable corpus scored as 0 % would be an unmeasurable
+  input reported as a measured catastrophe.
+- **`--ac AC-nn` closes a criterion MEASURED on a green run**, exactly as a green testcase does; a
+  ticked criterion whose only corpus evidence is red or advisory reports `narrated_only`.
+- **`log-gate --kind corpus`** records a run measured elsewhere (CI, a nightly) and is the third
+  and last kind that accepts `--verdict advisory`, because the check's own default mode is
+  advisory. Every other FACT kind still refuses it.
+- **No weight.** `readiness` prints one conditional `field` line per repo that declares a corpus
+  or ran one, and nothing else moves; the `field` *dimension* is deferred to its own ADR.
+- **Never author the corpus yourself.** A corpus the agent invented is the invented input this
+  instrument exists to expose.
+
+## The smoke run as measured evidence — `smoke-ingest` (ADR-047)
+
+From the field: *every simulator run returned an empty list, because the database had no rows —
+and the smoke was reported as verified.* An empty list is a 200. Phase 7 used to end in a
+paragraph — "the jar served /admin", "the simulator answered 200 in 6 ms" — and a paragraph
+cannot tell "the endpoint answered correctly" from "the endpoint answered". **Evidence is
+executed, not narrated.**
+
+The contract is the smallest thing a shell script can emit — `name` and a **boolean** `ok` are the
+whole mandatory surface:
+
+```json
+{"checks": [{"name": "AC-28 the jar serves /admin", "ok": true, "status": 200,
+             "latency_ms": 6, "evidence": "curl -sS localhost:8080/admin | head -1"}]}
+```
+
+```bash
+python3 $QL smoke-ingest --repo <REPO> --report reports/smoke.json
+#   [qa_ledger] backend-api/gate:smoke: FAIL — 7/8 checks ok
+#     FAIL healthz (status 503)
+#     caps readiness <=65 and blocks convergence until a clean smoke
+python3 $QL readiness
+#   --- smoke backend-api: 7/8 checks ok, 1 failed (healthz) FAIL
+```
+
+- **A failed check is a BLOCKER**, through the same record `gate-check` writes: readiness ≤65,
+  convergence blocked, cleared by a later clean report.
+- **A report the engine cannot read is exit 2, naming the check or the field** — missing,
+  malformed, no `checks` key, a check with no `name` or no boolean `ok`. An **EMPTY** `checks`
+  list is refused too: a run that verified nothing is not a clean gate.
+- **`smoke` is a FACT kind and never runs advisory.** `corpus` may (a percentage needs an adopted
+  budget); `ok` is binary, so an advisory smoke would be a mandatory gate cleared by goodwill.
+  `log-gate --kind smoke --verdict pass|fail|not-run` is the parity door.
+- **A check named `AC-nn ...` closes that criterion MEASURED** when it is `ok` and its report
+  passed — the same tag grammar a JUnit testcase name uses. A **failed** tagged check VETOES,
+  exactly like a red test, and `readiness --json` reports both halves
+  (`acceptance.smoke_closed`, `acceptance.smoke_vetoed`).
+- **No weight.** One conditional `smoke` line per repo that ingested a report, and nothing else
+  moves.
+- **`templates/scripts/smoke-report-example.json`** is the reference report (three checks, one
+  tagged `AC-01`). Never narrate the report: a checklist a human ticked is evidence, a checklist
+  an agent wrote is not.
+
+## Ledger subcommands
 
-The **fact gates** (golden-diff, gate-check, pit-check, simplicity) are PERSISTED with
-`log-gate`: a fail blocks convergence and caps readiness ≤65 via the ledger. A CONSTITUTION
-violation is recorded with `flag-blocker` (same effect, until `--resolve`).
+`bench - bench-curate - bench-r2 - bench-roundtrip - bootstrap-oracle - bootstrap-variance - check-coverage - check-terminado - cleanroom - compile-ingest - compile-validate - converged - corpus-run - curate - curation-check - dashboard - discover - doctor - escalate - execution-policy - facts - fastpath-eval - fidelity - flag-blocker - gate-check - golden-coverage - golden-diff - ingest-gate - init - ir-extract - ir-render - lang-compare - log-gate - log-step - operability - oscillation - phase - pit-check - production-finding - promote - readiness - rebuild - regression-check - resolve-escalation - roundtrip - rubric-ingest - simplicity-check - smoke-ingest - snapshot - spec-change-request - spec-check - spec-doubt - spec-drift - summary - top - waste-check` - the exact current `qa_ledger.py` parser surface (56 subcommands, derived from `SYSTEM-FACTS.json`, itself introspected from `build_parser()`); each supports `--help`.
+
+`gate-check --repo R` SCOPES the diff to `repos[R].path` (2.2.0): in a monorepo one `git diff`
+carries every repo's hunks, and a sibling's findings are neither this repo's report nor this
+repo's exit code. A rename is reported under `moved` — informational, never a deletion — both
+from git's own rename headers (`--from-git` forces `-M`, so the caller's `diff.renames` config
+cannot hide one) and from an exact delete/add pair in a diff whose producer detected none. A
+real deletion still blocks.
+
+The **fact gates** (golden-diff, gate-check, pit-check, simplicity, **ci**) are PERSISTED with
+`log-gate`: a fail blocks convergence and caps readiness ≤65 via the ledger; `--verdict
+advisory` records a run that is measured but not gating (it caps nothing, blocks nothing, and
+never counts as an `ok` gate) and is accepted ONLY for `simplicity|waste` — every FACT gate
+refuses it. `--kind ci` (2.2.0) records what the pipeline did, with `--ref <run URL or id>`
+stored on the record as the receipt; a `ci` fail caps and blocks exactly like `gate-check`. A CONSTITUTION violation is recorded with `flag-blocker` (same
+effect, until `--resolve`).
 
 ## Notes
 

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 2.0.0
+uscha-kit 2.2.0

package/uscha-kit/install-uscha.py

@@ -33,6 +33,13 @@ SKILL_ROOTS = {
 }
 TARGETS = ("codex", "claude") + tuple(SKILL_ROOTS)
 HOOK_NAME = "block-approved-writes.py"
+# The kit's version, copied beside the installed skills so an INSTALLED engine can date them
+# (ADR-045). The name is NAMESPACED (2.2.0, fresh review): until this release the copy was
+# called `VERSION`, a bare shared name written into directories the kit does not own --
+# `~/.claude/skills/`, `~/.cursor/skills/` -- where an install would overwrite whatever else
+# lived under it and an uninstall would delete it. An installer owns the files it creates and
+# nothing else, and the only way to guarantee that is to claim a name nobody else would pick.
+KIT_VERSION_COPY = ".uscha-kit-VERSION"
 
 
 class InstallError(Exception):
@@ -274,7 +281,7 @@ def stage_plugin(plugin_root, mode):
         (stage / "skills").mkdir()
         for skill in SKILLS:
             copy_skill(source / skill, stage / "skills" / skill, mode)
-        shutil.copy2(KIT_ROOT / "VERSION", stage / "VERSION")
+        shutil.copy2(KIT_ROOT / "VERSION", stage / KIT_VERSION_COPY)
         shutil.copy2(KIT_ROOT / "uscha.config.json", stage / "uscha.config.json")
         return stage
     except Exception:
@@ -366,7 +373,7 @@ def install_claude(home, mode, dry_run, operations):
     data = prepared_settings(settings, hook_command(hook))  # parse and merge before writes, including dry-run
     marker_data = marker("claude", root, mode)
     operations.extend({"action": "install-skill", "path": str(root / "skills" / skill)} for skill in SKILLS)
-    operations.extend([{"action": "copy-hook", "path": str(hook)}, {"action": "atomic-write-json", "path": str(settings)}, {"action": "write-marker-last", "path": str(install_marker)}])
+    operations.extend([{"action": "copy-version", "path": str(root / "skills" / KIT_VERSION_COPY)}, {"action": "copy-hook", "path": str(hook)}, {"action": "atomic-write-json", "path": str(settings)}, {"action": "write-marker-last", "path": str(install_marker)}])
     if dry_run:
         return root
 
@@ -383,6 +390,7 @@ def install_claude(home, mode, dry_run, operations):
             copy_skill(source / skill, staged / "skills" / skill, mode)
         (staged / "hooks").mkdir()
         shutil.copy2(KIT_ROOT / "hooks" / HOOK_NAME, staged / "hooks" / HOOK_NAME)
+        shutil.copy2(KIT_ROOT / "VERSION", staged / "skills" / KIT_VERSION_COPY)
         atomic_json(staged / "settings.json", data)
         atomic_json(staged / "uscha-install.json", marker_data)
 
@@ -390,6 +398,8 @@ def install_claude(home, mode, dry_run, operations):
         entries = [(skills_root / skill, staged / "skills" / skill, backups / "skills" / skill)
                    for skill in SKILLS]
         entries.extend([
+            (skills_root / KIT_VERSION_COPY, staged / "skills" / KIT_VERSION_COPY,
+             backups / "skills" / KIT_VERSION_COPY),
             (hook, staged / "hooks" / HOOK_NAME, backups / "hooks" / HOOK_NAME),
             (settings, staged / "settings.json", backups / "settings.json"),
             (install_marker, staged / "uscha-install.json", backups / "uscha-install.json"),
@@ -456,6 +466,7 @@ def install_skills_only(target, home, mode, dry_run, operations):
     install_marker = root / "uscha-install.json"
     marker_data = marker(target, root, mode)
     operations.extend({"action": "install-skill", "path": str(root / skill)} for skill in SKILLS)
+    operations.append({"action": "copy-version", "path": str(root / KIT_VERSION_COPY)})
     operations.append({"action": "write-marker-last", "path": str(install_marker)})
     if dry_run:
         return root
@@ -471,9 +482,12 @@ def install_skills_only(target, home, mode, dry_run, operations):
         backups.mkdir()
         for skill in SKILLS:
             copy_skill(source / skill, staged / skill, mode)
+        shutil.copy2(KIT_ROOT / "VERSION", staged / KIT_VERSION_COPY)
         atomic_json(staged / "uscha-install.json", marker_data)
 
         entries = [(root / skill, staged / skill, backups / skill) for skill in SKILLS]
+        entries.append((root / KIT_VERSION_COPY, staged / KIT_VERSION_COPY,
+                        backups / KIT_VERSION_COPY))
         entries.append((install_marker, staged / "uscha-install.json", backups / "uscha-install.json"))
         # The loops below bind PATHS. They must NOT be named `target`: a Python for-loop has no
         # scope of its own, so that would permanently rebind this function's `target` argument
@@ -1056,11 +1070,13 @@ def uninstall_target(target, home, dry_run, operations, force):
     elif target in SKILL_ROOTS:
         for skill in SKILLS:
             drop(root / skill, "uscha skill")
+        drop(root / KIT_VERSION_COPY, "kit version beside the installed skills")
         drop(marker_path, "install marker")
     else:
         skills_root = root / "skills"
         for skill in SKILLS:
             drop(skills_root / skill, "uscha skill")
+        drop(skills_root / KIT_VERSION_COPY, "kit version beside the installed skills")
         drop(root / "hooks" / HOOK_NAME, "INV-GOLDEN-01 hook")
         drop(marker_path, "install marker")
         settings_path = root / "settings.json"