@andresmassello/uscha 1.51.1 → 1.53.0

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

@@ -1,161 +1,192 @@
----
-name: uscha-mirador
-description: >
-  Bird's-eye status view ("mirador") of a spec-loop project: one glance at
-  readiness, sub-scores, the phase path, invariants, QA loops and a readiness
-  time-lapse. Runs `qa_ledger.py dashboard --json` (read-only, deterministic,
-  zero LLM narration), injects that JSON into mirador.template.html, writes
-  mirador.html at the project root and opens it. The skill WIRES, it does not
-  calculate — every number comes from the ledger (truth-pass: a field with no
-  source shows null and the template degrades, never invented). Invoke for
-  "mirador", "vista de estado", "bird's-eye", "dashboard del proyecto".
-allowed-tools: Read, Write, Glob, Grep, Bash
----
-
-# uscha-mirador — bird's-eye status view
-
-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.
-
-## Contract
-
-- **Source of truth:** `qa_ledger.py dashboard --json` — aggregates ONLY state the
-  ledger already has (readiness, subscores, phases, acceptance, adrs, inv, layers, loops,
-  snapshots, evidence). A field with no source comes out `null`/`[]`; the template
-  degrades. **A datum is never invented.**
-- **Template:** `mirador.template.html` (in this folder). The data block lives between
-  `/*MIRADOR_DATA_START*/` and `/*MIRADOR_DATA_END*/`; the sample `const DATA` it ships
-  with is the **offline fallback**. The skill replaces ONLY that region; it does not
-  touch the rest of the HTML.
-- **Project name (top):** the mirador shows the project name prominently at the top, from
-  `config.project` in `uscha.config.json` (set it in `uscha-discovery`); if unset, it falls
-  back to the joined repo names (truth-pass — no invented name).
-- **Execution policy (bird's-eye):** `dashboard --json` also exposes
-  `execution_policy` plus `phase.execution` for each trail node. This is routing metadata
-  from `config.defaults.execution_policy` (`method`, `tier`, `model`, `effort`,
-  `uncorrelated`), not a score. The template renders it as a separate panel so the human
-  sees which methodology/model/effort is selected per phase without mixing it into
-  readiness.
-- **Discovery intake:** `dashboard --json` carries `discovery_intake` from readiness:
-  open `production_findings`, `spec_doubts`, and `spec_change_requests`. The current template keeps the top-level
-  verdict honest through readiness/caps; future panels may render the intake directly.
-- **ADR experiments:** ADR rows may carry `adr_status: "experiment"`, `review_by`,
-  `review_trigger`, `experiment_valid`, `experiment_missing`, and `expired`; top-level
-  `adr_experiments` summarizes open/malformed/expired experiments. This is advisory
-  visibility for measured hypotheses, not readiness scoring.
-- **Session telemetry (optional, vendor-reported):** if `.uscha/telemetry.jsonl` exists,
-  the skill aggregates it and MERGES a `telemetry` object into `DATA`. This is the ONE
-  panel that is **narrated by the vendor (Claude Code), not measured by the engine** —
-  tokens, wall time, model, effort — so it renders in a **segregated strip** labeled as
-  such, never mixed with the measured panels. `dashboard --json` NEVER emits it; it enters
-  only through this adapter. Absent file → no strip (degrades). This is the doctrinal
-  line: telemetry is neither a fact-gate nor a guess-advisor, so it must not dilute
-  *measured beats narrated*.
-
-## Flow
-
-1. **Resolve the engine.** Use the first one that exists:
-   - `./.claude/skills/uscha-devloop/qa_ledger.py` (per-project install)
-   - `~/plugins/uscha/skills/uscha-devloop/qa_ledger.py` (Codex plugin install)
-   - `~/.codex/skills/uscha-devloop/qa_ledger.py` (Codex raw-skills install)
-   - `~/.claude/skills/uscha-devloop/qa_ledger.py` (Claude global install)
-
-2. **Resolve the ledger.** `QA-LEDGER.json` in the cwd (or the `--ledger` the user
-   points to). If it does not exist, warn: you have to run `uscha-devloop` (or
-   `qa_ledger.py init`) first — with no ledger there is no state to look at.
-
-   (`<skill-dir>` below = this folder: `.claude/skills/uscha-mirador/` per-project, or `~/plugins/uscha/skills/uscha-mirador/` / `~/.codex/skills/uscha-mirador/` / `~/.claude/skills/uscha-mirador/` global.)
-
-3. **(Optional) record this session's telemetry.** For the vendor-telemetry strip, append
-   the current Claude Code session to the sidecar:
-   ```bash
-   python3 <skill-dir>/telemetry-extract.py <path-to-CC-transcript.jsonl>
-   ```
-   It **upserts by session** (safe to re-run — a watch loop won't inflate the totals). Skip
-   this for a pure measured view.
-
-4. **Render `mirador.html`** with the standalone renderer — it runs `dashboard --json`,
-   merges the sidecar telemetry if present, injects `const DATA`, writes the file, prints its
-   absolute path (`OPEN IT: ...`), and opens it in the default browser. From the project root,
-   with no long paths — `--engine` and `--template` default to the renderer's sibling skill
-   files (kit 1.41.2):
-   ```bash
-   python3 <skill-dir>/mirador-render.py --ledger QA-LEDGER.json
-   ```
-   The engine stays model-agnostic — telemetry is merged by the renderer (the adapter), NOT
-   by `dashboard`. If the ledger is missing, warn and stop (run `uscha-devloop` first). The
-   time-lapse feeds from `qa_ledger.py readiness --record` — since kit 1.47.0 the dev-loop
-   records at every pass close, so history accumulates without extra ceremony.
-
-5. **Where to look:** the renderer already opened `mirador.html` and printed its absolute path
-   on the `OPEN IT:` line — surface that path to the operator. Pass `--no-open` to write the
-   file without opening a browser (headless/CI, or the watch loop below, which passes it).
-
-## For a human at a terminal: `uscha mirador`
-
-The one-liner above is what THIS skill runs. A human who just wants the dashboard — without a
-Claude Code session — has a zero-friction verb instead (kit 1.43.0): from the project root,
-
-```bash
-uscha mirador            # render + open, defaults to the QA-LEDGER.json convention
-uscha mirador --watch    # live second-screen view (auto-refresh, one self-reloading tab)
-npx @andresmassello/uscha mirador   # same, no install
-```
-
-No python, no paths: the verb resolves the engine, template and ledger on its own.
-
-## Live second-screen view
-
-For a mirador that updates while you keep coding in the terminal, run the watch loop in a
-spare terminal and open `mirador.html` on a second monitor (or just use `uscha mirador --watch`):
-
-```bash
-# Windows:  powershell -NoProfile -File <skill-dir>\mirador-watch.ps1 -Interval 30
-# Unix:     bash <skill-dir>/mirador-watch.sh 30
-```
-
-It re-renders `mirador.html` every N seconds (default 30) from the current ledger, rendered
-with a matching `<meta http-equiv="refresh">` so the open page reloads on its own — **no
-server**. It is only as live as the **ledger**: the picture changes at the dev-loop's
-measured checkpoints (snapshots, gates, `readiness --record`), not per keystroke. Honest by
-design — it shows measured state, which changes at measured moments.
-
-## Session telemetry — sidecar contract
-
-`.uscha/telemetry.jsonl` is an **append-only** file, one JSON object per session/run:
-
-```jsonl
-{"at": "2026-07-05T23:40:00Z", "model": "claude-opus-4-8", "tokens_in": 240000, "tokens_out": 41000, "ms": 4200000, "by_model": [{"model": "claude-opus-4-8", "tokens_in": 240000, "tokens_out": 41000}], "note": "mirador build"}
-```
-
-`effort` and `note` are **optional** and are NOT produced by `telemetry-extract.py` (a Claude
-Code transcript carries no reliable effort label) — add them by hand if you want them; the
-strip shows `—` when `effort` is absent. `by_model` is per-**tokens** (session-level `ms` only).
-
-- **Who writes it:** the AGENT / operator, NEVER the engine (the engine is model-agnostic
-  and cannot see tokens). Two honest sources:
-  - **`telemetry-extract.py <transcript.jsonl>`** (shipped in this skill folder): parses a
-    Claude Code session transcript — each assistant turn carries a `usage` block
-    (`input_tokens` / `cache_*_input_tokens` / `output_tokens`) and a `model` — sums per
-    model, computes wall time from the timestamps, and appends one line (with a `by_model`
-    breakdown). Real, vendor-native data. Best-effort: unknown/older schemas degrade, never
-    crash; no usage found → nothing appended.
-  - **Manual append**: paste the session's numbers from Claude Code's own cost view.
-- **Persistence:** the file itself IS the history (portable, diffable, greppable). Add it to
-  the project's `.gitignore` — it is per-machine telemetry, not repo state. (A pure-client
-  alternative is `localStorage` inside `mirador.html`, but the sidecar survives regeneration,
-  so it is the default.)
-- **Boundary (non-negotiable):** this is the ONLY place vendor-narrated numbers enter the
-  mirador. They are shown, never gated, never fed into readiness — telemetry answers "what
-  did it cost", the measured panels answer "is it correct". Keep them apart.
-
-## Rules
-
-- **Zero computation in the skill.** The numbers come from the ledger. If a panel looks
-  empty, it's because the engine doesn't have that source yet (truth-pass), not because
-  painting it was missed.
-- **Read-only.** The skill does not run gates or modify the ledger. `dashboard` is
-  read-only; the only one that writes (opt-in) is `readiness --record`, and that is the
-  loop's decision, not this skill's.
-- **`mirador.html` is a generated artifact** — suggest adding it to the project's
-  `.gitignore`; it regenerates whenever you want.
+---
+name: uscha-mirador
+description: >
+  Bird's-eye status view ("mirador") of a spec-loop project: one glance at
+  readiness, sub-scores, the phase path, invariants, QA loops and a readiness
+  time-lapse. Runs `qa_ledger.py dashboard --json` (read-only, deterministic,
+  zero LLM narration), injects that JSON into mirador.template.html, writes
+  mirador.html at the project root and opens it. The skill WIRES, it does not
+  calculate — every number comes from the ledger (truth-pass: a field with no
+  source shows null and the template degrades, never invented). Invoke for
+  "mirador", "vista de estado", "bird's-eye", "dashboard del proyecto".
+allowed-tools: Read, Write, Glob, Grep, Bash
+---
+
+# uscha-mirador — bird's-eye status view
+
+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.
+
+## Orientation markers (non-negotiable)
+
+The operator must never have to ask "where am I?" or "what happens now?".
+
+This skill is a **one-shot read-only readout**: its block IS the answer. It therefore does NOT
+take the conversational close block — that would be exactly the padding this skill forbids.
+It carries the two minimal markers instead.
+
+**Open with a breadcrumb:**
+
+`[uscha · mirador · step <n> → <target>]`
+
+**End with the two routing lines, and nothing else:**
+
+```
+Next: <the next action, derived from what this readout just showed>
+Run:  <the exact command or skill to invoke>
+```
+
+`Next` is **derived** from the state you just read — never copied from a fixed route,
+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.
+
+## Contract
+
+- **Source of truth:** `qa_ledger.py dashboard --json` — aggregates ONLY state the
+  ledger already has (readiness, subscores, phases, acceptance, adrs, inv, layers, loops,
+  snapshots, evidence). A field with no source comes out `null`/`[]`; the template
+  degrades. **A datum is never invented.**
+- **Template:** `mirador.template.html` (in this folder). The data block lives between
+  `/*MIRADOR_DATA_START*/` and `/*MIRADOR_DATA_END*/`; the sample `const DATA` it ships
+  with is the **offline fallback**. The skill replaces ONLY that region; it does not
+  touch the rest of the HTML.
+- **Project name (top):** the mirador shows the project name prominently at the top, from
+  `config.project` in `uscha.config.json` (set it in `uscha-discovery`); if unset, it falls
+  back to the joined repo names (truth-pass — no invented name).
+- **Execution policy (bird's-eye):** `dashboard --json` also exposes
+  `execution_policy` plus `phase.execution` for each trail node. This is routing metadata
+  from `config.defaults.execution_policy` (`method`, `tier`, `model`, `effort`,
+  `uncorrelated`), not a score. The template renders it as a separate panel so the human
+  sees which methodology/model/effort is selected per phase without mixing it into
+  readiness.
+- **Discovery intake:** `dashboard --json` carries `discovery_intake` from readiness:
+  open `production_findings`, `spec_doubts`, and `spec_change_requests`. The current template keeps the top-level
+  verdict honest through readiness/caps; future panels may render the intake directly.
+- **ADR experiments:** ADR rows may carry `adr_status: "experiment"`, `review_by`,
+  `review_trigger`, `experiment_valid`, `experiment_missing`, and `expired`; top-level
+  `adr_experiments` summarizes open/malformed/expired experiments. This is advisory
+  visibility for measured hypotheses, not readiness scoring.
+- **Session telemetry (optional, vendor-reported):** if `.uscha/telemetry.jsonl` exists,
+  the skill aggregates it and MERGES a `telemetry` object into `DATA`. This is the ONE
+  panel that is **narrated by the vendor (Claude Code), not measured by the engine** —
+  tokens, wall time, model, effort — so it renders in a **segregated strip** labeled as
+  such, never mixed with the measured panels. `dashboard --json` NEVER emits it; it enters
+  only through this adapter. Absent file → no strip (degrades). This is the doctrinal
+  line: telemetry is neither a fact-gate nor a guess-advisor, so it must not dilute
+  *measured beats narrated*.
+
+## Flow
+
+1. **Resolve the engine.** Use the first one that exists:
+   - `./.claude/skills/uscha-devloop/qa_ledger.py` (per-project install)
+   - `~/plugins/uscha/skills/uscha-devloop/qa_ledger.py` (Codex plugin install)
+   - `~/.codex/skills/uscha-devloop/qa_ledger.py` (Codex raw-skills install)
+   - `~/.claude/skills/uscha-devloop/qa_ledger.py` (Claude global install)
+
+2. **Resolve the ledger.** `QA-LEDGER.json` in the cwd (or the `--ledger` the user
+   points to). If it does not exist, warn: you have to run `uscha-devloop` (or
+   `qa_ledger.py init`) first — with no ledger there is no state to look at.
+
+   (`<skill-dir>` below = this folder: `.claude/skills/uscha-mirador/` per-project, or `~/plugins/uscha/skills/uscha-mirador/` / `~/.codex/skills/uscha-mirador/` / `~/.claude/skills/uscha-mirador/` global.)
+
+3. **(Optional) record this session's telemetry.** For the vendor-telemetry strip, append
+   the current Claude Code session to the sidecar:
+   ```bash
+   python3 <skill-dir>/telemetry-extract.py <path-to-CC-transcript.jsonl>
+   ```
+   It **upserts by session** (safe to re-run — a watch loop won't inflate the totals). Skip
+   this for a pure measured view.
+
+4. **Render `mirador.html`** with the standalone renderer — it runs `dashboard --json`,
+   merges the sidecar telemetry if present, injects `const DATA`, writes the file, prints its
+   absolute path (`OPEN IT: ...`), and opens it in the default browser **the first time it
+   creates the file** (see step 5 — a re-render updates the open tab instead). From the project root,
+   with no long paths — `--engine` and `--template` default to the renderer's sibling skill
+   files (kit 1.41.2):
+   ```bash
+   python3 <skill-dir>/mirador-render.py --ledger QA-LEDGER.json
+   ```
+   The engine stays model-agnostic — telemetry is merged by the renderer (the adapter), NOT
+   by `dashboard`. If the ledger is missing, warn and stop (run `uscha-devloop` first). The
+   time-lapse feeds from `qa_ledger.py readiness --record` — since kit 1.47.0 the dev-loop
+   records at every pass close, so history accumulates without extra ceremony.
+
+5. **Where to look:** the renderer opens `mirador.html` **once — only the first time it is
+   created** — and always prints its absolute path on the `OPEN IT:` line; surface that path to
+   the operator. Re-rendering (this skill invoked again on a later pass, or the watch loop)
+   rewrites the SAME file, and the page's built-in auto-refresh reloads the already-open tab in
+   place, so a re-render never spawns a new browser tab. On a fresh session the file is already
+   on disk, so nothing pops — open the printed path once, or pass `--open` (`uscha mirador
+   --open`) to force a reopen when you closed the tab. `--no-open` suppresses opening
+   everywhere and wins over `--open` (headless/CI, or the watch loop, which passes it);
+   `--refresh 0` writes a frozen snapshot with no auto-reload.
+
+## For a human at a terminal: `uscha mirador`
+
+The one-liner above is what THIS skill runs. A human who just wants the dashboard — without a
+Claude Code session — has a zero-friction verb instead (kit 1.43.0): from the project root,
+
+```bash
+uscha mirador            # render + open, defaults to the QA-LEDGER.json convention
+uscha mirador --watch    # live second-screen view (auto-refresh, one self-reloading tab)
+npx @andresmassello/uscha mirador   # same, no install
+```
+
+No python, no paths: the verb resolves the engine, template and ledger on its own.
+
+## Live second-screen view
+
+For a mirador that updates while you keep coding in the terminal, run the watch loop in a
+spare terminal and open `mirador.html` on a second monitor (or just use `uscha mirador --watch`):
+
+```bash
+# Windows:  powershell -NoProfile -File <skill-dir>\mirador-watch.ps1 -Interval 30
+# Unix:     bash <skill-dir>/mirador-watch.sh 30
+```
+
+It re-renders `mirador.html` every N seconds (default 30) from the current ledger, rendered
+with a matching `<meta http-equiv="refresh">` so the open page reloads on its own — **no
+server**. It is only as live as the **ledger**: the picture changes at the dev-loop's
+measured checkpoints (snapshots, gates, `readiness --record`), not per keystroke. Honest by
+design — it shows measured state, which changes at measured moments.
+
+## Session telemetry — sidecar contract
+
+`.uscha/telemetry.jsonl` is an **append-only** file, one JSON object per session/run:
+
+```jsonl
+{"at": "2026-07-05T23:40:00Z", "model": "claude-opus-4-8", "tokens_in": 240000, "tokens_out": 41000, "ms": 4200000, "by_model": [{"model": "claude-opus-4-8", "tokens_in": 240000, "tokens_out": 41000}], "note": "mirador build"}
+```
+
+`effort` and `note` are **optional** and are NOT produced by `telemetry-extract.py` (a Claude
+Code transcript carries no reliable effort label) — add them by hand if you want them; the
+strip shows `—` when `effort` is absent. `by_model` is per-**tokens** (session-level `ms` only).
+
+- **Who writes it:** the AGENT / operator, NEVER the engine (the engine is model-agnostic
+  and cannot see tokens). Two honest sources:
+  - **`telemetry-extract.py <transcript.jsonl>`** (shipped in this skill folder): parses a
+    Claude Code session transcript — each assistant turn carries a `usage` block
+    (`input_tokens` / `cache_*_input_tokens` / `output_tokens`) and a `model` — sums per
+    model, computes wall time from the timestamps, and appends one line (with a `by_model`
+    breakdown). Real, vendor-native data. Best-effort: unknown/older schemas degrade, never
+    crash; no usage found → nothing appended.
+  - **Manual append**: paste the session's numbers from Claude Code's own cost view.
+- **Persistence:** the file itself IS the history (portable, diffable, greppable). Add it to
+  the project's `.gitignore` — it is per-machine telemetry, not repo state. (A pure-client
+  alternative is `localStorage` inside `mirador.html`, but the sidecar survives regeneration,
+  so it is the default.)
+- **Boundary (non-negotiable):** this is the ONLY place vendor-narrated numbers enter the
+  mirador. They are shown, never gated, never fed into readiness — telemetry answers "what
+  did it cost", the measured panels answer "is it correct". Keep them apart.
+
+## Rules
+
+- **Zero computation in the skill.** The numbers come from the ledger. If a panel looks
+  empty, it's because the engine doesn't have that source yet (truth-pass), not because
+  painting it was missed.
+- **Read-only.** The skill does not run gates or modify the ledger. `dashboard` is
+  read-only; the only one that writes (opt-in) is `readiness --record`, and that is the
+  loop's decision, not this skill's.
+- **`mirador.html` is a generated artifact** — suggest adding it to the project's
+  `.gitignore`; it regenerates whenever you want.

package/uscha-kit/skills/uscha-mirador/mirador-render.py

@@ -94,10 +94,13 @@ def main():
                     help="path to mirador.template.html (default: the sibling template)")
     ap.add_argument("--out", default="mirador.html")
     ap.add_argument("--sidecar", default=os.path.join(".uscha", "telemetry.jsonl"))
-    ap.add_argument("--refresh", type=int, default=0,
-                    help="if >0, the page auto-reloads every N seconds (live second-screen view)")
+    ap.add_argument("--refresh", type=int, default=10,
+                    help="auto-reload the open tab every N seconds so a SINGLE tab stays live "
+                         "(0 = frozen snapshot; default 10)")
     ap.add_argument("--no-open", action="store_true",
                     help="write the file but do not open it in a browser")
+    ap.add_argument("--open", dest="force_open", action="store_true",
+                    help="open the browser even if the file already existed (the tab was closed)")
     args = ap.parse_args()
 
     try:
@@ -127,10 +130,12 @@ def main():
     out = re.sub(r"/\*MIRADOR_DATA_START\*/.*?/\*MIRADOR_DATA_END\*/",
                  lambda m: payload, tpl, count=1, flags=re.S)
     if args.refresh and args.refresh > 0:
-        # opt-in live reload: a meta-refresh, injected only when watching
+        # a meta-refresh so the ONE open tab reloads itself in place (on by default) --
+        # pass --refresh 0 for a frozen snapshot
         out = out.replace("</head>",
                           f'<meta http-equiv="refresh" content="{args.refresh}">\n</head>', 1)
-    live = bool(args.refresh and args.refresh > 0)
+    # capture BEFORE writing: auto-open fires only when the mirador is FIRST materialized
+    pre_existed = os.path.exists(args.out)
     with open(args.out, "w", encoding="utf-8") as f:
         f.write(out)
     score = (data.get("readiness") or {}).get("score")
@@ -139,10 +144,13 @@ def main():
     print(f"[mirador-render]   readiness {score} | telemetry {'on' if tel else 'off'} | "
           f"refresh {args.refresh or 'off'}")
     print(f"[mirador-render]   OPEN IT:  {out_abs}")
-    # Auto-open only a ONE-SHOT view. In live mode (--refresh) the page carries its own
-    # meta-refresh and reloads in the SAME tab, so opening on every render cycle would
-    # spawn a new browser tab each time (kit 1.41.3). Open it once by hand and let it live.
-    if not args.no_open and not live:
+    # Auto-open ONLY the first time the file is created. Repeated renders (the agent per
+    # pass, or a watch loop) rewrite the SAME file, and the meta-refresh reloads the already-
+    # open tab in place -- so a re-render never spawns a new browser tab (kit 1.51.2; 1.41.3
+    # gated this on --refresh, which spammed a tab per one-shot re-render). `pre_existed`
+    # tracks the FILE, not a live tab, so --open forces a reopen when the tab was closed;
+    # --no-open suppresses everywhere and wins over it. The OPEN IT path is always printed.
+    if not args.no_open and (args.force_open or not pre_existed):
         _open_best_effort(out_abs)
     return 0
 

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

@@ -18,6 +18,46 @@ disable-model-invocation: false
 opposite. The system already runs; its observable behavior is the ground truth. **You do
 not invent anything — you characterize what is already there, as facts.**
 
+## Orientation markers (non-negotiable)
+
+The operator must never have to ask "where am I?" or "what happens now?". Two markers, always.
+They are navigation, not ceremony: one line per turn, one block at the end.
+
+**Open every turn with a breadcrumb**, then the content:
+
+`[uscha · reverse-discovery · <step> → <target>]`
+
+- `<step>` — `Q<n>` for a question, `pass <n>` for a loop iteration, `step <n>` otherwise.
+  Count what has actually happened. **Never write a denominator** (`Q4/12`): this phase
+  converges, its length is not known in advance, and an invented total is exactly the kind of
+  narrated number the method forbids. **When the ledger already measures the count** (the QA
+  loop's `loop_count`), use the measured number — never keep a parallel tally of your own.
+- `<target>` — the artifact this turn feeds (`SPEC`, `ADR-003`, `ACCEPTANCE`, `LEDGER`,
+  `RECEIVED`, ...). Drop `→ <target>` only when the turn genuinely feeds none.
+
+**Close with the close block ONCE, when the skill finishes** — not on every turn. Ending
+without it is a defect, even when the phase converged cleanly:
+
+```
+[uscha · reverse-discovery · CLOSED]
+Produced: <files actually written, or "nothing">
+Blocks:   <what stands between here and the next phase, or "nothing">
+Next:     <the next action, and why it is that one>
+Run:      <the exact command or skill to invoke>
+```
+
+This is **not** the implementation handoff some skills also emit: that one is a prompt for
+whoever implements next, this one is navigation for the human operator, and both can appear.
+
+`Blocks` and `Next` are **derived from the state you just produced** — never copied from a
+fixed route, **including any `Flow:` line in this file**. Those lines are the nominal path;
+open ADR experiments, an unclosed spike, an unapproved golden or a red gate all change what
+genuinely comes next, and the derived answer wins. If the next phase cannot start yet, name it
+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.
+
 ## The one non-negotiable: produce ONLY facts
 
 A system map (from static analysis) and a golden suite (byte-captured) are FACTS —
@@ -94,6 +134,8 @@ Flow (migration): `uscha-reverse-discovery` (facts) → human writes SPEC + `/us
 module decisions) → `/uscha-devloop` (restructure; `golden-diff` + `ApplicationModules.verify()`
 stay green the whole way) → readiness + human gate.
 
+That route is the **nominal** one, not the answer: the `Next:`/`Run:` you emit in the close block are DERIVED from the state you actually produced, and override it whenever an open experiment, an unclosed spike, an unapproved golden or a red gate stands in between.
+
 ## Relationship to the other skills
 
 - **discovery** (greenfield): you PROPOSE the shape from an idea. **reverse-discovery**