@mohammadhprp/system-prompt 0.11.1 → 0.11.2

package/framework/skills/tlc-spec-driven/scripts/lessons.py

@@ -0,0 +1,412 @@
+#!/usr/bin/env python3
+"""
+lessons.py - deterministic bookkeeping for the tlc-spec-driven lessons layer.
+
+The LLM supplies judgment (which failure happened, how to phrase the lesson, what
+signal grounds it). This script owns everything mechanical: IDs, distinct-feature
+recurrence counting, candidate->confirmed promotion, pruning, demotion, and
+rendering the human/agent-readable playbook. Bookkeeping by hand is exactly what
+rots a lessons file, so it lives here, not in a prompt.
+
+Canonical state:  .specs/lessons.json   (machine-owned - do NOT hand-edit)
+Rendered view:    .specs/LESSONS.md      (regenerated on every write)
+
+Pure standard library. No dependencies. The script file lives in this skill's
+`scripts/` directory - invoke it as `python3 <skill-dir>/scripts/lessons.py ...`
+(never `python3 scripts/lessons.py` from a consuming project root). Run with
+cwd at the project root (the dir that contains .specs), or pass --root.
+
+Commands:
+  add        Record a grounded lesson from a verification signal.
+  list       Print lessons (default: confirmed) for loading at Specify/Design.
+  penalize   Mark a confirmed lesson as having failed when applied (-> quarantine).
+  prune      Drop stale uncorroborated candidates (also runs automatically on add/list).
+  status     Print counts (used by the self-check in validate.md).
+  init       Create empty store + rendered file.
+  selftest   Run stdlib regressions (normalization).
+
+Exit codes: 0 ok, 2 usage/validation error (e.g. missing grounding).
+"""
+
+import argparse
+import datetime as _dt
+import json
+import os
+import re
+import sys
+import unicodedata
+
+STORE_REL = os.path.join(".specs", "lessons.json")
+RENDER_REL = os.path.join(".specs", "LESSONS.md")
+
+SIGNALS = {
+    "ac_gap": "Acceptance criterion not covered / failed",
+    "surviving_mutant": "Discrimination sensor mutant survived (weak test)",
+    "spec_precision_gap": "Spec did not define a precise outcome",
+    "spec_deviation": "Implementation diverged from spec/design (SPEC_DEVIATION)",
+    "gate_fail": "Build-level gate check failed",
+}
+
+DEFAULTS = {"promote_threshold": 2, "window_days": 45, "quarantine_threshold": 2}
+
+
+def _now():
+    return _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _parse_date(s):
+    try:
+        return _dt.datetime.strptime(s, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=_dt.timezone.utc)
+    except Exception:
+        return _dt.datetime.now(_dt.timezone.utc)
+
+
+def _store_path(root):
+    return os.path.join(root, STORE_REL)
+
+
+def _render_path(root):
+    return os.path.join(root, RENDER_REL)
+
+
+def _load(root):
+    path = _store_path(root)
+    if not os.path.exists(path):
+        return {
+            "schema": 1,
+            "promote_threshold": DEFAULTS["promote_threshold"],
+            "window_days": DEFAULTS["window_days"],
+            "quarantine_threshold": DEFAULTS["quarantine_threshold"],
+            "next_id": 1,
+            "lessons": [],
+        }
+    with open(path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    for k, v in DEFAULTS.items():
+        data.setdefault(k, v)
+    data.setdefault("schema", 1)
+    data.setdefault("next_id", 1)
+    data.setdefault("lessons", [])
+    return data
+
+
+def _save(root, data):
+    os.makedirs(os.path.join(root, ".specs"), exist_ok=True)
+    with open(_store_path(root), "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+    _render(root, data)
+
+
+def _norm(text):
+    """Normalized dedup key for lesson text.
+
+    - casefold + NFD, strip combining marks (so Portuguese diacritics match ASCII peers)
+    - keep characters where str.isalnum() is true (any script) and whitespace
+    - drop other punctuation, collapse whitespace
+
+    Exact-after-normalization only - no semantic matching (stdlib-only limitation).
+    Phrase lessons tersely and canonically so recurrences actually merge.
+    """
+    t = unicodedata.normalize("NFD", text.casefold())
+    t = "".join(c for c in t if unicodedata.category(c) != "Mn")
+    t = "".join(c if (c.isalnum() or c.isspace()) else " " for c in t)
+    t = re.sub(r"\s+", " ", t).strip()
+    return t
+
+
+def _selftest_norm():
+    """Regressions for #158: Portuguese diacritics + distinct non-Latin text."""
+    failures = []
+
+    def check(cond, msg):
+        if not cond:
+            failures.append(msg)
+
+    a = _norm("Não use datas locais")
+    b = _norm("Nao use datas locais")
+    check(a == b == "nao use datas locais", f"PT diacritics: {a!r} vs {b!r}")
+
+    jp1 = _norm("日本語の文です")
+    jp2 = _norm("別の日本語文")
+    check(jp1 != "", f"JP1 empty: {jp1!r}")
+    check(jp2 != "", f"JP2 empty: {jp2!r}")
+    check(jp1 != jp2, f"JP sentences collapsed: {jp1!r} == {jp2!r}")
+
+    check(_norm("café") == _norm("cafe") == "cafe", f"cafe: {_norm('café')!r}")
+
+    if failures:
+        for f in failures:
+            print(f"FAIL: {f}", file=sys.stderr)
+        return 1
+    print("selftest_norm: ok")
+    return 0
+
+
+def _key(signal, text):
+    return signal + "::" + _norm(text)
+
+
+def _auto_prune(data):
+    """Drop candidates that never recurred within the window. Mutates data."""
+    threshold = data["promote_threshold"]
+    window = data["window_days"]
+    now = _dt.datetime.now(_dt.timezone.utc)
+    kept = []
+    dropped = []
+    for l in data["lessons"]:
+        if l["status"] == "candidate" and l["recurrence"] < threshold:
+            age_days = (now - _parse_date(l.get("last_seen", l.get("created", _now())))).days
+            if age_days > window:
+                dropped.append(l["id"])
+                continue
+        kept.append(l)
+    data["lessons"] = kept
+    return dropped
+
+
+def _find(data, signal, text):
+    k = _key(signal, text)
+    for l in data["lessons"]:
+        if l.get("key") == k:
+            return l
+    return None
+
+
+def _render(root, data):
+    lines = []
+    lines.append("# LESSONS - auto-maintained by scripts/lessons.py")
+    lines.append("")
+    lines.append("> Machine-owned. Do NOT hand-edit. Changes are overwritten on the next `lessons.py` write.")
+    lines.append("> Canonical state lives in `.specs/lessons.json`. Edit lessons only via the script.")
+    lines.append(f"> promote_threshold={data['promote_threshold']} distinct features · window_days={data['window_days']} · quarantine_threshold={data['quarantine_threshold']}")
+    lines.append("")
+
+    by_status = {"confirmed": [], "candidate": [], "quarantined": []}
+    for l in data["lessons"]:
+        by_status.get(l["status"], by_status["candidate"]).append(l)
+
+    def block(title, items, note):
+        out = [f"## {title}", ""]
+        if note:
+            out.append(note)
+            out.append("")
+        if not items:
+            out.append("_none_")
+            out.append("")
+            return out
+        for l in sorted(items, key=lambda x: x["id"]):
+            scope = f" · scope: `{l['scope']}`" if l.get("scope") else ""
+            out.append(f"### {l['id']} - {l['text']}")
+            out.append(
+                f"- signal: `{l['signal']}` · recurrence: {l['recurrence']} feature(s){scope} · harmful: {l.get('harmful', 0)}"
+            )
+            feats = ", ".join(l.get("features", [])) or "-"
+            out.append(f"- features: {feats}")
+            ev = l.get("evidence", [])
+            if ev:
+                out.append(f"- evidence: {ev[0]}" + (f" (+{len(ev) - 1} more)" if len(ev) > 1 else ""))
+            out.append(f"- last seen: {l.get('last_seen', '-')}")
+            out.append("")
+        return out
+
+    lines += block(
+        "Confirmed (load these at Specify/Design)",
+        by_status["confirmed"],
+        "Corroborated across multiple features. Safe to apply as guidance.",
+    )
+    lines += block(
+        "Candidates (under observation - do NOT load as guidance yet)",
+        by_status["candidate"],
+        "Seen once or not yet corroborated. Tracked, not trusted.",
+    )
+    lines += block(
+        "Quarantined (failed when applied - ignore)",
+        by_status["quarantined"],
+        "A confirmed lesson that recurred alongside failure. Kept for the maintainer to review.",
+    )
+
+    with open(_render_path(root), "w", encoding="utf-8") as f:
+        f.write("\n".join(lines).rstrip() + "\n")
+
+
+# ----------------------------- commands -----------------------------
+
+def cmd_init(root, args):
+    data = _load(root)
+    _save(root, data)
+    print(f"Initialized lessons store at {_store_path(root)} and {_render_path(root)}")
+    return 0
+
+
+def cmd_add(root, args):
+    signal = args.signal
+    source = (args.source or "").strip()
+    text = (args.text or "").strip()
+    feature = (args.feature or "").strip()
+
+    # Grounding is enforced here, deterministically - not left to the prompt.
+    if signal not in SIGNALS:
+        print(f"ERROR: --signal must be one of {sorted(SIGNALS)}", file=sys.stderr)
+        return 2
+    if not feature:
+        print("ERROR: --feature is required (the feature the signal came from).", file=sys.stderr)
+        return 2
+    if not source:
+        print("ERROR: --source is required (file:line / AC id / mutant id / SPEC_DEVIATION ref).", file=sys.stderr)
+        print("       A lesson with no grounding in validation.md is an opinion, not a lesson. Refused.", file=sys.stderr)
+        return 2
+    if len(text) < 12:
+        print("ERROR: --text too short. State the actionable lesson in one terse sentence.", file=sys.stderr)
+        return 2
+
+    data = _load(root)
+    _auto_prune(data)
+    existing = _find(data, signal, text)
+    now = _now()
+
+    if existing:
+        if feature not in existing["features"]:
+            existing["features"].append(feature)
+        existing["recurrence"] = len(existing["features"])
+        existing["last_seen"] = now
+        ev = source if not args.scope else f"{source} ({args.scope})"
+        if ev not in existing["evidence"]:
+            existing["evidence"].append(ev)
+        promoted = False
+        if existing["status"] == "candidate" and existing["recurrence"] >= data["promote_threshold"]:
+            existing["status"] = "confirmed"
+            promoted = True
+        _save(root, data)
+        msg = f"UPDATED {existing['id']} (recurrence={existing['recurrence']}, status={existing['status']})"
+        if promoted:
+            msg += " - PROMOTED to confirmed"
+        print(msg)
+    else:
+        lid = f"L-{data['next_id']:03d}"
+        data["next_id"] += 1
+        data["lessons"].append(
+            {
+                "id": lid,
+                "key": _key(signal, text),
+                "text": text,
+                "signal": signal,
+                "scope": (args.scope or "").strip(),
+                "status": "candidate",
+                "features": [feature],
+                "recurrence": 1,
+                "harmful": 0,
+                "evidence": [source if not args.scope else f"{source} ({args.scope})"],
+                "created": now,
+                "last_seen": now,
+            }
+        )
+        _save(root, data)
+        print(f"ADDED {lid} (status=candidate, recurrence=1)")
+    return 0
+
+
+def cmd_penalize(root, args):
+    data = _load(root)
+    target = None
+    for l in data["lessons"]:
+        if l["id"].lower() == args.id.lower():
+            target = l
+            break
+    if not target:
+        print(f"ERROR: no lesson with id {args.id}", file=sys.stderr)
+        return 2
+    target["harmful"] = target.get("harmful", 0) + 1
+    target["last_seen"] = _now()
+    if target["harmful"] >= data["quarantine_threshold"]:
+        target["status"] = "quarantined"
+    _save(root, data)
+    print(f"PENALIZED {target['id']} (harmful={target['harmful']}, status={target['status']})")
+    return 0
+
+
+def cmd_list(root, args):
+    data = _load(root)
+    if _auto_prune(data):
+        _save(root, data)
+    want = args.status
+    q = (args.query or "").lower().strip()
+    scope = (args.scope or "").lower().strip()
+    rows = []
+    for l in data["lessons"]:
+        if want != "all" and l["status"] != want:
+            continue
+        if q and q not in l["text"].lower():
+            continue
+        if scope and scope not in (l.get("scope", "").lower()):
+            continue
+        rows.append(l)
+    if not rows:
+        print(f"(no {want} lessons" + (f" matching '{q or scope}'" if (q or scope) else "") + ")")
+        return 0
+    for l in sorted(rows, key=lambda x: x["id"]):
+        sc = f" [scope:{l['scope']}]" if l.get("scope") else ""
+        print(f"{l['id']} ({l['status']}, x{l['recurrence']}){sc}: {l['text']}")
+    return 0
+
+
+def cmd_prune(root, args):
+    data = _load(root)
+    dropped = _auto_prune(data)
+    _save(root, data)
+    print(f"Pruned {len(dropped)} stale candidate(s): {', '.join(dropped) if dropped else '-'}")
+    return 0
+
+
+def cmd_status(root, args):
+    data = _load(root)
+    counts = {"confirmed": 0, "candidate": 0, "quarantined": 0}
+    for l in data["lessons"]:
+        counts[l["status"]] = counts.get(l["status"], 0) + 1
+    total = len(data["lessons"])
+    print(f"lessons: {total} total | confirmed={counts['confirmed']} candidate={counts['candidate']} quarantined={counts['quarantined']}")
+    return 0
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="lessons.py", description="Deterministic lessons bookkeeping for tlc-spec-driven.")
+    p.add_argument("--root", default=".", help="Project root containing .specs/ (default: current dir)")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sp = sub.add_parser("init", help="Create empty store + rendered file")
+    sp.set_defaults(fn=cmd_init)
+
+    sp = sub.add_parser("add", help="Record a grounded lesson")
+    sp.add_argument("--feature", required=True)
+    sp.add_argument("--signal", required=True, choices=sorted(SIGNALS))
+    sp.add_argument("--source", required=True, help="file:line / AC id / mutant id / SPEC_DEVIATION ref")
+    sp.add_argument("--text", required=True, help="One terse, actionable sentence")
+    sp.add_argument("--scope", default="", help="Optional: path/layer/tag for retrieval filtering")
+    sp.set_defaults(fn=cmd_add)
+
+    sp = sub.add_parser("penalize", help="Mark a confirmed lesson as failed-when-applied")
+    sp.add_argument("--id", required=True)
+    sp.set_defaults(fn=cmd_penalize)
+
+    sp = sub.add_parser("list", help="Print lessons for loading")
+    sp.add_argument("--status", default="confirmed", choices=["confirmed", "candidate", "quarantined", "all"])
+    sp.add_argument("--query", default="", help="Substring filter on lesson text")
+    sp.add_argument("--scope", default="", help="Substring filter on scope")
+    sp.set_defaults(fn=cmd_list)
+
+    sp = sub.add_parser("prune", help="Drop stale uncorroborated candidates")
+    sp.set_defaults(fn=cmd_prune)
+
+    sp = sub.add_parser("status", help="Print counts")
+    sp.set_defaults(fn=cmd_status)
+
+    sp = sub.add_parser("selftest", help="Run stdlib regressions (normalization)")
+    sp.set_defaults(fn=lambda root, args: _selftest_norm())
+
+    args = p.parse_args(argv)
+    root = os.path.abspath(args.root)
+    return args.fn(root, args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/framework/skills/tlc-spec-driven/scripts/validate_spec.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""
+validate_spec.py - deterministic closure-gate checks for a feature spec.md.
+
+Turns the Requirement Closure Gate (Specify phase) into a checkable pass/fail
+run BEFORE a spec is presented for confirmation, instead of trusting the model
+to remember the checks. Pure standard library, zero dependencies. Operates only
+on the spec.md markdown artifact - never on the target codebase - so it stays
+stack-agnostic and tool-agnostic.
+
+What it checks (heuristic markdown inspection, not a full parser):
+  ERROR  - a required section is missing
+  ERROR  - an acceptance criterion has no SHALL (not testable / not EARS-shaped)
+  ERROR  - an Assumptions row has an empty "Chosen default" or "Rationale" cell
+  ERROR  - a Requirement Traceability row has a malformed ID
+  WARN   - an AC has SHALL but no recognizable EARS lead keyword
+  WARN   - template placeholder rows are still present (spec not filled in)
+  WARN   - open questions are not explicitly resolved
+
+Usage:
+  python3 <skill-dir>/scripts/validate_spec.py [target] [--root DIR] [--strict]
+
+  Invoke from the skill directory that ships this script (not the project root).
+  target    Path to a spec.md, a feature directory, or a project root.
+            Omitted -> auto-detect the single feature under <root>/.specs/features/.
+  --root    Project root that contains .specs/ (default: current dir).
+  --strict  Treat warnings as errors.
+
+Exit codes: 0 pass, 1 errors found (or warnings under --strict), 2 usage error.
+"""
+
+import argparse
+import os
+import re
+import sys
+
+REQUIRED_SECTIONS = [
+    "Problem Statement",
+    "Out of Scope",
+    "Assumptions & Open Questions",
+    "User Stories",
+    "Requirement Traceability",
+]
+
+ID_RE = re.compile(r"^[A-Z][A-Z0-9]*-\d+$")
+PLACEHOLDER_RE = re.compile(r"^\s*\[.+\]\s*$")
+STATUS_VALUES = {"pending", "in design", "in tasks", "implementing", "verified"}
+
+
+def resolve_spec(target, root):
+    """Return the path to a spec.md from a file, dir, or auto-detect."""
+    if target:
+        if os.path.isfile(target):
+            return target
+        if os.path.isdir(target):
+            cand = os.path.join(target, "spec.md")
+            if os.path.isfile(cand):
+                return cand
+            # maybe it's a project root
+            return _autodetect(target)
+        # Not a path: treat as a feature name under <root>/.specs/features/<name>/
+        cand = os.path.join(root, ".specs", "features", target, "spec.md")
+        if os.path.isfile(cand):
+            return cand
+        return None
+    return _autodetect(root)
+
+
+def _autodetect(root):
+    base = os.path.join(root, ".specs", "features")
+    if not os.path.isdir(base):
+        return None
+    features = [
+        d for d in sorted(os.listdir(base))
+        if os.path.isfile(os.path.join(base, d, "spec.md"))
+    ]
+    if len(features) == 1:
+        return os.path.join(base, features[0], "spec.md")
+    if len(features) == 0:
+        return None
+    # Ambiguous: signal the caller with the list.
+    raise SystemExit(
+        "validate_spec: multiple features found; pass one explicitly:\n  "
+        + "\n  ".join(os.path.join(base, f, "spec.md") for f in features)
+    )
+
+
+def split_row(line):
+    cells = line.strip().strip("|").split("|")
+    return [c.strip() for c in cells]
+
+
+def is_separator(line):
+    return bool(re.match(r"^\s*\|?[\s:|-]+\|?\s*$", line)) and "-" in line
+
+
+def section_bounds(lines, name):
+    """Return (start, end) line indices for a `## name` section body."""
+    start = None
+    for i, ln in enumerate(lines):
+        if re.match(r"^#{1,3}\s+" + re.escape(name) + r"\s*$", ln.strip()):
+            start = i + 1
+            break
+    if start is None:
+        return None
+    end = len(lines)
+    for j in range(start, len(lines)):
+        if re.match(r"^#{1,3}\s+\S", lines[j]):
+            end = j
+            break
+    return (start, end)
+
+
+def classify_ears(text):
+    """Return (ok, note). ok requires a SHALL; note records the EARS pattern."""
+    t = text.strip()
+    low = t.lower()
+    has_shall = bool(re.search(r"\bshall\b", low))
+    if not has_shall:
+        return (False, "no SHALL")
+    kws = []
+    if re.search(r"\bwhile\b", low):
+        kws.append("WHILE")
+    if re.search(r"\bwhen\b", low):
+        kws.append("WHEN")
+    if re.match(r"^\s*if\b", low) or re.search(r"\bif\b.*\bthen\b", low):
+        kws.append("IF/THEN")
+    if re.search(r"\bwhere\b", low):
+        kws.append("WHERE")
+    if len(kws) >= 2:
+        return (True, "complex (" + "+".join(kws) + ")")
+    if kws:
+        pattern = {
+            "WHILE": "state-driven",
+            "WHEN": "event-driven",
+            "IF/THEN": "unwanted-behavior",
+            "WHERE": "optional-feature",
+        }[kws[0]]
+        return (True, pattern)
+    if re.match(r"^\s*the\b", low):
+        return (True, "ubiquitous")
+    return (True, "warn: SHALL present but no EARS lead keyword")
+
+
+def check(spec_path):
+    with open(spec_path, "r", encoding="utf-8") as f:
+        text = f.read()
+    lines = text.splitlines()
+    errors, warnings = [], []
+
+    # 1. Required sections.
+    for name in REQUIRED_SECTIONS:
+        if section_bounds(lines, name) is None:
+            errors.append(f"missing required section: ## {name}")
+
+    # 2. Acceptance criteria are EARS-shaped (have a SHALL).
+    in_ac = False
+    for i, ln in enumerate(lines, start=1):
+        stripped = ln.strip()
+        if re.match(r"^\*{0,2}Acceptance Criteria\*{0,2}\s*:?\s*$", stripped):
+            in_ac = True
+            continue
+        if in_ac:
+            m = re.match(r"^\s*\d+\.\s+(.*)$", ln)
+            if m:
+                item = m.group(1).strip()
+                if PLACEHOLDER_RE.match(item):
+                    continue  # untouched template row
+                ok, note = classify_ears(item)
+                if not ok:
+                    errors.append(f"L{i}: acceptance criterion has no SHALL (not testable): {item[:70]}")
+                elif note.startswith("warn"):
+                    warnings.append(f"L{i}: AC has SHALL but no EARS keyword (WHEN/WHILE/WHERE/IF or ubiquitous 'The … shall'): {item[:60]}")
+            elif stripped == "" or re.match(r"^#{1,3}\s", ln) or stripped.startswith("**"):
+                in_ac = False
+
+    # 3. Assumptions table cells filled.
+    b = section_bounds(lines, "Assumptions & Open Questions")
+    if b:
+        rows = [lines[i] for i in range(*b) if lines[i].strip().startswith("|")]
+        data = [r for r in rows if not is_separator(r)]
+        # drop the header row (first table row)
+        if data:
+            data = data[1:]
+        template_seen = False
+        for r in data:
+            cells = split_row(r)
+            if len(cells) < 3:
+                continue
+            assumption, chosen, rationale = cells[0], cells[1], cells[2]
+            if PLACEHOLDER_RE.match(assumption) and PLACEHOLDER_RE.match(chosen):
+                template_seen = True
+                continue
+            if not chosen or PLACEHOLDER_RE.match(chosen):
+                errors.append(f"assumption '{assumption[:40]}' has empty 'Chosen default'")
+            if not rationale or PLACEHOLDER_RE.match(rationale):
+                errors.append(f"assumption '{assumption[:40]}' has empty 'Rationale'")
+        if template_seen:
+            warnings.append("Assumptions table still contains template placeholder rows")
+        # open questions line
+        oq = [lines[i] for i in range(*b) if "open questions" in lines[i].lower()]
+        oq_clean = re.sub(r"[*_]", "", " ".join(oq)).lower()
+        if not oq:
+            warnings.append("no 'Open questions:' line in Assumptions section")
+        elif not re.search(r"open questions.*:\s*none", oq_clean):
+            warnings.append("open questions do not read as resolved ('Open questions: none')")
+
+    # 4. Requirement traceability IDs.
+    b = section_bounds(lines, "Requirement Traceability")
+    if b:
+        rows = [lines[i] for i in range(*b) if lines[i].strip().startswith("|")]
+        data = [r for r in rows if not is_separator(r)]
+        if data:
+            data = data[1:]
+        template_seen = False
+        real_ids = 0
+        for r in data:
+            cells = split_row(r)
+            if not cells:
+                continue
+            rid = cells[0]
+            if PLACEHOLDER_RE.match(rid) or "[" in rid:
+                template_seen = True
+                continue
+            if not rid:
+                continue
+            if not ID_RE.match(rid):
+                errors.append(f"malformed requirement ID: '{rid}' (expected e.g. AUTH-01)")
+            else:
+                real_ids += 1
+        if template_seen and real_ids == 0:
+            warnings.append("Requirement Traceability has only template rows (no real IDs yet)")
+
+    return errors, warnings
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="validate_spec.py", description="Closure-gate checks for a feature spec.md.")
+    p.add_argument("target", nargs="?", default=None)
+    p.add_argument("--root", default=".")
+    p.add_argument("--strict", action="store_true")
+    args = p.parse_args(argv)
+
+    spec = resolve_spec(args.target, args.root)
+    if not spec:
+        print("validate_spec: could not locate a spec.md. Pass a path or run from the project root.", file=sys.stderr)
+        return 2
+
+    errors, warnings = check(spec)
+    for w in warnings:
+        print(f"  WARN  {w}")
+    for e in errors:
+        print(f"  ERROR {e}")
+    fail = errors or (warnings and args.strict)
+    print(f"\nvalidate_spec: {len(errors)} error(s), {len(warnings)} warning(s) in {spec}")
+    return 1 if fail else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())