@luizsantiago/spec-guardrails 3.2.0 → 3.2.1

package/scripts/lessons.py

@@ -40,7 +40,18 @@ FEATURE_IN_PATH = re.compile(
     r"(?:^|/)features/(?P<name>[^/]+)/", re.IGNORECASE
 )
 
-STATUSES = ("candidate", "confirmed", "quarantined")
+STATUSES = (
+    "observed",
+    "repeated",
+    "candidate",
+    "approved",
+    "graduated",
+    "deprecated",
+    "quarantined",
+)
+LEGACY_CONFIRMED = "confirmed"
+GUIDANCE_STATUSES = frozenset({"approved", "graduated", LEGACY_CONFIRMED})
+PROMOTION_CHAIN = ("observed", "repeated", "candidate", "approved")
 
 
 def fail(message: str, code: int = EXIT_FAILED) -> int:
@@ -54,6 +65,30 @@ def ok(message: str) -> int:
     return EXIT_OK
 
 
+def normalize_status(raw: str | None) -> str:
+    value = str(raw or "").strip().lower()
+    if value == LEGACY_CONFIRMED:
+        return "approved"
+    return value
+
+
+def is_guidance_status(status: str) -> bool:
+    return normalize_status(status) in GUIDANCE_STATUSES
+
+
+def next_promotion_status(status: str) -> str | None:
+    normalized = normalize_status(status)
+    if normalized == LEGACY_CONFIRMED:
+        return "graduated"
+    try:
+        index = PROMOTION_CHAIN.index(normalized)
+    except ValueError:
+        return None
+    if index + 1 >= len(PROMOTION_CHAIN):
+        return None
+    return PROMOTION_CHAIN[index + 1]
+
+
 def normalize(text: str) -> str:
     """Casefold, strip accents and punctuation, collapse whitespace."""
 
@@ -173,32 +208,47 @@ def parse_iso_date(raw: str) -> date | None:
 
 
 def render_markdown(store: dict) -> str:
-    confirmed = [item for item in store["lessons"] if item.get("status") == "confirmed"]
+    guidance = [
+        item
+        for item in store["lessons"]
+        if is_guidance_status(str(item.get("status") or ""))
+        and normalize_status(str(item.get("status") or "")) != "graduated"
+    ]
+    graduated = [
+        item
+        for item in store["lessons"]
+        if normalize_status(str(item.get("status") or "")) == "graduated"
+    ]
     lines = [
         "# Lessons Learned",
         "",
         "Generated by `lessons.py` from `.specs/lessons.json`. Do not edit this file.",
-        "A clean PASS records nothing. Only **confirmed** lessons below are guidance.",
+        "A clean PASS records nothing. Only **approved** lessons below are guidance.",
+        "Graduated rules live in engineering standards — never auto-graduate.",
         "Inspect candidates with `python3 .specs/guardrails/scripts/lessons.py list --status all`.",
         "",
     ]
 
-    if not confirmed:
+    if not guidance:
         lines.append("- none yet")
-        lines.append("")
-        return "\n".join(lines)
-
-    for lesson in confirmed:
-        lines.append(f"### {lesson.get('id', '?')}: {lesson.get('title', '')}")
-        if lesson.get("trigger"):
-            lines.append(f"- **Trigger**: {lesson['trigger']}")
-        lines.append(f"- **Rule**: {lesson.get('rule', '')}")
-        features = ", ".join(lesson.get("features") or [])
-        if features:
-            lines.append(f"- **Features**: {features}")
-        lines.append(f"- **Source**: {lesson.get('source', '—')}")
-        lines.append("")
-
+    else:
+        for lesson in guidance:
+            lines.append(f"### {lesson.get('id', '?')}: {lesson.get('title', '')}")
+            if lesson.get("trigger"):
+                lines.append(f"- **Trigger**: {lesson['trigger']}")
+            lines.append(f"- **Rule**: {lesson.get('rule', '')}")
+            features = ", ".join(lesson.get("features") or [])
+            if features:
+                lines.append(f"- **Features**: {features}")
+            lines.append(f"- **Source**: {lesson.get('source', '—')}")
+            lines.append("")
+
+    if graduated:
+        lines.extend(["## Graduated", ""])
+        for lesson in graduated:
+            lines.append(f"- {lesson.get('id', '?')}: {lesson.get('title', '')}")
+
+    lines.append("")
     return "\n".join(lines)
 
 
@@ -271,13 +321,13 @@ def cmd_add(args: argparse.Namespace) -> int:
         existing["updated"] = now
         existing["source"] = source_raw
         if (
-            existing.get("status") == "candidate"
+            normalize_status(str(existing.get("status"))) == "candidate"
             and len(features) >= PROMOTE_AFTER_FEATURES
         ):
-            existing["status"] = "confirmed"
+            existing["status"] = "approved"
             save_store(store)
             return ok(
-                f"{existing['id']} promoted to confirmed "
+                f"{existing['id']} promoted to approved "
                 f"(seen in {len(features)} features)"
             )
 
@@ -306,13 +356,24 @@ def cmd_list(args: argparse.Namespace) -> int:
     if isinstance(store, int):
         return store
 
-    wanted = args.status or "confirmed"
+    wanted = args.status or "approved"
     if wanted == "all":
         rows = store["lessons"]
+    elif wanted == LEGACY_CONFIRMED:
+        rows = [
+            item
+            for item in store["lessons"]
+            if is_guidance_status(str(item.get("status") or ""))
+        ]
     elif wanted in STATUSES:
-        rows = [item for item in store["lessons"] if item.get("status") == wanted]
+        rows = [
+            item for item in store["lessons"] if normalize_status(item.get("status")) == wanted
+        ]
     else:
-        return fail(f"unknown status '{wanted}' - use {', '.join(STATUSES)} or all", EXIT_USAGE)
+        return fail(
+            f"unknown status '{wanted}' - use {', '.join(STATUSES)}, confirmed, or all",
+            EXIT_USAGE,
+        )
 
     print(f"[{GATE}] {len(rows)} {wanted} lesson(s)")
     for lesson in rows:
@@ -336,9 +397,9 @@ def cmd_penalize(args: argparse.Namespace) -> int:
     if not lesson:
         return fail(f"no such lesson: {lesson_id}")
 
-    if lesson.get("status") != "confirmed":
+    if normalize_status(str(lesson.get("status"))) not in {"approved", LEGACY_CONFIRMED}:
         return fail(
-            f"{lesson_id} is {lesson.get('status')} - only confirmed lessons can be penalized"
+            f"{lesson_id} is {lesson.get('status')} - only approved lessons can be penalized"
         )
 
     try:
@@ -392,18 +453,80 @@ def cmd_status(args: argparse.Namespace) -> int:
         return store
 
     counts = {status: 0 for status in STATUSES}
+    legacy_confirmed = 0
     for lesson in store["lessons"]:
-        status = lesson.get("status")
+        raw_status = str(lesson.get("status") or "")
+        if raw_status == LEGACY_CONFIRMED:
+            legacy_confirmed += 1
+            continue
+        status = normalize_status(raw_status)
         if status in counts:
             counts[status] += 1
 
-    total = sum(counts.values())
+    total = len(store["lessons"])
     print(f"[{GATE}] {total} lesson(s) in {STORE_PATH}")
     for status in STATUSES:
         print(f"  {status:<12} {counts[status]}")
+    if legacy_confirmed:
+        print(f"  {'confirmed (legacy)':<12} {legacy_confirmed}")
     return EXIT_OK
 
 
+def cmd_promote(args: argparse.Namespace) -> int:
+    store = load_store()
+    if isinstance(store, int):
+        return store
+
+    lesson_id = (args.id or "").strip().upper()
+    lesson = next((item for item in store["lessons"] if item.get("id") == lesson_id), None)
+    if not lesson:
+        return fail(f"no such lesson: {lesson_id}")
+
+    next_status = next_promotion_status(str(lesson.get("status") or ""))
+    if not next_status:
+        return fail(
+            f"{lesson_id} is {lesson.get('status')} - no manual promotion step available"
+        )
+
+    lesson["status"] = next_status
+    lesson["updated"] = today_iso()
+    save_store(store)
+    return ok(f"{lesson_id} promoted to {next_status}")
+
+
+def cmd_graduate(args: argparse.Namespace) -> int:
+    source = validate_source(args.source)
+    if isinstance(source, int):
+        return source
+
+    store = load_store()
+    if isinstance(store, int):
+        return store
+
+    lesson_id = (args.id or "").strip().upper()
+    lesson = next((item for item in store["lessons"] if item.get("id") == lesson_id), None)
+    if not lesson:
+        return fail(f"no such lesson: {lesson_id}")
+
+    status = normalize_status(str(lesson.get("status")))
+    if status not in {"approved", LEGACY_CONFIRMED}:
+        return fail(
+            f"{lesson_id} is {lesson.get('status')} - only approved lessons can graduate"
+        )
+
+    evidence = (args.evidence or "").strip()
+    if not evidence:
+        return fail("--evidence is required - graduation must cite why this is a house rule")
+
+    lesson["status"] = "graduated"
+    lesson["graduated_from"] = str(lesson.get("source") or "")
+    lesson["graduation_evidence"] = evidence
+    lesson["source"] = source[1]
+    lesson["updated"] = today_iso()
+    save_store(store)
+    return ok(f"{lesson_id} graduated — stop loading as active guidance")
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description="Manage grounded lessons")
     sub = parser.add_subparsers(dest="command")
@@ -416,10 +539,20 @@ def build_parser() -> argparse.ArgumentParser:
     add.add_argument("--feature", default="")
     add.set_defaults(func=cmd_add)
 
-    listing = sub.add_parser("list", help="list lessons (default: confirmed)")
-    listing.add_argument("--status", default="confirmed")
+    listing = sub.add_parser("list", help="list lessons (default: approved)")
+    listing.add_argument("--status", default="approved")
     listing.set_defaults(func=cmd_list)
 
+    promote = sub.add_parser("promote", help="advance one step in the graduation lifecycle")
+    promote.add_argument("--id", required=True)
+    promote.set_defaults(func=cmd_promote)
+
+    graduate = sub.add_parser("graduate", help="graduate an approved lesson into a house rule")
+    graduate.add_argument("--id", required=True)
+    graduate.add_argument("--source", required=True, help="path to validation.md evidence")
+    graduate.add_argument("--evidence", required=True, help="why this rule is stable enough to graduate")
+    graduate.set_defaults(func=cmd_graduate)
+
     penalize = sub.add_parser("penalize", help="mark a confirmed lesson that failed to prevent a repeat")
     penalize.add_argument("--id", required=True)
     penalize.add_argument("--source", required=True)

package/scripts/memory_index.py

@@ -0,0 +1,325 @@
+#!/usr/bin/env python3
+"""Rebuild the SQLite memory index from `.specs/` markdown artifacts.
+
+Source of truth remains markdown under `.specs/`. The database is a derived index.
+
+    python3 memory_index.py rebuild
+    python3 memory_index.py rebuild --json
+
+Exit codes: 0 ok, 1 failure, 2 usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sqlite3
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from _common import EXIT_FAILED, EXIT_OK, EXIT_USAGE, requirement_ids
+
+GATE = "memory-index"
+SPECS_DIR = Path(".specs")
+FEATURES_DIR = SPECS_DIR / "features"
+MEMORY_DIR = SPECS_DIR / "memory"
+DB_PATH = MEMORY_DIR / "memory.db"
+
+TASK_HEADING = re.compile(
+    r"^#{2,6}\s*(?P<id>T\d{1,6})\s*[:\-–]?\s*(?P<title>.*)$",
+    re.MULTILINE | re.IGNORECASE,
+)
+TASK_FIELD = re.compile(
+    r"^\s*[-*]?\s*\*{0,2}(?P<key>[A-Za-z][A-Za-z ]+?)\*{0,2}\s*:\s*(?P<value>.+?)\s*$",
+    re.MULTILINE,
+)
+REQ_REF = re.compile(r"\b[A-Z][A-Z0-9]{1,9}-\d{2,4}\b")
+
+
+def fail(message: str, code: int = EXIT_FAILED) -> int:
+    print(f"[{GATE}] FAIL - {DB_PATH}")
+    print(f"  error   {message}")
+    return code
+
+
+def ok(message: str) -> int:
+    print(f"[{GATE}] PASS - {message}")
+    return EXIT_OK
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+def init_schema(conn: sqlite3.Connection) -> None:
+    conn.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS entities (
+            id TEXT PRIMARY KEY,
+            kind TEXT NOT NULL,
+            label TEXT NOT NULL,
+            source_path TEXT,
+            updated_at TEXT NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS relations (
+            from_id TEXT NOT NULL,
+            to_id TEXT NOT NULL,
+            kind TEXT NOT NULL,
+            PRIMARY KEY (from_id, to_id, kind)
+        );
+        CREATE VIRTUAL TABLE IF NOT EXISTS entity_fts USING fts5(
+            id UNINDEXED,
+            kind,
+            label,
+            source_path,
+            tokenize='porter'
+        );
+        """
+    )
+
+
+def upsert_entity(
+    conn: sqlite3.Connection,
+    entity_id: str,
+    kind: str,
+    label: str,
+    source_path: str | None,
+    now: str,
+) -> None:
+    conn.execute(
+        """
+        INSERT INTO entities (id, kind, label, source_path, updated_at)
+        VALUES (?, ?, ?, ?, ?)
+        ON CONFLICT(id) DO UPDATE SET
+            kind=excluded.kind,
+            label=excluded.label,
+            source_path=excluded.source_path,
+            updated_at=excluded.updated_at
+        """,
+        (entity_id, kind, label, source_path, now),
+    )
+    conn.execute("DELETE FROM entity_fts WHERE id = ?", (entity_id,))
+    conn.execute(
+        "INSERT INTO entity_fts (id, kind, label, source_path) VALUES (?, ?, ?, ?)",
+        (entity_id, kind, label, source_path or ""),
+    )
+
+
+def upsert_relation(conn: sqlite3.Connection, from_id: str, to_id: str, kind: str) -> None:
+    conn.execute(
+        """
+        INSERT OR IGNORE INTO relations (from_id, to_id, kind)
+        VALUES (?, ?, ?)
+        """,
+        (from_id, to_id, kind),
+    )
+
+
+def task_requirement_ids(tasks_text: str) -> dict[str, set[str]]:
+    current_task: str | None = None
+    mapping: dict[str, set[str]] = {}
+
+    for line in tasks_text.splitlines():
+        heading = TASK_HEADING.match(line)
+        if heading:
+            current_task = heading.group("id").upper()
+            mapping.setdefault(current_task, set())
+            continue
+
+        if not current_task:
+            continue
+
+        field = TASK_FIELD.match(line)
+        if not field or field.group("key").strip().lower() != "requirement":
+            continue
+
+        mapping[current_task].update(REQ_REF.findall(field.group("value")))
+
+    return mapping
+
+
+def task_file_paths(tasks_text: str) -> dict[str, set[str]]:
+    current_task: str | None = None
+    mapping: dict[str, set[str]] = {}
+
+    for line in tasks_text.splitlines():
+        heading = TASK_HEADING.match(line)
+        if heading:
+            current_task = heading.group("id").upper()
+            mapping.setdefault(current_task, set())
+            continue
+
+        if not current_task:
+            continue
+
+        field = TASK_FIELD.match(line)
+        if not field or field.group("key").strip().lower() != "files":
+            continue
+
+        raw = field.group("value").strip()
+        if raw.lower() in {"—", "-", "none", "n/a"}:
+            continue
+
+        for part in re.split(r"[,;]", raw):
+            cleaned = part.strip().strip("`")
+            if cleaned:
+                mapping[current_task].add(cleaned)
+
+    return mapping
+
+
+def index_lessons(conn: sqlite3.Connection, now: str) -> int:
+    lessons_path = SPECS_DIR / "lessons.json"
+    if not lessons_path.is_file():
+        return 0
+
+    payload = json.loads(lessons_path.read_text(encoding="utf-8"))
+    count = 0
+    for lesson in payload.get("lessons") or []:
+        lesson_id = str(lesson.get("id") or "").strip()
+        if not lesson_id:
+            continue
+        upsert_entity(
+            conn,
+            lesson_id,
+            "lesson",
+            str(lesson.get("title") or lesson_id),
+            str(lesson.get("source") or ""),
+            now,
+        )
+        count += 1
+    return count
+
+
+def rebuild(json_output: bool = False) -> int:
+    if not SPECS_DIR.is_dir():
+        return fail(".specs/ not found — run install first")
+
+    MEMORY_DIR.mkdir(parents=True, exist_ok=True)
+    now = utc_now()
+
+    conn = sqlite3.connect(DB_PATH)
+    try:
+        init_schema(conn)
+        conn.execute("DELETE FROM relations")
+        conn.execute("DELETE FROM entities")
+        conn.execute("DELETE FROM entity_fts")
+
+        entity_count = 0
+        relation_count = 0
+
+        if FEATURES_DIR.is_dir():
+            for feature_dir in sorted(FEATURES_DIR.iterdir()):
+                if not feature_dir.is_dir():
+                    continue
+
+                feature_id = feature_dir.name
+                upsert_entity(
+                    conn,
+                    feature_id,
+                    "feature",
+                    feature_id,
+                    str(feature_dir / "spec.md"),
+                    now,
+                )
+                entity_count += 1
+
+                spec_path = feature_dir / "spec.md"
+                if spec_path.is_file():
+                    spec_text = spec_path.read_text(encoding="utf-8")
+                    for req_id in requirement_ids(spec_text):
+                        upsert_entity(
+                            conn,
+                            req_id,
+                            "requirement",
+                            req_id,
+                            str(spec_path),
+                            now,
+                        )
+                        entity_count += 1
+                        upsert_relation(conn, feature_id, req_id, "contains")
+                        relation_count += 1
+
+                tasks_path = feature_dir / "tasks.md"
+                if tasks_path.is_file():
+                    tasks_text = tasks_path.read_text(encoding="utf-8")
+                    for match in TASK_HEADING.finditer(tasks_text):
+                        task_id = match.group("id").upper()
+                        title = match.group("title").strip() or task_id
+                        upsert_entity(
+                            conn,
+                            task_id,
+                            "task",
+                            title,
+                            str(tasks_path),
+                            now,
+                        )
+                        entity_count += 1
+                        upsert_relation(conn, feature_id, task_id, "contains")
+                        relation_count += 1
+
+                    for task_id, req_ids in task_requirement_ids(tasks_text).items():
+                        for req_id in req_ids:
+                            upsert_relation(conn, task_id, req_id, "implements")
+                            relation_count += 1
+
+                    for task_id, files in task_file_paths(tasks_text).items():
+                        for file_path in files:
+                            file_entity = f"file:{file_path}"
+                            upsert_entity(
+                                conn,
+                                file_entity,
+                                "file",
+                                file_path,
+                                str(tasks_path),
+                                now,
+                            )
+                            entity_count += 1
+                            upsert_relation(conn, task_id, file_entity, "touches")
+                            relation_count += 1
+
+        entity_count += index_lessons(conn, now)
+        conn.commit()
+
+        summary = {
+            "database": str(DB_PATH),
+            "entities": entity_count,
+            "relations": relation_count,
+            "updated_at": now,
+        }
+
+        if json_output:
+            print(json.dumps(summary, indent=2))
+        else:
+            return ok(
+                f"indexed {entity_count} entities and {relation_count} relations -> {DB_PATH}"
+            )
+        return EXIT_OK
+    finally:
+        conn.close()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Rebuild SQLite memory index from .specs/")
+    sub = parser.add_subparsers(dest="command")
+
+    rebuild_cmd = sub.add_parser("rebuild", help="rebuild index from markdown artifacts")
+    rebuild_cmd.add_argument("--json", action="store_true")
+    rebuild_cmd.set_defaults(func=lambda args: rebuild(json_output=args.json))
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help()
+        return EXIT_USAGE
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())