@andresmassello/uscha 1.93.1 → 1.94.1

package/README.md

@@ -40,7 +40,7 @@ Requires **Python 3.8+** on the machine (the engine is Python stdlib — no pip
 runtime dependencies). The npm package is a thin router; the canonical installer is
 `uscha-kit/install-uscha.py`.
 
-**Kit v1.93.1** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.94.1** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
 [changelog](https://github.com/andresmassello/uscha/blob/main/uscha-kit/CHANGELOG.md)
 (the per-release changelogs live in the repo, not in the npm tarball)
 
@@ -85,7 +85,7 @@ automatic tool can perform: a human verdict.
    from the compiled code: 0.828 measured (12 archetypes) — names AND behaviour
 ```
 
-**What each arrow is, in the engine (kit 1.93.1, 53 subcommands, all measured):**
+**What each arrow is, in the engine (kit 1.94.1, 53 subcommands, all measured):**
 
 | Leg | Subcommands | What it establishes |
 |---|---|---|

package/package.json

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

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

@@ -112,21 +112,45 @@ it's already fully answered. Keep a running list of OPEN GAPS and resolved decis
 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,
+3. **Stack and lifecycle (MANDATORY — before any stack/architecture decision is
+   recorded).** The stack is not a given ("we use X"): it is a decision with an EXPIRY
+   DATE. A major version is a family; support is granted to a MINOR line, for a window,
+   by an upstream nobody in the room controls. Ask these one at a time, each with your
+   recommended answer, and **FETCH the dates from the official source AS YOU ASK — never
+   answer from memory**; record the URL and the day you checked:
+   (a) the EXACT version of every runtime/framework/store (JDK, web framework, ORM, DB,
+   Node, bundler, broker, cache) and its OSS/LTS end-of-support date, cited;
+   (b) support window vs the declared go-live AND the expected operating life — does the
+   line stay patched for the whole operation? If not, move it up BEFORE building: a major
+   upgrade days before the milestone is the most expensive one there is;
+   (c) major dependencies and the upgrade policy — who approves one, and when it is
+   scheduled (aligned with the dev-loop's "zero new dependencies without approval");
+   (d) development and observability tools the operator wants from day one (consoles, APM,
+   admin UIs) — they CONSTRAIN versions, so ask early or they force the upgrade;
+   (e) compatibility with reused legacy modules — the minimum version they support.
+   The answers distil into the stack ADR with the dates INSIDE it, as the machine-readable
+   `lifecycle:` frontmatter block (`component` / `version` / `eol` / `source` / `checked`,
+   ISO dates; `eol: unknown` is allowed and reads as a NAMED absence, never a pass) — see
+   `templates/docs/adr/ADR-stack-template.md`. The SPEC declares the milestone it is
+   compared against: frontmatter `go_live: YYYY-MM-DD` or a `**Go-live:** YYYY-MM-DD` line.
+   `qa_ledger.py spec-check` then reports, per component, `ok` / `expires before go-live` /
+   `no EOL cited` / `no source cited` — ADVISORY, it never gates. It can see that a date
+   was CITED; it cannot see whether the citation is TRUE. That part is yours.
+4. **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
+5. **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
+6. **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
+7. **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.
+8. **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.
@@ -146,7 +170,7 @@ have behavior, the scope has a boundary and the DoD is verifiable.") before Phas
 ## 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
+step 5, 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:

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

@@ -206,17 +206,51 @@ def _repo_cfg(ledger, name):
 # measurement: coverage
 # --------------------------------------------------------------------------- #
 def _jacoco_line_counter(xml_path):
-    """Return (missed, covered) for the report-level LINE counter."""
+    """Return (missed, covered) for the report-level LINE counter, or None when the report
+    could not be READ. The distinction is the whole point: a report that measured nothing
+    must never be summed as (0, 0) — that is an invented number, and with one module's XML
+    truncated mid-write it made the surviving modules' percentage look like the project's
+    (audit 1.94.1). Absence is never invented as a number — the rule `cobertura_coverage`
+    already states, applied to the JaCoCo readers too. A report with no LINE counter at all
+    is a real, readable zero and stays (0, 0)."""
     try:
         root = _parse_xml(xml_path).getroot()
-    except ET.ParseError:
-        return 0, 0
+    except (ET.ParseError, OSError, ReportTooLarge):
+        return None
     for c in root.findall("counter"):
         if c.get("type") == "LINE":
-            return int(c.get("missed", 0)), int(c.get("covered", 0))
+            try:
+                return int(c.get("missed", 0)), int(c.get("covered", 0))
+            except (TypeError, ValueError):
+                return None          # a counter that is not a number measured nothing
     return 0, 0
 
 
+def _jacoco_result(files):
+    """Sum the LINE counters of `files`, or report the WHOLE reading unmeasured. Shared by
+    maven/gradle/ant: three hand-copied versions of this sum is how one of them would drift.
+
+    ONE unreadable report makes the reading unmeasured, and an unmeasured reading is
+    (0, 0, 0.0) -- not the survivors' percentage with a false flag beside it. Every other
+    reader in this file returns pct 0.0 whenever report_found is False, and readers of the
+    result rely on it: `readiness` scores coverage as pct/threshold WITHOUT consulting
+    report_found, and `snapshot` prints and persists the pct next to the flag. Handing them
+    the surviving modules' number would score a project on a question nobody asked
+    (audit 1.94.1). The report paths are still listed -- the operator needs to know which
+    files were looked at."""
+    parsed = [_jacoco_line_counter(f) for f in files]
+    reports = [f.replace("\\", "/") for f in files]
+    if not files or any(p is None for p in parsed):
+        return {"covered": 0, "missed": 0, "pct": 0.0, "report_found": False,
+                "reports": reports}
+    missed = sum(p[0] for p in parsed)
+    covered = sum(p[1] for p in parsed)
+    total = missed + covered
+    pct = round(covered / total * 100, 2) if total else 0.0
+    return {"covered": covered, "missed": missed, "pct": pct,
+            "report_found": True, "reports": reports}
+
+
 def maven_coverage(repo_path):
     """
     Prefer an aggregate report if present, else sum per-module reports.
@@ -231,16 +265,7 @@ def maven_coverage(repo_path):
         files = glob.glob(os.path.join(repo_path, "**", "target", "site",
                                        "jacoco", "jacoco.xml"),
                           recursive=True)
-    missed = covered = 0
-    for f in files:
-        m, c = _jacoco_line_counter(f)
-        missed += m
-        covered += c
-    total = missed + covered
-    pct = round(covered / total * 100, 2) if total else 0.0
-    return {"covered": covered, "missed": missed, "pct": pct,
-            "report_found": bool(files),
-            "reports": [f.replace("\\", "/") for f in files]}
+    return _jacoco_result(files)
 
 
 def flutter_coverage(repo_path):
@@ -343,16 +368,7 @@ def gradle_coverage(repo_path):
     if not files:
         files = glob.glob(os.path.join(repo_path, "**", "build", "reports",
                                        "jacoco", "jacoco.xml"), recursive=True)
-    missed = covered = 0
-    for f in files:
-        m, c = _jacoco_line_counter(f)
-        missed += m
-        covered += c
-    total = missed + covered
-    pct = round(covered / total * 100, 2) if total else 0.0
-    return {"covered": covered, "missed": missed, "pct": pct,
-            "report_found": bool(files),
-            "reports": [f.replace("\\", "/") for f in files]}
+    return _jacoco_result(files)
 
 
 def ant_coverage(repo_path):
@@ -360,16 +376,7 @@ def ant_coverage(repo_path):
     report task writes wherever the build file says -- so the report is discovered
     RECURSIVELY by name instead of guessing one convention."""
     files = _ant_reports(repo_path, "jacoco.xml")
-    missed = covered = 0
-    for f in files:
-        m, c = _jacoco_line_counter(f)
-        missed += m
-        covered += c
-    total = missed + covered
-    pct = round(covered / total * 100, 2) if total else 0.0
-    return {"covered": covered, "missed": missed, "pct": pct,
-            "report_found": bool(files),
-            "reports": [f.replace("\\", "/") for f in files]}
+    return _jacoco_result(files)
 
 
 def coverage(repo_path, repo_type):
@@ -1276,7 +1283,15 @@ def _mk_id(tool, rule, fname, line, granularity):
 
 def _find_all(base, patterns, explicit):
     if explicit:
-        return [explicit] if os.path.exists(explicit) else []
+        if not os.path.exists(explicit):
+            # An EXPLICIT path is a claim the operator made about where the report is. When
+            # it is not there, the honest reading is a typo or a build that never wrote it --
+            # not "this linter has no findings". Returning [] made ingest-gate log nothing
+            # and exit 0, so a mistyped --ruff read as a clean gate (audit 1.94.1). Same
+            # fail-closed exit an unparseable report already gets, with the path named.
+            _invalid_static_report(explicit, "linter",
+                                   "no such file (explicit path given, nothing to ingest)")
+        return [explicit]
     found = []
     for pat in patterns:
         found += glob.glob(os.path.join(base, pat), recursive=True)
@@ -3107,7 +3122,7 @@ def cmd_fastpath_eval(args):
         sig("configured", False, "defaults.fast_path present and enabled",
             "config.defaults.fast_path", False)
     else:
-        repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+        repo_path = _scope_path(ledger, args.repo)
         base, base_src = args.base, "--base"
         if base:
             probe = subprocess.run(["git", "rev-parse", "--verify", base + "^{commit}"],
@@ -3694,7 +3709,7 @@ def cmd_cleanroom(args):
     import time
     ledger = _load(args.ledger)
     _repo_node(ledger, args.repo)
-    repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+    repo_path = _scope_path(ledger, args.repo)
 
     def git(*a, **kw):
         cwd = kw.pop("cwd", repo_path)
@@ -8406,6 +8421,10 @@ def cmd_dashboard(args):
                             for r in {e.get("repo") for e in ledger["fast_path"]}}
     if ledger.get("spec_drift"):
         out["spec_drift"] = ledger["spec_drift"]
+    # lifecycle (ADR-040): reused VERBATIM from the readiness payload above (one read, no
+    # drift possible between the two surfaces), conditional for the same reason spec_drift is.
+    if rd.get("lifecycle"):
+        out["lifecycle"] = rd["lifecycle"]
     # evidence_origin: the latest snapshot's origin per repo, and ONLY when one exists --
     # a ledger predating ADR-007 keeps the exact prior schema (same conditional-key rule
     # fast_path and spec_drift already follow).
@@ -9554,6 +9573,12 @@ def cmd_readiness(args):
         "gates": _gate_rollup(ledger),
         "by_repo": repos,
     }
+    # lifecycle (ADR-040): advisory, and CONDITIONAL like fast_path/spec_drift -- a project
+    # that declares no lifecycle: block keeps the exact prior payload and the exact prior
+    # text. Speaking only when it matters is the anti-ceremony rule applied to itself.
+    _lc = _lifecycle_for(os.path.dirname(os.path.abspath(args.ledger)) or os.getcwd())
+    if _lc["declared"]:
+        out["lifecycle"] = _lc
     if args.json:
         print(json.dumps(out, indent=2, ensure_ascii=False))
         return
@@ -9634,6 +9659,8 @@ def cmd_readiness(args):
               f"rising for {STALL_WINDOW} cycles: iterating more is not getting "
               f"closer. Likely a design/SPEC problem — go back to the ADR / "
               f"re-plan with the human (advisory)")
+    if _lc["declared"]:
+        print("  · " + _lifecycle_summary(_lc))
     # rubrica (1.23.0): el ultimo grade por repo, siempre visible — guess
     # estructurado que aconseja; si esta gateado ya bloqueo por el ledger
     for rname, rnode in ledger["repos"].items():
@@ -10986,6 +11013,225 @@ _SC_SETEXT = re.compile(r"^(=+|-{2,})\s*$")
 _SC_CHECKBOX = re.compile(r"^\[[ xX]\]\s*")
 
 
+# --------------------------------------------------------------------------- #
+# lifecycle  (ADR-040: stack end-of-support vs go-live -- advisory, NEVER gates)
+# --------------------------------------------------------------------------- #
+# The method interrogates WHAT and WHY and has always treated the stack as a given
+# ("we use X"). A major line is not a decision: a minor line has an END-OF-SUPPORT
+# DATE, and a date that falls before the declared go-live is a forced upgrade nobody
+# planned. This dimension reads what the ADR CITES and compares it against the SPEC's
+# declared go-live. It cannot verify that the cited source tells the truth -- only that
+# a date and a source were cited at all. Advisory by construction, like spec-drift
+# (ADR-005): it never gates, never caps readiness, and never changes an exit code.
+_LC_DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+def _lc_valid_date(s):
+    """A cited date is real only if it is BOTH shaped YYYY-MM-DD and a calendar date:
+    the format regex alone accepts 2025-13-40 (1.94.0 review), which then string-compares
+    as if it were a real EOL. fromisoformat rejects the impossible month/day."""
+    if not s or not _LC_DATE.match(s):
+        return False
+    try:
+        datetime.strptime(s, "%Y-%m-%d")
+        return True
+    except ValueError:
+        return False
+_LC_KEY = re.compile(r"^lifecycle\s*:\s*(.*)$")
+_LC_GOLIVE_FM = re.compile(r"^go[-_ ]?live\s*:\s*(.+?)\s*$", re.I)
+_LC_GOLIVE_LINE = re.compile(r"^\s*\*\*\s*go[-_ ]?live\s*:?\s*\*\*\s*:?\s*"
+                             r"(\d{4}-\d{2}-\d{2})\b", re.I)
+_LC_FIELDS = ("component", "version", "eol", "source", "checked")
+
+
+def _lc_frontmatter(lines):
+    """The lines INSIDE a leading `---` frontmatter block, or None when there is none.
+    An unterminated fence is not data: a half-written block reads as absent."""
+    if not lines or lines[0].strip() != "---":
+        return None
+    body = []
+    for ln in lines[1:]:
+        if ln.strip() == "---":
+            return body
+        body.append(ln)
+    return None
+
+
+def _lc_parse(lines):
+    """The `lifecycle:` list-of-dicts of a markdown file, parsed as a YAML SUBSET --
+    stdlib only, the kit ships no PyYAML. Returns None when the key is absent (nothing to
+    measure) and [] when the key is there but nothing under it parses (a NAMED absence:
+    the caller reports UNMEASURED with a reason, never a silent pass)."""
+    fm = _lc_frontmatter(lines)
+    if fm is None:
+        return None
+    entries, in_lc, cur = None, False, None
+    for ln in fm:
+        s = ln.strip()
+        if not in_lc:
+            m = _LC_KEY.match(ln)
+            if m:
+                entries = []
+                # only the block form is supported; an inline `lifecycle: [...]` parses to
+                # nothing and reads as unparseable, never as "this ADR fixes no component"
+                in_lc = not m.group(1).strip()
+            continue
+        if not s or s.startswith("#"):
+            continue
+        if not ln[:1].isspace():          # back to column 0 -> the key ended
+            in_lc = False
+            continue
+        if s.startswith("- "):
+            cur = {}
+            entries.append(cur)
+            s = s[2:].strip()
+            if not s:
+                continue
+        if cur is None:
+            continue
+        k, sep, v = s.partition(":")
+        if not sep:
+            continue
+        k = k.strip().lower()
+        if k in _LC_FIELDS:
+            cur[k] = v.strip().strip("\x27\x22")
+    if entries is not None:
+        entries = [e for e in entries if e]
+    return entries
+
+
+def _lc_go_live(text):
+    """The declared go-live of a SPEC: frontmatter `go_live: YYYY-MM-DD`, or a
+    `**Go-live:** YYYY-MM-DD` line anywhere in the body. None = not declared."""
+    lines = [ln.rstrip("\r") for ln in (text or "").split("\n")]
+    fm = _lc_frontmatter(lines)
+    if fm:
+        for ln in fm:
+            if ln[:1].isspace():
+                continue
+            m = _LC_GOLIVE_FM.match(ln.strip())
+            if m:
+                v = m.group(1).strip().strip("\x27\x22")
+                if _lc_valid_date(v):
+                    return v
+    for ln in lines:
+        m = _LC_GOLIVE_LINE.match(ln)
+        if m and _lc_valid_date(m.group(1)):
+            return m.group(1)
+    return None
+
+
+def _lc_short(path):
+    """The ADR dir as the reader would type it: relative to the cwd when that is shorter,
+    absolute otherwise (a different drive on Windows has no relative form)."""
+    if not path:
+        return "docs/adr"
+    try:
+        rel = os.path.relpath(path)
+    except ValueError:
+        return path
+    return rel if len(rel) < len(path) else path
+
+
+def _lifecycle_report(adr_dir, spec_text):
+    """Per-component verdicts for every `lifecycle:` entry under `adr_dir`, compared
+    against the go-live declared in `spec_text`. Whole-dimension UNMEASURED -- with the
+    reason spelled out, never silence -- when no ADR carries the block, when the block is
+    unparseable, or when no go-live is declared."""
+    go_live = _lc_go_live(spec_text)
+    comps, unparsed, names = [], [], []
+    if adr_dir and os.path.isdir(adr_dir):
+        names = sorted(f for f in os.listdir(adr_dir) if f.lower().endswith(".md"))
+    for fn in names:
+        try:
+            with open(os.path.join(adr_dir, fn), "r", encoding="utf-8",
+                      errors="replace") as fh:
+                lines = [ln.rstrip("\r") for ln in fh.read().split("\n")]
+        except OSError:
+            continue
+        ent = _lc_parse(lines)
+        if ent is None:
+            continue
+        if not ent:
+            unparsed.append(fn)
+            continue
+        for e in ent:
+            comps.append({"adr": fn, "component": e.get("component") or "(unnamed)",
+                          "version": e.get("version"), "eol": e.get("eol"),
+                          "source": e.get("source"), "checked": e.get("checked")})
+    out = {"status": "UNMEASURED", "reason": None, "go_live": go_live,
+           "adr_dir": adr_dir, "declared": bool(comps or unparsed),
+           "components": comps, "n_components": len(comps), "n_expiring": 0,
+           "unparsed_adrs": unparsed}
+    if not comps:
+        out["reason"] = ("lifecycle: block declared but unparseable in: "
+                         + ", ".join(unparsed) if unparsed else
+                         "no ADR under %s carries a lifecycle: block"
+                         % _lc_short(adr_dir))
+        return out
+    if not go_live:
+        for c in comps:
+            c["status"], c["detail"] = "unmeasured", "no go-live declared"
+        out["reason"] = ("no go-live declared in the SPEC (frontmatter 'go_live: "
+                         "YYYY-MM-DD' or a '**Go-live:** YYYY-MM-DD' line)")
+        return out
+    for c in comps:
+        eol = (c.get("eol") or "").strip()
+        cited = (c.get("source") or "").strip()
+        if not eol or eol.lower() == "unknown" or not _lc_valid_date(eol):
+            c["status"] = "no EOL cited"
+            c["detail"] = ("declared unknown" if eol.lower() == "unknown"
+                           else ("not a YYYY-MM-DD date: %s" % eol if eol else "absent"))
+        elif eol < go_live:
+            # the sharper fact wins the label: a date that already expires is reported as
+            # expiring even when uncited, and the missing source stays visible in the record
+            c["status"] = "expires before go-live"
+            c["detail"] = "%s < %s" % (eol, go_live)
+            out["n_expiring"] += 1
+        elif not cited:
+            c["status"] = "no source cited"
+            c["detail"] = "eol %s is asserted, not cited" % eol
+        else:
+            c["status"] = "ok"
+            c["detail"] = "eol %s >= go-live %s" % (eol, go_live)
+    out["status"] = "measured"
+    return out
+
+
+def _lifecycle_summary(lc):
+    """The one advisory line, shared by spec-check and readiness so the two surfaces
+    cannot drift apart."""
+    if lc["status"] != "measured":
+        return "lifecycle: UNMEASURED - %s" % lc["reason"]
+    return ("lifecycle: %d component(s), %d expire before go-live %s (advisory)"
+            % (lc["n_components"], lc["n_expiring"], lc["go_live"]))
+
+
+def _lifecycle_root(*paths):
+    """The project root a lifecycle read hangs off: the directory of the first path
+    given, else the cwd."""
+    for p in paths:
+        if p:
+            return os.path.dirname(os.path.abspath(p)) or os.getcwd()
+    return os.getcwd()
+
+
+def _lifecycle_for(root, adr_dir=None, spec_text=None, fallback=True):
+    """Read the dimension for a project root: `docs/adr` unless overridden, and the
+    go-live from the text already in hand. `fallback` reads `<root>/SPEC.md` when no
+    text was supplied -- it is OFF when the caller named the spec files itself, so an
+    explicit `--spec` is never silently topped up from a file nobody asked for."""
+    if fallback and not _lc_go_live(spec_text):
+        sp = os.path.join(root, "SPEC.md")
+        if os.path.isfile(sp):
+            try:
+                with open(sp, "r", encoding="utf-8", errors="replace") as fh:
+                    spec_text = (spec_text or "") + "\n" + fh.read()
+            except OSError:
+                pass
+    return _lifecycle_report(adr_dir or os.path.join(root, "docs", "adr"), spec_text)
+
+
 def _spec_check_text(text):
     lines = text.split("\n")
     n = len(lines)
@@ -11280,6 +11526,11 @@ def cmd_spec_check(args):
     m = (_spec_check_text(text) if text.strip()
          else {"blockers": [], "untestable": [], "stack_hits": [],
                "non_ears": 0, "n_criteria": 0})
+    # lifecycle (ADR-040): read-only and advisory -- it never touches `fail` below.
+    lc = _lifecycle_for(_lifecycle_root(args.spec[0] if args.spec else None,
+                                        args.acceptance),
+                        getattr(args, "adr_dir", None), text,
+                        fallback=not args.spec)
     structural = len(m["blockers"]) + len(acc_block)  # estructura = FACT -> bloquea
     soft_find = len(m["untestable"]) + len(m["stack_hits"]) + len(acc_adv)
     fail = structural > 0 or (args.strict and soft_find > 0)
@@ -11288,7 +11539,7 @@ def cmd_spec_check(args):
     if args.json:
         print(json.dumps({"verdict": verdict, "advisory": structural == 0,
                           "acceptance_blockers": acc_block,
-                          "acceptance_advisory": acc_adv, **m},
+                          "acceptance_advisory": acc_adv, "lifecycle": lc, **m},
                          indent=2, ensure_ascii=False))
         sys.exit(1 if fail else 0)
 
@@ -11309,6 +11560,11 @@ def cmd_spec_check(args):
         print(f"  ~ stack named in criteria ({len(m['stack_hits'])}): {', '.join(terms[:6])} — the 'how' belongs in the ADR, not the SPEC")
     if m["non_ears"] and m["n_criteria"]:
         print(f"  · advisory: {m['non_ears']}/{m['n_criteria']} criteria do not follow the EARS pattern (When/If/While … shall)")
+    print("  · " + _lifecycle_summary(lc))
+    for c in [x for x in lc["components"] if x.get("status") not in ("ok", None)][:5]:
+        print("      %s %s %s - %s (%s)"
+              % ("!" if c["status"] == "expires before go-live" else "~",
+                 c["component"], c.get("version") or "?", c["status"], c["detail"]))
     print("  i consistency: INFERENTIAL (an uncorrelated checker), not this lint · "
           "structure = FACT (blocks) · prose = advisory (--strict to gate)")
     if verdict == "OK":
@@ -12529,6 +12785,9 @@ def build_parser():
                      help="validate ACCEPTANCE traceability (AC-n IDs): missing "
                           "file / zero criteria / zero traceable / duplicate "
                           "IDs block as structural FACTS")
+    psc.add_argument("--adr-dir", default=None,
+                     help="ADRs whose lifecycle: blocks are read (ADR-040); default "
+                          "docs/adr beside the SPEC")
     psc.add_argument("--strict", action="store_true",
                      help="also fail (exit 1) on soft findings: untestable criteria / stack named")
     psc.add_argument("--json", action="store_true")

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

@@ -137,25 +137,49 @@ answer.
    I deduce these core entities: … do they work for you, or is one missing?")
 3. **Operation / API surface.** Propose the endpoints/operations and their
    contracts (idempotency, status codes).
-4. **Big decisions (→ ADR).** Propose 2–3 architecture options with trade-offs and
+4. **Stack and lifecycle (MANDATORY — before any stack/architecture decision is
+   recorded).** The stack is not a given ("we use X"): it is a decision with an EXPIRY
+   DATE. A major version is a family; support is granted to a MINOR line, for a window,
+   by an upstream nobody in the room controls. Ask these one at a time, each with your
+   recommended answer, and **FETCH the dates from the official source AS YOU ASK — never
+   answer from memory**; record the URL and the day you checked:
+   (a) the EXACT version of every runtime/framework/store (JDK, web framework, ORM, DB,
+   Node, bundler, broker, cache) and its OSS/LTS end-of-support date, cited;
+   (b) support window vs the declared go-live AND the expected operating life — does the
+   line stay patched for the whole operation? If not, move it up BEFORE building: a major
+   upgrade days before the milestone is the most expensive one there is;
+   (c) major dependencies and the upgrade policy — who approves one, and when it is
+   scheduled (aligned with the dev-loop's "zero new dependencies without approval");
+   (d) development and observability tools the operator wants from day one (consoles, APM,
+   admin UIs) — they CONSTRAIN versions, so ask early or they force the upgrade;
+   (e) compatibility with reused legacy modules — the minimum version they support.
+   The answers distil into the stack ADR with the dates INSIDE it, as the machine-readable
+   `lifecycle:` frontmatter block (`component` / `version` / `eol` / `source` / `checked`,
+   ISO dates; `eol: unknown` is allowed and reads as a NAMED absence, never a pass) — see
+   `templates/docs/adr/ADR-stack-template.md`. The SPEC declares the milestone it is
+   compared against: frontmatter `go_live: YYYY-MM-DD` or a `**Go-live:** YYYY-MM-DD` line.
+   `qa_ledger.py spec-check` then reports, per component, `ok` / `expires before go-live` /
+   `no EOL cited` / `no source cited` — ADVISORY, it never gates. It can see that a date
+   was CITED; it cannot see whether the citation is TRUE. That part is yours.
+5. **Big decisions (→ ADR).** Propose 2–3 architecture options with trade-offs and
    a recommended default: persistence, protocol, idempotency, sync/async, multi-tenancy.
-5. **Behavior and dirty cases.** Happy path, then failures, retries, partial states,
+6. **Behavior and dirty cases.** Happy path, then failures, retries, partial states,
    concurrency, what must NOT happen.
-6. **Inviolable constraints (→ `CONSTITUTION.md`).** Domain + security + operation
+7. **Inviolable constraints (→ `CONSTITUTION.md`).** Domain + security + operation
    rules that can't be broken (money to the cent, no numbering gaps, never cross
    environments, secrets never logged, auth). Write/extend `CONSTITUTION.md` with these —
    one invariant per line, with a CWE reference where it maps. They feed the severity gate
    downstream, and a breach is a BLOCKER, never a trade-off.
-7. **Out of scope.** Explicit boundaries with forward references.
-8. **Acceptance / Definition of Done.** Concrete, checkable criteria + success metrics.
-9. **Quality bar (→ config, kit 1.17.0).** "What level of quality is ENOUGH here, and which
+8. **Out of scope.** Explicit boundaries with forward references.
+9. **Acceptance / Definition of Done.** Concrete, checkable criteria + success metrics.
+10. **Quality bar (→ config, kit 1.17.0).** "What level of quality is ENOUGH here, and which
    dimensions are negotiable (coverage, perf, security)?" Propose thresholds fit for
    the risk profile (a payments core is not an internal dashboard). What the human
    declares goes into `uscha.config.json` (`defaults.coverage_threshold`,
    `defaults.readiness_caps`, `defaults.simplicity`) — a declared threshold reads as
    **requerimiento (config)** in the engine's output; an undeclared one stays a kit
    default (opinion) and is labeled as such. Declaring is committing the config.
-10. **Residual risks and dependencies.** What's uncertain, what must exist first.
+11. **Residual risks and dependencies.** What's uncertain, what must exist first.
     For each HIGH-uncertainty risk, ask (kit 1.19.0, Tip 21 'Prototype to Learn'):
     "Does it warrant a time-boxed spike before freezing the SPEC?" A spike runs on a
     `spike/*` branch and its ONLY legitimate output is an **ADR with lessons**

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

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "uscha",
-  "version": "1.93.1",
+  "version": "1.94.1",
   "displayName": "Uscha",
   "description": "Spec-driven development for LLM coding agents: 9 skills (discovery, adr-refine, reverse-discovery, characterize, devloop, sysdoc, rubric, mirador, status) + a stdlib measurement engine (qa_ledger.py, 53 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
   "author": {

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

@@ -1,6 +1,6 @@
 {
   "name": "uscha",
-  "version": "1.93.1",
+  "version": "1.94.1",
   "description": "Uscha spec-driven development methodology for coding agents. Includes npm/npx router.",
   "author": {
     "name": "Andres Massello",

package/uscha-kit/README.md

@@ -1,6 +1,6 @@
 # uscha-kit
 
-**Kit version:** v1.93.1 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.94.1 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
 
 Spec-driven orchestrator + multi-repo QA for Claude Code, with a deterministic ledger.
 **Nine skills** (`uscha-discovery`, `uscha-adr-refine`, `uscha-devloop`, `uscha-sysdoc`, `uscha-reverse-discovery`,

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 1.93.1
+uscha-kit 1.94.1