@massa-ai/cursor-plugin 1.19.0 → 1.21.0

package/skills/massa-ai/scripts/validate_spec.py

@@ -0,0 +1,272 @@
+#!/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 skills/massa-ai/scripts/validate_spec.py [target] [--root DIR] [--strict]
+
+  Invoke with the repo-root-relative script path shown above (matches
+  lessons.py's convention), not a project-local copy.
+  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).
+    #
+    # massa-ai patch (beyond D1): upstream terminated the AC scan on the FIRST
+    # blank line after the "**Acceptance Criteria**:" header, before any item
+    # was ever read - massa-ai's (and TLC's own) template puts a blank line
+    # between the header and the numbered list, so the SHALL check was a
+    # silent no-op against every realistically-formatted spec. Track whether
+    # an item has been seen and only let a blank line end the block once it
+    # has, so leading blank lines are skipped instead of ending the scan.
+    in_ac = False
+    seen_item = 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
+            seen_item = False
+            continue
+        if in_ac:
+            m = re.match(r"^\s*\d+\.\s+(.*)$", ln)
+            if m:
+                seen_item = True
+                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 re.match(r"^#{1,3}\s", ln) or stripped.startswith("**") or (stripped == "" and seen_item):
+                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())

package/skills/massa-ai/scripts/validate_state.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""
+validate_state.py - deterministic completion gate for a feature.
+
+The skill's strongest invariant is "the Verifier is always-on, never prompted;
+Execute is not done until validation.md reports PASS." That is prose the model
+must remember. This turns it into a checkable pass/fail the closing step runs
+automatically, so declaring a feature done without a real Verifier report fails
+loudly instead of slipping through.
+
+It does NOT merely check that validation.md exists - a report that exists but is
+empty, still holds the template placeholder, or has no evidence would pass a
+shallow existence check while proving nothing. This gate requires a real,
+filled verdict plus at least one file:line evidence citation.
+
+Operates only on the .specs/ markdown artifacts (stack- and tool-agnostic). No
+dependencies. Run from the project root (the dir that contains .specs), or pass
+--root. Meant to be invoked by the skill as the closing gate of Execute, the
+same way lessons.py is invoked at distillation - not a manual step.
+
+Usage:
+  python3 skills/massa-ai/scripts/validate_state.py [feature]
+  python3 skills/massa-ai/scripts/validate_state.py
+
+  Invoke with the repo-root-relative script path shown above (matches
+  lessons.py's convention), not a project-local copy. Pass --root when cwd is
+  not the project that contains .specs/.
+
+Exit codes: 0 ok, 1 a completed feature is missing a real PASS report,
+            2 usage error.
+"""
+
+import argparse
+import os
+import re
+import sys
+
+# A file:line citation: a path with an extension, then :<line>. e.g. src/a.ts:42
+EVIDENCE_RE = re.compile(r"[\w./-]+\.[A-Za-z0-9]+:\d+")
+
+
+def _feature_dirs(root):
+    base = os.path.join(root, ".specs", "features")
+    if not os.path.isdir(base):
+        return base, []
+    dirs = [
+        d for d in sorted(os.listdir(base))
+        if os.path.isdir(os.path.join(base, d))
+    ]
+    return base, dirs
+
+
+def _verdict(text):
+    """Return 'pass', 'fail', 'unfilled', or None from a validation report."""
+    lines = text.splitlines()
+    # Scope to the '## Summary' section when it carries its own Result line:
+    # the Discrimination Sensor's per-mutation `**Result**:` sub-line elsewhere
+    # in the report can carry the opposite word (sensor PASS, overall FAIL) and
+    # must not collide with the report verdict.
+    summary_lines = []
+    in_summary = False
+    for ln in lines:
+        stripped = ln.strip()
+        if re.match(r"^#{1,4}\s*summary\b", stripped, re.IGNORECASE):
+            in_summary = True
+            continue
+        if in_summary and re.match(r"^#{1,4}\s", stripped):
+            break
+        if in_summary:
+            summary_lines.append(ln)
+    result_re = r"\*{0,2}result\*{0,2}\s*:"
+    if any(re.search(result_re, ln.strip(), re.IGNORECASE) for ln in summary_lines):
+        scope = summary_lines
+    else:
+        scope = lines
+    # Look at the '## Validation' heading first, then a '**Result**' line.
+    candidates = [
+        ln for ln in scope
+        if re.search(r"^#{1,4}\s*validation\b", ln.strip(), re.IGNORECASE)
+        or re.search(result_re, ln.strip(), re.IGNORECASE)
+    ]
+    hay = " ".join(candidates) if candidates else "\n".join(scope)
+    has_pass = re.search(r"\bPASS\b", hay) is not None
+    has_fail = re.search(r"\bFAIL\b", hay) is not None
+    if has_pass and has_fail:
+        # Both present on the verdict line = unfilled template "[PASS | FAIL]".
+        return "unfilled"
+    if has_pass:
+        return "pass"
+    if has_fail:
+        return "fail"
+    return None
+
+
+def _appears_complete(fdir):
+    """Conservative completeness heuristic for the cross-check mode.
+
+    A feature 'appears complete' if it already has a validation.md, or if it has
+    a tasks.md with at least one task and no unchecked '- [ ]' boxes left. When
+    the signal is ambiguous (no tasks.md, Tasks phase skipped), returns False so
+    an in-flight feature is never falsely flagged.
+    """
+    if os.path.exists(os.path.join(fdir, "validation.md")):
+        return True
+    tasks = os.path.join(fdir, "tasks.md")
+    if not os.path.exists(tasks):
+        return False
+    body = open(tasks, encoding="utf-8", errors="replace").read()
+    if not re.search(r"^#{2,4}\s+T\d+\s*:", body, re.MULTILINE):
+        return False
+    if re.search(r"^\s*-\s*\[\s\]", body, re.MULTILINE):
+        return False  # unchecked box remains -> still in progress
+    return True
+
+
+def _check_feature(fdir, name):
+    """Return list of error strings for one feature (empty = pass)."""
+    errors = []
+    vpath = os.path.join(fdir, "validation.md")
+    if not os.path.exists(vpath):
+        errors.append(
+            f"{name}: no validation.md - Execute is not done until the Verifier "
+            f"writes it (author != verifier). Dispatch validation before marking done."
+        )
+        return errors
+    text = open(vpath, encoding="utf-8", errors="replace").read()
+    verdict = _verdict(text)
+    if verdict is None:
+        errors.append(f"{name}: validation.md has no PASS/FAIL verdict (a prose-only report does not count)")
+    elif verdict == "unfilled":
+        errors.append(f"{name}: validation.md verdict is still the template placeholder '[PASS | FAIL]' - not filled")
+    elif verdict == "fail":
+        errors.append(f"{name}: validation.md verdict is FAIL - route the ranked gaps to fix tasks, then re-verify (feature is not done)")
+    if verdict == "pass" and not EVIDENCE_RE.search(text):
+        errors.append(f"{name}: validation.md is PASS but cites no file:line evidence - evidence-or-zero not satisfied")
+    return errors
+
+
+def _resolve(root, feature):
+    base, dirs = _feature_dirs(root)
+    if not os.path.isdir(base):
+        print(f"validate_state: no {base} directory - nothing to check.")
+        return []
+    if feature:
+        fdir = feature if os.path.isdir(feature) else os.path.join(base, feature)
+        if not os.path.isdir(fdir):
+            print(f"validate_state: feature not found: {feature}", file=sys.stderr)
+            raise SystemExit(2)
+        return [(fdir, os.path.basename(fdir.rstrip("/")))]
+    if len(dirs) == 1:
+        return [(os.path.join(base, dirs[0]), dirs[0])]
+    if not dirs:
+        print("validate_state: no features under .specs/features/ - nothing to check.")
+        return []
+    # Cross-check mode: only features that appear complete.
+    picked = [(os.path.join(base, d), d) for d in dirs if _appears_complete(os.path.join(base, d))]
+    if not picked:
+        print("validate_state: no completed feature detected (all in progress) - nothing to gate.")
+    return picked
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="validate_state.py", description="Deterministic completion gate: a done feature must have a real PASS validation report.")
+    p.add_argument("feature", nargs="?", default=None, help="Feature dir or name (default: sole feature, else cross-check all completed)")
+    p.add_argument("--root", default=".", help="Project root containing .specs/ (default: current dir)")
+    args = p.parse_args(argv)
+    root = os.path.abspath(args.root)
+
+    targets = _resolve(root, args.feature)
+    all_errors = []
+    for fdir, name in targets:
+        all_errors += _check_feature(fdir, name)
+
+    for e in all_errors:
+        print(f"  ERROR {e}")
+    n = len(all_errors)
+    checked = ", ".join(name for _, name in targets) or "(none)"
+    print(f"\nvalidate_state: {n} error(s) across [{checked}]")
+    return 1 if n else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())