@luizsantiago/spec-guardrails 3.2.0 → 3.2.1

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>` |
+| 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,21 @@ 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.
+- **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/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