@luizsantiago/spec-guardrails 3.2.0 → 3.3.0

package/lib/install.js

@@ -13,8 +13,6 @@ import {
   resolveAssetOverride,
 } from "./constants.js";
 import { installPlatformAdapters } from "./adapters.js";
-import { injectClaudeMd } from "./claude-md.js";
-import { injectCursorRules } from "./cursorrules.js";
 import { ensureDir, readFileSafe, writeFileIfMissing } from "./fs-utils.js";
 import { hasPython } from "./gates.js";
 import { initGuardrailsMemory } from "./memory.js";
@@ -117,8 +115,6 @@ export async function install(options = {}) {
   }
 
   log("🔗 Installing platform adapters...");
-  await injectCursorRules(cwd);
-  await injectClaudeMd(cwd);
   await installPlatformAdapters(cwd);
   log("✅ Adapters → .cursorrules, CLAUDE.md, copilot-instructions.md, AGENTS.md, .codex/AGENTS.md");
 

package/lib/memory-index.js

@@ -0,0 +1,59 @@
+import path from "node:path";
+
+import { GUARDRAILS_SCRIPTS_DIR } from "./constants.js";
+import { runGuardrailsScript } from "./gates.js";
+
+export const MEMORY_DB_PATH = ".specs/memory/memory.db";
+
+/**
+ * Rebuild the SQLite memory index from `.specs/` markdown artifacts.
+ *
+ * @param {{ cwd?: string }} [options]
+ * @returns {Promise<number>} exit code
+ */
+export async function rebuildMemoryIndex(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  return runGuardrailsScript("memory-index", ["rebuild"], { cwd });
+}
+
+/**
+ * Query the knowledge graph for a bounded context package.
+ *
+ * @param {{ from: string, depth?: number, json?: boolean, cwd?: string }} options
+ * @returns {Promise<number>} exit code
+ */
+export async function queryMemory(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const args = ["--from", options.from];
+  if (options.depth !== undefined) {
+    args.push("--depth", String(options.depth));
+  }
+  if (options.json) {
+    args.push("--json");
+  }
+  return runGuardrailsScript("memory-query", args, { cwd });
+}
+
+/**
+ * @param {string} [cwd]
+ * @returns {string}
+ */
+export function memoryDbPath(cwd = process.cwd()) {
+  return path.join(cwd, MEMORY_DB_PATH);
+}
+
+/**
+ * @returns {string}
+ */
+export function memoryDbRelativePath() {
+  return MEMORY_DB_PATH;
+}
+
+/**
+ * Relative scripts directory for memory tooling diagnostics.
+ *
+ * @returns {string}
+ */
+export function memoryScriptsDir() {
+  return GUARDRAILS_SCRIPTS_DIR;
+}

package/lib/workspace-isolation.js

@@ -137,6 +137,39 @@ export async function cleanupWorkspaces(cwd, { featureId, taskIds, force = false
   return results;
 }
 
+/**
+ * @param {string} cwd
+ * @param {string} featureId
+ * @returns {Promise<Array<{ taskId: string, path: string }>>}
+ */
+export async function listWorkspaces(cwd, featureId) {
+  const paths = await listWorkspacePaths(cwd, featureId);
+  return paths.map((wtPath) => ({
+    taskId: path.basename(wtPath),
+    path: wtPath,
+  }));
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof listWorkspaces>>} workspaces
+ * @param {{ json?: boolean, featureId?: string }} [options]
+ */
+export function formatWorkspaceList(workspaces, options = {}) {
+  if (options.json) {
+    return JSON.stringify({ feature: options.featureId, workspaces }, null, 2);
+  }
+
+  const lines = ["Workspace list:"];
+  if (!workspaces.length) {
+    lines.push("  (none)");
+  } else {
+    for (const item of workspaces) {
+      lines.push(`  ${item.taskId}: ${item.path}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
 /**
  * @param {ReturnType<typeof prepareWorkspaces> extends Promise<infer T> ? T : never} results
  * @param {{ json?: boolean }} [options]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luizsantiago/spec-guardrails",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Keep AI coding agents honest — specify the work, prove each step, verify independently. Process mode (Node) for flexibility; Brakes mode (Node + Python) for structural gates and a Guarantees matrix. Progressive loading, independent verify — any AI agent.",
   "type": "module",
   "bin": {
@@ -12,7 +12,7 @@
   "scripts": {
     "guardrails": "node index.js",
     "test": "npm run test:node && npm run test:gates",
-    "test:node": "node --test test/install.test.js test/test_feature_init.test.js test/test_config.test.js test/test_archive.test.js test/test_delta_merge.test.js test/test_presets.test.js test/test_brownfield.test.js test/test_doctor.test.js test/test_token_cost.test.js test/test_next_steps.test.js test/test_classify_change.test.js test/test_feature_status.test.js test/test_agent_contract.test.js test/test_gates_python.test.js test/test_specs_utils.test.js test/test_validation_verdict.test.js test/test_execution_policy.test.js test/test_workspace_isolation.test.js",
+    "test:node": "node --test test/install.test.js test/test_feature_init.test.js test/test_config.test.js test/test_archive.test.js test/test_delta_merge.test.js test/test_presets.test.js test/test_brownfield.test.js test/test_doctor.test.js test/test_token_cost.test.js test/test_next_steps.test.js test/test_classify_change.test.js test/test_feature_status.test.js test/test_agent_contract.test.js test/test_gates_python.test.js test/test_specs_utils.test.js test/test_validation_verdict.test.js test/test_execution_policy.test.js test/test_workspace_isolation.test.js test/test_adapter_registry.test.js",
     "test:gates": "node test/run-gate-tests.mjs",
     "prepublishOnly": "npm test"
   },

package/rules/engineering-baseline.mdc

@@ -47,8 +47,10 @@ Gates live in `.specs/guardrails/scripts/` (Python 3). **The agent runs them** a
 | `feature-init "…"` | Optional — or ask the agent to `/specify` |
 | `project-init` | Optional — brownfield repo with existing code |
 | `doctor` | Install looks broken |
+| `workspace-list <feature>` | Inspect parallel worktrees before cleanup |
+| `execution-policy status` | Check budgets and scope before expanding Execute |
 
-Everything else (`validate-spec`, `validate-tasks`, `check-commit`, …) is normally run **by the agent**, not memorized from this file. Full list: `npx @luizsantiago/spec-guardrails --help` or `.specs/GETTING_STARTED.md`.
+Everything else (`validate-spec`, `validate-tasks`, `check-commit`, `workspace-prepare`, `execution-policy check-path`, …) is normally run **by the agent**, not memorized from this file. Full list: `npx @luizsantiago/spec-guardrails --help` or `.specs/GETTING_STARTED.md`.
 
 Non-zero gate exit = STOP. Without Python, the agent performs the same checks manually.
 

package/scripts/analyze_artifacts.py

@@ -46,6 +46,15 @@ STATE_FEATURE = re.compile(
     r"^\s*-\s*Feature:\s*(.+)$",
     re.IGNORECASE | re.MULTILINE,
 )
+TASK_HEADING = re.compile(
+    r"^#{2,6}\s*(?P<id>T\d{1,6})\s*[:\-–]?\s*(?P<title>.*)$",
+    re.MULTILINE | re.IGNORECASE,
+)
+VERIFY_HINT = re.compile(
+    r"\b(test strategy|verification|validate\.md|/verify|acceptance test)\b",
+    re.IGNORECASE,
+)
+MEDIUM_TASK_FLOOR = 5
 
 
 def git_branch(root: Path) -> str | None:
@@ -121,6 +130,20 @@ def build_report(feature_dir: Path, root: Path) -> Report:
     else:
         report.warn("tasks.md missing or empty — task coverage checks skipped")
 
+    task_count = len(TASK_HEADING.findall(tasks_text or ""))
+    medium_plus = task_count >= MEDIUM_TASK_FLOOR
+
+    if medium_plus and design_text is None:
+        report.warn(
+            f"{task_count} tasks — design.md recommended for Medium+ features"
+        )
+
+    plan_text = "\n".join(filter(None, [spec_text, design_text]))
+    if medium_plus and plan_text and not VERIFY_HINT.search(plan_text):
+        report.warn(
+            "no verification or test strategy mention in spec/design — add verify plan before Execute"
+        )
+
     if design_text is not None and tasks_text:
         visible_design = visible_markdown(design_text).strip()
         if len(visible_design.splitlines()) < 5:

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)