@andresmassello/uscha 1.93.1 → 1.94.0

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.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
 [changelog](https://github.com/andresmassello/uscha/blob/main/uscha-kit/CHANGELOG.md)
 (the per-release changelogs live in the repo, not in the npm tarball)
 
@@ -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.0, 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.0",
   "description": "Spec-driven development for LLM coding agents: 9 skills + a stdlib evidence engine. Facts block, guesses advise; the human approves.",
   "author": {
     "name": "Andres Massello",

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

@@ -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

@@ -8406,6 +8406,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 +9558,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 +9644,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 +10998,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 +11511,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 +11524,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 +11545,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 +12770,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.0",
   "displayName": "Uscha",
   "description": "Spec-driven development for LLM coding agents: 9 skills (discovery, adr-refine, reverse-discovery, characterize, devloop, sysdoc, rubric, mirador, status) + a stdlib measurement engine (qa_ledger.py, 53 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
   "author": {

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

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

package/uscha-kit/README.md

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

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 1.93.1
+uscha-kit 1.94.0

package/uscha-kit/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/skills/uscha-devloop/qa_ledger.py

@@ -8406,6 +8406,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 +9558,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 +9644,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 +10998,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 +11511,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 +11524,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 +11545,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 +12770,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/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/templates/CONSTITUTION.md

@@ -98,6 +98,17 @@ enforcing the record is the engine's job. It is never resolved by "working aroun
 - [ ] `golden-diff` clean (byte for byte) = hard closing condition of the touched module
 - [ ] Corpus documented; a module with insufficient corpus = PARTIAL, never COVERS
 
+## Stack lifecycle — the stack expires (non-negotiable)
+
+> A major version is a family; support is granted to a MINOR line, for a window, by an upstream
+> nobody here controls. A stack ADR that fixes a version without its end-of-support date has not
+> decided anything — it has deferred the decision to the week before go-live (ADR-040).
+> Measured — ADVISORY, never a gate — by `qa_ledger.py spec-check`'s lifecycle dimension.
+
+- [ ] No stack ADR without a cited end-of-support date for every component it fixes <!-- ADR-040 -->
+- [ ] The date comes from the OFFICIAL source, fetched when asked, with the URL and the day checked recorded — never from memory
+- [ ] No component whose support ends before the declared `go_live` enters the build; the upgrade happens BEFORE, not days after
+
 ## Anti-ceremony — Lean over the method itself (meta-invariant)
 
 > The risk is not a bad gate: it is the **sum** of good gates turning `/uscha-devloop` into an
@@ -139,6 +150,12 @@ enforcing the record is the engine's job. It is never resolved by "working aroun
 - The **Golden (INV-GOLDEN-01)** invariant is measured by `qa_ledger.py golden-diff`: any `.received`
   that does not match its `.approved` (or is unapproved) = **DIVERGE**, cutting the chain before judgment-day.
   The agent does not touch `.approved` (ideally a `PreToolUse` hook makes it impossible).
+- The **Stack lifecycle** invariant is measured by `qa_ledger.py spec-check`: each `lifecycle:`
+  entry in `docs/adr/*.md` is compared against the SPEC's `go_live` and reads `ok` / `expires
+  before go-live` / `no EOL cited` / `no source cited`, with the whole dimension UNMEASURED (and
+  the reason named) when nothing declares it. **Advisory** — it never gates and never caps
+  readiness: the engine can see that a date was CITED, never that the citation is true. Verifying
+  the source is the human's job; the record makes the omission visible.
 - The **Anti-ceremony** meta-invariant is not measured by any subcommand: it is the admission filter
   for new gates (does it autorun? does it stay quiet except when it matters? does it collapse into `readiness`? does a
   trivial change skip it?). Its only mechanized leg today is the single verdict of `readiness` (kit

package/uscha-kit/templates/docs/adr/ADR-stack-template.md

@@ -0,0 +1,73 @@
+---
+# The machine-readable half of a stack ADR (ADR-040). One entry per component this ADR
+# FIXES: runtime, web framework, ORM, database, Node, bundler, message broker, cache.
+#
+#   component  the name as your team says it
+#   version    the EXACT version or minor line you are fixing -- not the major family
+#   eol        end of OSS/LTS support, YYYY-MM-DD. `unknown` is allowed and reads as a
+#              NAMED absence ("no EOL cited"), never as a pass
+#   source     the OFFICIAL page the date came from. Fetch it while you ask; never
+#              answer from memory
+#   checked    the day you actually looked, YYYY-MM-DD
+#
+# `qa_ledger.py spec-check` reads this block and compares each `eol` against the
+# `go_live` declared in the SPEC. It is ADVISORY: it never gates and never caps
+# readiness. It measures that a date and a source were CITED -- it cannot verify that
+# the source tells the truth. That check is the human's.
+lifecycle:
+  - component: <runtime, e.g. the language runtime>
+    version: "<exact version or minor line>"
+    eol: YYYY-MM-DD
+    source: https://<official support page>
+    checked: YYYY-MM-DD
+  - component: <web framework>
+    version: "<exact version or minor line>"
+    eol: YYYY-MM-DD
+    source: https://<official support page>
+    checked: YYYY-MM-DD
+  - component: <database / store>
+    version: "<exact version or minor line>"
+    eol: unknown
+    source: https://<official support page>
+    checked: YYYY-MM-DD
+---
+# ADR-NNN: <the stack this project fixes, and until when it is supported>
+
+## Status: Accepted
+
+> The SPEC must declare the milestone this block is compared against, as frontmatter
+> `go_live: YYYY-MM-DD` or a `**Go-live:** YYYY-MM-DD` line. Without it the whole
+> dimension reads UNMEASURED, with the reason named.
+
+## Context
+<Why this stack, and what already constrains it: reused legacy modules and the minimum
+versions they support, the operator's development/observability tooling (consoles, APM,
+admin UIs) — those constrain versions, so they are asked BEFORE the stack is fixed, not
+after — and the expected operating life of the system beyond go-live.>
+
+## Alternatives
+- A) <option> — support window <until when>, cost <…>
+- B) <option> — support window <until when>, cost <…>
+
+## Decision
+- <The exact versions fixed, one line each, with the date they stop being supported.>
+- **Upgrade policy**: <who approves a major upgrade, and when it is scheduled>. A new
+  dependency is never added without explicit approval (the dev-loop's "zero new
+  dependencies without approval" rule).
+
+## Reasons
+- <why this line, and why its support window covers the operation, not just the launch>
+
+## Consequences
++ <the good>
+- <the cost: the upgrade already on the calendar, and who owns it>
+
+## Implementation Plan
+- Affected paths: <build files, lockfiles, CI images, base images>
+- Tests: <the suite that proves the fixed versions actually run>
+
+## Verification
+- [ ] Every component this ADR fixes carries a `version`, an `eol` and the `source` it
+      was read from, checked on a named day.
+- [ ] No component's `eol` falls before the SPEC's `go_live`; where one does, the upgrade
+      is scheduled BEFORE the build, not after.

package/uscha-kit/templates/docs/adr/README.md

@@ -8,6 +8,11 @@ Format: Status (proposed/accepted/experiment/deprecated/superseded) · Context
 Decision · Consequences · Implementation Plan (affected paths, patterns, tests) ·
 Verification (checkboxes).
 
+The ADR that fixes the stack has a template of its own, `ADR-stack-template.md`: it carries a
+machine-readable `lifecycle:` frontmatter block (component / version / eol / source / checked)
+that `spec-check` compares against the SPEC's declared `go_live` (ADR-040). Advisory: it reports,
+it never gates.
+
 `Status: Experiment` is for a bounded, reversible hypothesis that needs real feedback.
 It must include: Hypothesis, Feedback Signal, Review By or Review Trigger, Promote
 Criteria, and Rollback / Supersede Criteria. Missing/expired metadata is advisory in

package/uscha-kit/uscha.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.93.1",
+  "version": "1.94.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,