@massa-ai/cursor-plugin 1.21.0 → 1.22.0

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

@@ -1,272 +0,0 @@
-#!/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

@@ -1,183 +0,0 @@
-#!/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())