@luizsantiago/spec-guardrails 3.2.0 → 3.3.0

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())

package/scripts/memory_query.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""Bounded knowledge-graph traversal over the SQLite memory index.
+
+    python3 memory_query.py --from T1 --depth 2
+    python3 memory_query.py --from REQ-001 --depth 1 --json
+
+Exit codes: 0 ok, 1 failure, 2 usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sqlite3
+import sys
+from collections import deque
+from pathlib import Path
+
+from _common import EXIT_FAILED, EXIT_OK, EXIT_USAGE
+
+GATE = "memory-query"
+DB_PATH = Path(".specs/memory/memory.db")
+DEFAULT_DEPTH = 2
+MAX_DEPTH = 5
+
+
+def fail(message: str, code: int = EXIT_FAILED) -> int:
+    print(f"[{GATE}] FAIL - {DB_PATH}")
+    print(f"  error   {message}")
+    return code
+
+
+def normalize_entity_id(raw: str) -> str:
+    value = raw.strip()
+    if value.upper().startswith("T") and value[1:].isdigit():
+        return f"T{int(value[1:])}"
+    return value
+
+
+def fetch_entity(conn: sqlite3.Connection, entity_id: str) -> dict | None:
+    row = conn.execute(
+        "SELECT id, kind, label, source_path, updated_at FROM entities WHERE id = ?",
+        (entity_id,),
+    ).fetchone()
+    if not row:
+        return None
+    return {
+        "id": row[0],
+        "kind": row[1],
+        "label": row[2],
+        "source_path": row[3],
+        "updated_at": row[4],
+    }
+
+
+def fetch_neighbors(conn: sqlite3.Connection, entity_id: str) -> list[dict]:
+    rows = conn.execute(
+        """
+        SELECT r.kind, e.id, e.kind, e.label, e.source_path
+        FROM relations r
+        JOIN entities e ON e.id = r.to_id
+        WHERE r.from_id = ?
+        UNION
+        SELECT r.kind, e.id, e.kind, e.label, e.source_path
+        FROM relations r
+        JOIN entities e ON e.id = r.from_id
+        WHERE r.to_id = ?
+        """,
+        (entity_id, entity_id),
+    ).fetchall()
+
+    neighbors: list[dict] = []
+    for kind, nid, nkind, label, source_path in rows:
+        neighbors.append(
+            {
+                "relation": kind,
+                "entity": {
+                    "id": nid,
+                    "kind": nkind,
+                    "label": label,
+                    "source_path": source_path,
+                },
+            }
+        )
+    return neighbors
+
+
+def traverse(from_id: str, depth: int) -> dict:
+    if not DB_PATH.is_file():
+        raise FileNotFoundError(
+            f"{DB_PATH} not found — run `memory-index rebuild` after install"
+        )
+
+    conn = sqlite3.connect(DB_PATH)
+    try:
+        root_id = normalize_entity_id(from_id)
+        root = fetch_entity(conn, root_id)
+        if not root:
+            raise LookupError(f"entity not found: {root_id}")
+
+        visited: set[str] = {root_id}
+        edges: list[dict] = []
+        entities: dict[str, dict] = {root_id: root}
+        queue: deque[tuple[str, int]] = deque([(root_id, 0)])
+
+        while queue:
+            current_id, current_depth = queue.popleft()
+            if current_depth >= depth:
+                continue
+
+            for neighbor in fetch_neighbors(conn, current_id):
+                target = neighbor["entity"]
+                target_id = target["id"]
+                edges.append(
+                    {
+                        "from": current_id,
+                        "to": target_id,
+                        "kind": neighbor["relation"],
+                    }
+                )
+                if target_id not in entities:
+                    entities[target_id] = target
+                if target_id not in visited:
+                    visited.add(target_id)
+                    queue.append((target_id, current_depth + 1))
+
+        return {
+            "from": root_id,
+            "depth": depth,
+            "entities": list(entities.values()),
+            "relations": edges,
+        }
+    finally:
+        conn.close()
+
+
+def cmd_query(args: argparse.Namespace) -> int:
+    depth = args.depth if args.depth is not None else DEFAULT_DEPTH
+    if depth < 0 or depth > MAX_DEPTH:
+        return fail(f"--depth must be between 0 and {MAX_DEPTH}", EXIT_USAGE)
+
+    try:
+        package = traverse(args.from_id, depth)
+    except FileNotFoundError as err:
+        return fail(str(err))
+    except LookupError as err:
+        return fail(str(err))
+
+    if args.json:
+        print(json.dumps(package, indent=2))
+    else:
+        print(f"[{GATE}] context package from {package['from']} (depth {package['depth']})")
+        print(f"  entities: {len(package['entities'])}")
+        print(f"  relations: {len(package['relations'])}")
+        for entity in package["entities"]:
+            print(f"  - {entity['id']} ({entity['kind']}): {entity['label']}")
+
+    return EXIT_OK
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Query the SQLite knowledge graph")
+    parser.add_argument("--from", dest="from_id", required=True, help="root entity id")
+    parser.add_argument("--depth", type=int, default=DEFAULT_DEPTH)
+    parser.add_argument("--json", action="store_true")
+    parser.set_defaults(func=cmd_query)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/validate_spec.py

@@ -311,6 +311,7 @@ def build_report(target: str, text: str) -> Report:
             "MODIFIED",
         )
         validate_removed_section(report, visible)
+        validate_out_of_scope(report, visible)
     else:
         for section in REQUIRED_SECTIONS:
             if has_section(visible, section):

package/skills/agent-architecture.md

@@ -46,6 +46,10 @@ Structural gates run **before** owner review, so they cannot drift when the mode
 | Before approving tasks | `python3 .specs/guardrails/scripts/analyze_artifacts.py [feature]` |
 | Before presenting tasks for approval | `python3 .specs/guardrails/scripts/validate_tasks.py [feature]` |
 | Before Execute waves (3+ tasks) | `npx @luizsantiago/spec-guardrails loop-plan [feature]` |
+| Parallel wave (2+ tasks, disjoint Files) | `npx @luizsantiago/spec-guardrails workspace-prepare [feature] --tasks T1,T2` |
+| After parallel wave merge | `npx @luizsantiago/spec-guardrails workspace-cleanup [feature] --force` |
+| Before editing paths outside task Files | `npx @luizsantiago/spec-guardrails execution-policy check-path <path> [--op write]` |
+| On gate retry (Execute playbook) | `npx @luizsantiago/spec-guardrails execution-policy record-retry Tn` |
 | On each commit | `python3 .specs/guardrails/scripts/check_commit.py --message "<message>"` |
 | Before declaring a feature done | `python3 .specs/guardrails/scripts/validate_state.py [feature]` |
 | Traceability (Medium+ features) | `python3 .specs/guardrails/scripts/validate_traceability.py [feature]` |

package/skills/git-handoff.md

@@ -62,6 +62,22 @@ node_modules/
 
 Follow `engineering-standards.md` — separate commits for code vs docs when possible.
 
+## Execution policy (scope and budgets)
+
+When `.specs/config.yaml` defines `budget`, `scope`, or `escalation`, consult policy before expanding edits:
+
+```bash
+npx @luizsantiago/spec-guardrails execution-policy status
+npx @luizsantiago/spec-guardrails execution-policy check-path src/auth.ts
+```
+
+- **Scope:** denied paths block with exit 1; allowed_paths (when set) restrict edits to listed globs.
+- **Intent/effect:** pass `--op read|write|delete` to `check-path`; configure `effects.deny_*` and `effects.warn_*` globs per operation in `.specs/config.yaml`.
+- **Retries:** after a task gate failure, run `execution-policy record-retry Tn`; stop at `max_retries_per_task` (default 3) and escalate per the Execute playbook — do not bypass with `--no-verify`.
+- **Agent runs:** orchestrators may call `execution-policy record-run` when dispatching sub-agents; stop when budgets exhaust.
+
+Policy is soft-enforced via CLI + skills — not an OS sandbox. Escalation defaults: scope expansion → human review; budget exhaustion → stop.
+
 ## Git Blast Radius (Tiers)
 
 Structural gates enforce artifact quality. Git tiers enforce **what leaves the machine**.

package/skills/references/implement.md

@@ -41,10 +41,13 @@ npx @luizsantiago/spec-guardrails workspace-cleanup [feature] --tasks T1,T2 --fo
 7. Consult execution policy before touching files outside the task list:
 
 ```bash
-npx @luizsantiago/spec-guardrails execution-policy check-path src/auth.ts
+npx @luizsantiago/spec-guardrails execution-policy check-path src/auth.ts --op write
+npx @luizsantiago/spec-guardrails execution-policy check-path README.md --op read
 npx @luizsantiago/spec-guardrails execution-policy status
 ```
 
+Declare the intended operation (`read`, `write`, or `delete`). When `--op` is omitted, the CLI infers `read` for common doc/config extensions and `write` otherwise. Effect rules in `.specs/config.yaml` (`effects.deny_*`, `effects.warn_*`) apply after scope checks.
+
 Record gate retries with `execution-policy record-retry T1` when a task fails its gate (respects `max_retries_per_task` in `.specs/config.yaml`).
 
 8. When `loop-plan` shows a **parallel group** (2+ tasks), offer sub-agent dispatch per `task-graph-engineering.md` and `sub-agents.md`. Offer and wait; never auto-spawn. Large features (roughly 8+ tasks total) also warrant batching across waves.

package/skills/references/lessons.md

@@ -1,18 +1,20 @@
 # Lessons
 
-How to record, promote, and load grounded lessons. The engine owns the files; this reference owns the judgment.
+How to record, promote, graduate, and load grounded lessons. The engine owns the files; this reference owns the judgment.
 
 ## When to Use
 
 - The last step of `/verify` when the verdict is FAIL for a grounded reason
-- The first step of `/specify` and `/plan`, loading only confirmed lessons
-- After a confirmed lesson was loaded and the same failure still happened (`penalize`)
+- The first step of `/specify` and `/plan`, loading only approved lessons
+- After a approved lesson was loaded and the same failure still happened (`penalize`)
+- When a stable approved rule should become an engineering standard (`graduate` — human only)
 
 ## When NOT to Use
 
 - A clean PASS — record nothing
 - A preference, a style nit, or anything not evidenced in `validation.md`
 - Hand-editing `.specs/LESSONS.md` or `.specs/lessons.json`
+- **Auto-graduation** — agents must never graduate without explicit human approval
 
 ## Files
 
@@ -20,7 +22,7 @@ How to record, promote, and load grounded lessons. The engine owns the files; th
 | --- | --- | --- |
 | `.specs/lessons.json` | `lessons.py` | Canonical store |
 | `.specs/LESSONS.md` | `lessons.py` | Rendered playbook — read, never write |
-| `.specs/guardrails/scripts/lessons.py` | Harness | `add`, `list`, `penalize`, `prune`, `status` |
+| `.specs/guardrails/scripts/lessons.py` | Harness | `add`, `list`, `promote`, `graduate`, `penalize`, `prune`, `status` |
 
 ## How to Phrase
 
@@ -42,25 +44,29 @@ Titles and rules are deduped after normalization (casefold, accents stripped, pu
 
 ```
 FAIL with evidence → add (candidate)
-candidate seen in 2 distinct features → confirmed (guidance)
-confirmed loaded but the same failure recurs → penalize
+observed → repeated → candidate → approved → graduated → deprecated
+candidate seen in 2 distinct features → approved (automatic)
+approved loaded but the same failure recurs → penalize
 2 penalties → quarantined (stop loading)
 candidate idle 90 days → prune
+graduate (human) → approved → graduated with --evidence + validation.md
 ```
 
-Same-feature recurrence does not promote. One noisy feature must not turn a guess into a house rule.
+Same-feature recurrence does not promote. One noisy feature must not turn a guess into a house rule. **Never auto-graduate** — use `graduate` only after human review.
+
+Manual promotion (`promote --id L-001`) advances one step along `observed → repeated → candidate → approved` when corroboration is incomplete.
 
 ## When to Load
 
 At the start of Specify and Design:
 
 ```bash
-python3 .specs/guardrails/scripts/lessons.py list --status confirmed
+python3 .specs/guardrails/scripts/lessons.py list --status approved
 ```
 
-Apply every confirmed rule that matches this work. Candidates are not guidance — they live in `lessons.json` until a second feature corroborates them.
+Apply every approved rule that matches this work. Candidates are not guidance — they live in `lessons.json` until a second feature corroborates them or a human promotes them.
 
-If a confirmed lesson was in the working set and the same gap still appears in `/verify`, penalize it with the new `validation.md` as `--source`. Two penalties quarantine it.
+If an approved lesson was in the working set and the same gap still appears in `/verify`, penalize it with the new `validation.md` as `--source`. Two penalties quarantine it.
 
 ## Degraded mode
 

package/templates/config.yaml.example

@@ -39,6 +39,16 @@ escalation:
   on_budget_exhaustion: stop
   on_policy_violation: block
 
+# Intent/effect rules (optional — pair with check-path --op read|write|delete)
+effects:
+  deny_delete:
+    - "**/.git/**"
+  deny_write: []
+  deny_read: []
+  warn_write: []
+  warn_read: []
+  warn_delete: []
+
 # Project-specific overrides (appended on top of preset + rules above):
 # overrides:
 #   rules: