@andresmassello/uscha 1.51.1 → 1.53.0

package/uscha-kit/install-uscha.py

@@ -20,7 +20,18 @@ PLUGIN_NAME = "uscha"
 SKILLS = ["uscha-discovery", "uscha-adr-refine", "uscha-reverse-discovery", "uscha-characterize",
           "uscha-devloop", "uscha-sysdoc", "uscha-rubric", "uscha-mirador",
           "uscha-status"]
-TARGETS = ("codex", "claude", "pi")
+# Agent-Skills targets: harness-neutral, SKILLS-ONLY installs. Each agent reads the 9 uscha-*
+# skill directories from its own root -- no plugin manifest, no settings.json, no hook. They all
+# share one transactional installer and one doctor branch, so a sixth costs a table row (kit
+# 1.53.0). Roots are the directories each agent documents for the Agent Skills standard.
+SKILL_ROOTS = {
+    "pi":      (".agents", "skills"),    # Earendil pi
+    "cursor":  (".cursor", "skills"),    # Cursor
+    "copilot": (".copilot", "skills"),   # VS Code / GitHub Copilot
+    "gemini":  (".gemini", "skills"),    # Gemini CLI
+    "cline":   (".cline", "skills"),     # Cline
+}
+TARGETS = ("codex", "claude") + tuple(SKILL_ROOTS)
 HOOK_NAME = "block-approved-writes.py"
 
 
@@ -41,8 +52,9 @@ def home_path(args):
 
 
 def selected_targets(value):
-    # `all` = every target (codex+claude+pi, kit 1.51.0); `both` stays a LEGACY alias for
-    # codex+claude so existing scripts/users keep their exact prior behavior when pi landed.
+    # `all` = every target in TARGETS, so a new Agent-Skills row is picked up automatically;
+    # `both` stays a LEGACY alias for codex+claude so existing scripts/users keep their exact
+    # prior behavior -- it deliberately does NOT grow as targets are added.
     return {"all": list(TARGETS), "both": ["codex", "claude"]}.get(value, [value])
 
 
@@ -115,7 +127,7 @@ def plugin_manifest():
     return {"name": PLUGIN_NAME, "version": source_version(),
             "description": "Uscha spec-driven development methodology for coding agents.",
             "author": {"name": "Andres Massello", "url": "https://github.com/andresmassello"},
-            "homepage": "https://github.com/andresmassello/uscha", "repository": "https://github.com/andresmassello/uscha",
+            "homepage": "https://uscha.dev", "repository": "https://github.com/andresmassello/uscha",
             "license": "MIT", "keywords": ["spec-driven", "qa", "gates", "golden-testing", "readiness"],
             "skills": "./skills/", "interface": {"displayName": "Uscha", "shortDescription": "Spec-driven development with fact gates and readiness.",
             "longDescription": "Uscha installs discovery, ADR, characterization, devloop, rubric, sysdoc and Mirador skills plus qa_ledger.py.",
@@ -434,15 +446,15 @@ def install_claude(home, mode, dry_run, operations):
                 pass
     return root
 
-def install_pi(home, mode, dry_run, operations):
-    # pi (Earendil) reads Agent Skills from ~/.agents/skills -- the harness-neutral sibling of
-    # the codex target's ~/.agents/plugins. Skills only: no settings.json and no hook here (the
-    # golden guard ships as a pi `tool_call` extension, see cmd doctor golden_guard). Same
-    # transactional shape as install_claude: stage -> back up -> atomic replace -> marker last.
+def install_skills_only(target, home, mode, dry_run, operations):
+    # One installer for every Agent-Skills target (SKILL_ROOTS): the 9 skills land flat under
+    # that agent's own root. Skills only -- no manifest, no settings.json, no hook. Same
+    # transactional shape as install_claude: stage -> back up -> atomic replace -> marker last,
+    # so a late failure rolls the target back with nothing lost.
     source = source_skills()
-    root = home / ".agents" / "skills"
+    root = home.joinpath(*SKILL_ROOTS[target])
     install_marker = root / "uscha-install.json"
-    marker_data = marker("pi", root, mode)
+    marker_data = marker(target, root, mode)
     operations.extend({"action": "install-skill", "path": str(root / skill)} for skill in SKILLS)
     operations.append({"action": "write-marker-last", "path": str(install_marker)})
     if dry_run:
@@ -450,7 +462,7 @@ def install_pi(home, mode, dry_run, operations):
 
     home_existed = home.exists()
     home.mkdir(parents=True, exist_ok=True)
-    transaction = home / (".uscha-pi-transaction-%s" % uuid.uuid4().hex)
+    transaction = home / (".uscha-%s-transaction-%s" % (target, uuid.uuid4().hex))
     staged = transaction / "staged"
     backups = transaction / "backups"
     cleanup_transaction = True
@@ -463,34 +475,38 @@ def install_pi(home, mode, dry_run, operations):
 
         entries = [(root / skill, staged / skill, backups / skill) for skill in SKILLS]
         entries.append((install_marker, staged / "uscha-install.json", backups / "uscha-install.json"))
-        preexisting = {target: target.exists() or target.is_symlink()
-                       for target, _, _ in entries}
+        # 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
+        # (the target NAME) to a Path, and the rollback error below would then report a file
+        # path instead of naming which target failed -- exactly when that matters most.
+        preexisting = {path: path.exists() or path.is_symlink()
+                       for path, _, _ in entries}
         created_dirs = []
         backed_up = set()
         installed = set()
         try:
-            for directory in (root.parent, root):   # ~/.agents then ~/.agents/skills
+            for directory in (root.parent, root):   # e.g. ~/.cursor then ~/.cursor/skills
                 if not directory.exists():
                     directory.mkdir(parents=True)
                     created_dirs.append(directory)
-            for target, replacement, backup in entries:
-                if preexisting[target]:
+            for path, replacement, backup in entries:
+                if preexisting[path]:
                     backup.parent.mkdir(parents=True, exist_ok=True)
-                    os.replace(target, backup)
-                    backed_up.add(target)
-                os.replace(replacement, target)
-                installed.add(target)
+                    os.replace(path, backup)
+                    backed_up.add(path)
+                os.replace(replacement, path)
+                installed.add(path)
         except Exception as exc:
             rollback_errors = []
-            for target, _, backup in reversed(entries):
+            for path, _, backup in reversed(entries):
                 try:
-                    if target in installed and (target.exists() or target.is_symlink()):
-                        remove_path(target)
-                    if target in backed_up and (backup.exists() or backup.is_symlink()):
-                        target.parent.mkdir(parents=True, exist_ok=True)
-                        os.replace(backup, target)
+                    if path in installed and (path.exists() or path.is_symlink()):
+                        remove_path(path)
+                    if path in backed_up and (backup.exists() or backup.is_symlink()):
+                        path.parent.mkdir(parents=True, exist_ok=True)
+                        os.replace(backup, path)
                 except Exception as rollback_exc:
-                    rollback_errors.append("%s: %s" % (target, rollback_exc))
+                    rollback_errors.append("%s: %s" % (path, rollback_exc))
             for directory in reversed(created_dirs):
                 try:
                     directory.rmdir()
@@ -499,8 +515,8 @@ def install_pi(home, mode, dry_run, operations):
             if rollback_errors:
                 cleanup_transaction = False
                 raise InstallError(
-                    "[install-uscha] pi rollback incomplete; recovery retained at %s (%s)"
-                    % (transaction, "; ".join(rollback_errors))
+                    "[install-uscha] %s rollback incomplete; recovery retained at %s (%s)"
+                    % (target, transaction, "; ".join(rollback_errors))
                 ) from exc
             raise
     finally:
@@ -542,11 +558,13 @@ def target_status(home, target):
             marketplace_ok = False
         checks = {"skills_present": skills_present, "manifest": manifest_ok, "marketplace_registered": marketplace_ok}
         guard = "advisory"   # Codex has no hooks mechanism (verified: .codex-plugin has no "hooks")
-    elif target == "pi":
-        # pi: skills live FLAT under ~/.agents/skills/<skill>/; no manifest, no hook. INV-GOLDEN-01
-        # ships as a pi `tool_call` extension (uscha-kit/pi/golden-guard.js) but is reported
-        # ADVISORY until a real pi run confirms the block -- the runtime is not measured here.
-        root = home / ".agents" / "skills"
+    elif target in SKILL_ROOTS:
+        # Agent-Skills targets: the skills live FLAT under that agent's root; no manifest, no
+        # hook. INV-GOLDEN-01 is therefore ADVISORY on all of them -- none exposes a blocking
+        # pre-tool hook the way Claude's PreToolUse does. pi is the one exception in waiting: a
+        # `tool_call` extension ships (uscha-kit/pi/golden-guard.js), but it stays advisory until
+        # a real pi run measures the block. The kit does not claim enforcement it has not seen.
+        root = home.joinpath(*SKILL_ROOTS[target])
         skills_root, marker_path = root, root / "uscha-install.json"
         skills_present = [skill for skill in SKILLS if (skills_root / skill / "SKILL.md").is_file()]
         checks = {"skills_present": skills_present}
@@ -579,9 +597,13 @@ def cmd_version(args):
 
 def cmd_install(args):
     home, operations, installed = home_path(args), [], {}
-    installers = {"codex": install_codex, "claude": install_claude, "pi": install_pi}
+    installers = {"codex": install_codex, "claude": install_claude}
     for target in selected_targets(args.target):
-        installed[target] = str(installers[target](home, args.mode, args.dry_run, operations))
+        if target in SKILL_ROOTS:
+            root = install_skills_only(target, home, args.mode, args.dry_run, operations)
+        else:
+            root = installers[target](home, args.mode, args.dry_run, operations)
+        installed[target] = str(root)
     emit({"status": "planned" if args.dry_run else "installed", "dry_run": args.dry_run, "source_version": source_version(), "home": str(home), "installed": installed, "operations": operations, "next": next_steps(args.target)}, args.json)
 
 
@@ -760,8 +782,11 @@ def cmd_mirador(args):
         raise SystemExit(1)
     base = [sys.executable, str(render), "--ledger", args.ledger, "--out", args.out]
     if not args.watch:
-        # one-shot: the renderer writes the file and opens it (unless --no-open)
-        rc = subprocess.call(base + (["--no-open"] if args.no_open else []))
+        # one-shot: the renderer writes the file and opens it only when FIRST materializing it
+        # -- a re-render updates the already-open tab in place instead of spawning another
+        # (kit 1.51.2). --no-open suppresses; --open forces a reopen when the tab was closed.
+        extra = ["--no-open"] if args.no_open else (["--open"] if args.force_open else [])
+        rc = subprocess.call(base + extra)
         if rc:
             raise SystemExit(rc)
         return
@@ -787,8 +812,15 @@ def next_steps(target):
     steps = []
     if "codex" in picked: steps.append("Codex: restart or open a new thread, then install/use uscha from the Personal marketplace if needed.")
     if "claude" in picked: steps.append("Claude: restart Claude Code so global skills/hooks are reloaded.")
-    if "pi" in picked: steps.append("pi: restart pi; the 9 uscha-* skills load from ~/.agents/skills. INV-GOLDEN-01 is advisory until the tool_call extension is installed (doctor reports golden_guard).")
-    return steps + ["Run: python install-uscha.py doctor --target %s" % target]
+    labels = {"pi": "pi (Earendil)", "cursor": "Cursor", "copilot": "VS Code / GitHub Copilot",
+              "gemini": "Gemini CLI", "cline": "Cline"}
+    for name in SKILL_ROOTS:
+        if name in picked:
+            steps.append("%s: restart it; the 9 uscha-* skills load from ~/%s. INV-GOLDEN-01 is "
+                         "advisory there (no blocking pre-tool hook) -- doctor reports golden_guard."
+                         % (labels.get(name, name), "/".join(SKILL_ROOTS[name])))
+    return steps + ["Run: python install-uscha.py doctor --target %s" % target,
+                    "Learn the method: https://uscha.dev"]
 
 
 def emit(data, as_json):
@@ -809,9 +841,9 @@ def build_parser():
     sub = parser.add_subparsers(dest="cmd", required=True)
     version = sub.add_parser("version", help="show source version and supported targets"); version.add_argument("--json", action="store_true"); version.set_defaults(func=cmd_version)
     install = sub.add_parser("install", help="install Uscha globally for a machine")
-    install.add_argument("--target", choices=["codex", "claude", "pi", "both", "all"], default="both"); install.add_argument("--mode", choices=["copy", "link"], default="copy"); install.add_argument("--home"); install.add_argument("--dry-run", action="store_true"); install.add_argument("--json", action="store_true"); install.set_defaults(func=cmd_install)
+    install.add_argument("--target", choices=list(TARGETS) + ["both", "all"], default="both"); install.add_argument("--mode", choices=["copy", "link"], default="copy"); install.add_argument("--home"); install.add_argument("--dry-run", action="store_true"); install.add_argument("--json", action="store_true"); install.set_defaults(func=cmd_install)
     doctor = sub.add_parser("doctor", help="check installed Uscha presence, registrations, and version drift")
-    doctor.add_argument("--target", choices=["codex", "claude", "pi", "both", "all"], default="both"); doctor.add_argument("--home"); doctor.add_argument("--json", action="store_true"); doctor.set_defaults(func=cmd_doctor)
+    doctor.add_argument("--target", choices=list(TARGETS) + ["both", "all"], default="both"); doctor.add_argument("--home"); doctor.add_argument("--json", action="store_true"); doctor.set_defaults(func=cmd_doctor)
     init = sub.add_parser("init", help="prepare a repo with Uscha config/templates")
     init.add_argument("--repo", default="."); init.add_argument("--force", action="store_true", help="replace differing init files deliberately"); init.add_argument("--dry-run", action="store_true"); init.add_argument("--json", action="store_true"); init.set_defaults(func=cmd_init)
     mirador = sub.add_parser("mirador", help="render + open the project's mirador dashboard from QA-LEDGER.json")
@@ -820,6 +852,8 @@ def build_parser():
     mirador.add_argument("--watch", action="store_true", help="live second-screen view: re-render every --interval seconds")
     mirador.add_argument("--interval", type=int, default=30)
     mirador.add_argument("--no-open", action="store_true", help="write the file but do not open a browser")
+    mirador.add_argument("--open", dest="force_open", action="store_true",
+                         help="open the browser even if mirador.html already existed (you closed the tab)")
     mirador.set_defaults(func=cmd_mirador)
     return parser
 

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

@@ -1,161 +1,203 @@
----
-name: uscha-adr-refine
-description: >
-  Turn a rough idea into a development-ready ADR set + ACCEPTANCE.md by INTERROGATING
-  before generating. Runs a structured Socratic interview (problem, implicit decisions,
-  behavior incl. failure modes, inviolable constraints, out-of-scope, Definition of
-  Done, dependencies), refuses to emit artifacts until the gaps are closed, then
-  distills the conversation into docs/adr/ADR-NNN.md files and an ACCEPTANCE.md. The
-  front-half counterpart to dev-loop. Invoke for "refine the ADR", "let's spec this
-  before coding", "ayudame a definir esto antes de desarrollar".
-allowed-tools: Read, Write, Glob, Grep
-disable-model-invocation: false
----
-
-# adr-refine — interview, then distill
-
-You convert a rough idea into a development-ready specification. You do this in two
-phases. **You are NOT a generator. You are an interrogator that distills.** The value
-is in the questions, not in agreeing.
-
-## Non-negotiable principles
-
-1. **Interrogate, don't agree.** Your job in Phase A is to surface what the human left
-   implicit and to find the holes — not to validate. A refinement where you agreed with
-   everything failed.
-2. **Converge, don't run out of questions.** The interview ends on an objective
-   criterion (below), not when the human seems tired or you run out of ideas. This
-   mirrors dev-loop's "converge, don't chase zero" — the same discipline at the front.
-3. **Do not emit artifacts until convergence.** No ADR, no ACCEPTANCE.md until every
-   exit condition is met. If asked to "just write it" early, name the open gaps first.
-4. **One topic at a time.** Never dump 20 questions. Walk the agenda below, a focused
-   batch at a time, and reflect back what you heard before moving on.
-5. **Record deferrals as explicit assumptions.** If the human says "you decide" on a
-   consequential decision, push back once with the trade-off; if they still defer,
-   record it as an explicit assumption in the ADR, never as a silent default.
-
-## Phase A — The interview (agenda)
-
-Start from the human's initial context. Work the agenda in order; skip a topic only if
-it's already fully answered. Keep a running list of OPEN GAPS and resolved decisions.
-
-1. **Problem and why now.** What job does this remove? What does it cost to NOT do
-   it (money, time, risk)? If "why now" has no answer, the priority is suspect.
-2. **Implicit decisions.** Surface the choices the request assumed: sync vs async,
-   storage, protocol, idempotency, transactional boundaries, who owns state. For each,
-   force an explicit decision and at least one considered alternative.
-3. **Behavior.** Happy path first, then the DIRTY cases: provider/timeout failures,
-   retries and backoff, 4xx vs 5xx, concurrency, partial/terminal states, what must NOT
-   happen. A feature without its failure behavior is half-specified.
-4. **Inviolable constraints (→ `CONSTITUTION.md`).** Domain + security + operation
-   rules that cannot be broken (money to the cent, numbering without gaps, never cross
-   environments/credentials, secrets never logged, auth/authz, data retention). Write/extend
-   `CONSTITUTION.md` (one invariant per line, CWE ref where it maps); these feed the
-   dev-loop severity gate and a breach is a BLOCKER. **An ADR may never contradict the
-   CONSTITUTION** — if a decision would, it's escalated, not recorded.
-5. **Out of scope.** Explicit boundaries, with forward references ("X goes to a later
-   spec"). What you exclude is as important as what you include.
-6. **Definition of Done + how we measure success.** Concrete, checkable acceptance criteria
-   (tests green, documented, metrics published, runbook) AND success metrics (p95,
-   cost ceiling, zero orphaned records). Each item must be verifiable, not a feeling.
-7. **Dependencies.** Which other specs/systems/credentials this needs to exist first.
-
-After each batch, reflect: "Decided: … / Still open: …". Move on only when the
-current topic is closed.
-
-## Convergence — exit conditions (ALL must hold)
-
-- Every decision has a rationale and at least one considered alternative.
-- Every failure mode named has a defined behavior.
-- Out-of-scope is explicit.
-- The Definition of Done exists and every item is checkable.
-- No OPEN GAP you raised remains unresolved (resolved = decided OR recorded as an
-  explicit assumption).
-
-State plainly when you've converged ("Closed: every decision has a rationale, the failures
-have behavior, the scope has a boundary and the DoD is verifiable.") before Phase B.
-
-## Phase B — Distill the artifacts
-
-Only after convergence. Produce (and, if any new project-wide invariant surfaced in
-step 4, append it to **`CONSTITUTION.md`** — never let an inviolable rule slip into an
-ADR where it could later be "traded away"):
-
-1. **One ADR per decision worth recording** at `docs/adr/ADR-NNN-<slug>.md`, format:
-
-```markdown
-# ADR-NNN: <title of the decision>
-## Status: Accepted
-<!-- Use Status: Experiment only for a bounded hypothesis with feedback/review criteria. -->
-## Context
-<the problem + the considered options: A) … B) … C) …>
-## Decision
-<the chosen option>
-## Reasons
-- <why, point by point>
-## Consequences
-+ <the good>
-- <the cost / what it forces on us>
-<!-- If Status: Experiment, also include:
-## Hypothesis
-## Feedback Signal
-## Review By: YYYY-MM-DD  (or ## Review Trigger)
-## Promote Criteria
-## Rollback / Supersede Criteria
--->
-## Implementation Plan
-- Affected paths: <files/dirs>
-- Patterns: <pattern to follow>
-- Tests: <which tests prove the decision>
-## Verification
-- [ ] <criterion checkable by an agent>
-```
-
-   Number ADRs continuing from the highest existing one in `docs/adr/` (glob first).
-   Negative decisions count: "what we are NOT going to use and why" is a valid ADR.
-   Experimental decisions count only when they are explicit hypotheses with feedback signal,
-   review date/trigger, promote criteria and rollback/supersede criteria. Do not use
-   `Status: Experiment` as a polite way to avoid deciding.
-
-2. **`ACCEPTANCE.md`** at the repo root (or the path in `uscha.config.json` →
-   `defaults.acceptance_file`). This is the file dev-loop's readiness measures — it MUST
-   exist and be checkable:
-
-```markdown
-# Acceptance — <feature>
-## Definition of Done
-- [ ] AC-01 — <verifiable criterion>
-- [ ] AC-02 — <verifiable criterion>
-## How we measure success
-- <objective metric: p95, cost, zero orphans, …>
-## Out of scope
-- <boundary> → <future spec>
-## Recorded decisions
-- ADR-NNN — <title>
-```
-
-**Where to write:** with file tools available (Claude Code), write the files to disk.
-In a chat-only context, print each file in a fenced block, clearly labeled with its
-target path, ready to paste — and remind the human these go to `docs/adr/` and the repo
-root before running dev-loop.
-
-**Tracked-markdown protocol:** if any target `.md` already exists and is tracked, ask
-for its current version before overwriting — never silently replace.
-
-## Handoff to dev-loop
-
-Close with the handoff prompt so the build phase starts by planning, not improvising:
-
-> "Read the ADR set and ACCEPTANCE.md. Before touching code: 1) summarize the plan of
-> files to create/modify, 2) confirm which decisions were left implicit, 3)
-> show me the first test you would write."
-
-Two-command flow end to end: `/uscha-adr-refine` → (ADR set + ACCEPTANCE.md) → `/uscha-devloop`.
-
-## Anti-patterns (do not do)
-
-- Generate an ADR from a one-line request without interviewing.
-- Accept "do it however you want" on a consequential decision without recording the
-  assumption.
-- Write an ACCEPTANCE item that isn't objectively checkable ("that it works well").
-- Emit artifacts before the convergence conditions are met.
+---
+name: uscha-adr-refine
+description: >
+  Turn a rough idea into a development-ready ADR set + ACCEPTANCE.md by INTERROGATING
+  before generating. Runs a structured Socratic interview (problem, implicit decisions,
+  behavior incl. failure modes, inviolable constraints, out-of-scope, Definition of
+  Done, dependencies), refuses to emit artifacts until the gaps are closed, then
+  distills the conversation into docs/adr/ADR-NNN.md files and an ACCEPTANCE.md. The
+  front-half counterpart to dev-loop. Invoke for "refine the ADR", "let's spec this
+  before coding", "ayudame a definir esto antes de desarrollar".
+allowed-tools: Read, Write, Glob, Grep
+disable-model-invocation: false
+---
+
+# adr-refine — interview, then distill
+
+You convert a rough idea into a development-ready specification. You do this in two
+phases. **You are NOT a generator. You are an interrogator that distills.** The value
+is in the questions, not in agreeing.
+
+## 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 · adr-refine · <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 · adr-refine · 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.
+
+## Non-negotiable principles
+
+1. **Interrogate, don't agree.** Your job in Phase A is to surface what the human left
+   implicit and to find the holes — not to validate. A refinement where you agreed with
+   everything failed.
+2. **Converge, don't run out of questions.** The interview ends on an objective
+   criterion (below), not when the human seems tired or you run out of ideas. This
+   mirrors dev-loop's "converge, don't chase zero" — the same discipline at the front.
+3. **Do not emit artifacts until convergence.** No ADR, no ACCEPTANCE.md until every
+   exit condition is met. If asked to "just write it" early, name the open gaps first.
+4. **One topic at a time.** Never dump 20 questions. Walk the agenda below, a focused
+   batch at a time, and reflect back what you heard before moving on.
+5. **Record deferrals as explicit assumptions.** If the human says "you decide" on a
+   consequential decision, push back once with the trade-off; if they still defer,
+   record it as an explicit assumption in the ADR, never as a silent default.
+
+## Phase A — The interview (agenda)
+
+Start from the human's initial context. Work the agenda in order; skip a topic only if
+it's already fully answered. Keep a running list of OPEN GAPS and resolved decisions.
+
+1. **Problem and why now.** What job does this remove? What does it cost to NOT do
+   it (money, time, risk)? If "why now" has no answer, the priority is suspect.
+2. **Implicit decisions.** Surface the choices the request assumed: sync vs async,
+   storage, protocol, idempotency, transactional boundaries, who owns state. For each,
+   force an explicit decision and at least one considered alternative.
+3. **Behavior.** Happy path first, then the DIRTY cases: provider/timeout failures,
+   retries and backoff, 4xx vs 5xx, concurrency, partial/terminal states, what must NOT
+   happen. A feature without its failure behavior is half-specified.
+4. **Inviolable constraints (→ `CONSTITUTION.md`).** Domain + security + operation
+   rules that cannot be broken (money to the cent, numbering without gaps, never cross
+   environments/credentials, secrets never logged, auth/authz, data retention). Write/extend
+   `CONSTITUTION.md` (one invariant per line, CWE ref where it maps); these feed the
+   dev-loop severity gate and a breach is a BLOCKER. **An ADR may never contradict the
+   CONSTITUTION** — if a decision would, it's escalated, not recorded.
+5. **Out of scope.** Explicit boundaries, with forward references ("X goes to a later
+   spec"). What you exclude is as important as what you include.
+6. **Definition of Done + how we measure success.** Concrete, checkable acceptance criteria
+   (tests green, documented, metrics published, runbook) AND success metrics (p95,
+   cost ceiling, zero orphaned records). Each item must be verifiable, not a feeling.
+7. **Dependencies.** Which other specs/systems/credentials this needs to exist first.
+
+After each batch, reflect: "Decided: … / Still open: …". Move on only when the
+current topic is closed.
+
+## Convergence — exit conditions (ALL must hold)
+
+- Every decision has a rationale and at least one considered alternative.
+- Every failure mode named has a defined behavior.
+- Out-of-scope is explicit.
+- The Definition of Done exists and every item is checkable.
+- No OPEN GAP you raised remains unresolved (resolved = decided OR recorded as an
+  explicit assumption).
+
+State plainly when you've converged ("Closed: every decision has a rationale, the failures
+have behavior, the scope has a boundary and the DoD is verifiable.") before Phase B.
+
+## Phase B — Distill the artifacts
+
+Only after convergence. Produce (and, if any new project-wide invariant surfaced in
+step 4, append it to **`CONSTITUTION.md`** — never let an inviolable rule slip into an
+ADR where it could later be "traded away"):
+
+1. **One ADR per decision worth recording** at `docs/adr/ADR-NNN-<slug>.md`, format:
+
+```markdown
+# ADR-NNN: <title of the decision>
+## Status: Accepted
+<!-- Use Status: Experiment only for a bounded hypothesis with feedback/review criteria. -->
+## Context
+<the problem + the considered options: A) … B) … C) …>
+## Decision
+<the chosen option>
+## Reasons
+- <why, point by point>
+## Consequences
++ <the good>
+- <the cost / what it forces on us>
+<!-- If Status: Experiment, also include:
+## Hypothesis
+## Feedback Signal
+## Review By: YYYY-MM-DD  (or ## Review Trigger)
+## Promote Criteria
+## Rollback / Supersede Criteria
+-->
+## Implementation Plan
+- Affected paths: <files/dirs>
+- Patterns: <pattern to follow>
+- Tests: <which tests prove the decision>
+## Verification
+- [ ] <criterion checkable by an agent>
+```
+
+   Number ADRs continuing from the highest existing one in `docs/adr/` (glob first).
+   Negative decisions count: "what we are NOT going to use and why" is a valid ADR.
+   Experimental decisions count only when they are explicit hypotheses with feedback signal,
+   review date/trigger, promote criteria and rollback/supersede criteria. Do not use
+   `Status: Experiment` as a polite way to avoid deciding.
+
+2. **`ACCEPTANCE.md`** at the repo root (or the path in `uscha.config.json` →
+   `defaults.acceptance_file`). This is the file dev-loop's readiness measures — it MUST
+   exist and be checkable:
+
+```markdown
+# Acceptance — <feature>
+## Definition of Done
+- [ ] AC-01 — <verifiable criterion>
+- [ ] AC-02 — <verifiable criterion>
+## How we measure success
+- <objective metric: p95, cost, zero orphans, …>
+## Out of scope
+- <boundary> → <future spec>
+## Recorded decisions
+- ADR-NNN — <title>
+```
+
+**Where to write:** with file tools available (Claude Code), write the files to disk.
+In a chat-only context, print each file in a fenced block, clearly labeled with its
+target path, ready to paste — and remind the human these go to `docs/adr/` and the repo
+root before running dev-loop.
+
+**Tracked-markdown protocol:** if any target `.md` already exists and is tracked, ask
+for its current version before overwriting — never silently replace.
+
+## Handoff to dev-loop
+
+Close with the handoff prompt so the build phase starts by planning, not improvising:
+
+> "Read the ADR set and ACCEPTANCE.md. Before touching code: 1) summarize the plan of
+> files to create/modify, 2) confirm which decisions were left implicit, 3)
+> show me the first test you would write."
+
+Two-command flow end to end: `/uscha-adr-refine` → (ADR set + ACCEPTANCE.md) → `/uscha-devloop`.
+
+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.
+
+## Anti-patterns (do not do)
+
+- Generate an ADR from a one-line request without interviewing.
+- Accept "do it however you want" on a consequential decision without recording the
+  assumption.
+- Write an ACCEPTANCE item that isn't objectively checkable ("that it works well").
+- Emit artifacts before the convergence conditions are met.