@luizsantiago/spec-guardrails 3.1.10 → 3.1.11

package/README.md

@@ -41,6 +41,12 @@ npx @luizsantiago/spec-guardrails install
 
 Re-run `install` anytime to refresh skills; your `.specs/` decisions and `STATE.md` are kept.
 
+### Optional Atlas companions (Lego)
+
+Spec Guardrails is a **complete product alone**. Optional **Atlas** packages add domain specialization (Path Domains, catalogs). The first is [**Tech Atlas**](https://github.com/luizssantiago92/tech-atlas) (`@luizsantiago/tech-atlas`) — tech engineering context routing.
+
+When paired, install Guardrails first, then the Atlas. Re-running Guardrails `install` **preserves** companion assets: Atlas skills/catalog, `.specs/atlas/`, mirrored `validate_layer_routing.py`, and `.specs/desks/` if present. Contract: [Companion: Tech Atlas](docs/guide/Companion-tech-atlas.md).
+
 | Need | Command |
 | --- | --- |
 | First time / upgrade | `install` |

package/index.js

@@ -50,6 +50,8 @@ Commands:
     [--json]                         Machine-readable output
   phase-context <phase>              Print .specs/config.yaml context + rules for a phase
   doctor [path]                      Audit guardrails readiness (score + next actions)
+                                      When Atlas companions are installed, also probes their
+                                      gates, rules, and PROJECT.md registry via INDEX.json
     [--json]                         Machine-readable output
     [--no-suggest]                   Hide per-check remediation hints
   validate-spec [spec.md|feature]    Closure gate for a feature spec

package/lib/companion-doctor.js

@@ -0,0 +1,140 @@
+import path from "node:path";
+
+import { GUARDRAILS_SCRIPTS_DIR } from "./constants.js";
+import {
+  listInstalledCompanions,
+  readCompanionsIndex,
+} from "./companions.js";
+import { readFileSafe } from "./fs-utils.js";
+
+/**
+ * @typedef {import("./doctor.js").DoctorCheck} DoctorCheck
+ */
+
+/**
+ * @param {string} cwd
+ * @param {string} relativePath
+ * @returns {Promise<boolean>}
+ */
+async function pathExists(cwd, relativePath) {
+  try {
+    const { access } = await import("node:fs/promises");
+    await access(path.join(cwd, relativePath));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Filesystem probes for installed Atlas companions (no Atlas CLI spawn).
+ * Used by Guardrails doctor when `.specs/companions/INDEX.json` exists.
+ *
+ * @param {string} cwd
+ * @returns {Promise<{
+ *   paired: boolean,
+ *   companions: import("./companions.js").CompanionIndexEntry[],
+ *   checks: DoctorCheck[],
+ * }>}
+ */
+export async function runCompanionDoctorChecks(cwd) {
+  const index = await readCompanionsIndex(cwd);
+  const companions = await listInstalledCompanions(cwd);
+  /** @type {DoctorCheck[]} */
+  const checks = [];
+
+  if (companions.length === 0) {
+    return { paired: false, companions: [], checks };
+  }
+
+  const paired = Boolean(index?.paired);
+  const projectContent = await readFileSafe(path.join(cwd, ".specs/project/PROJECT.md"));
+
+  checks.push({
+    id: "atlas-companions",
+    label: "Atlas companions registry (.specs/companions/INDEX.json)",
+    weight: 5,
+    pass: true,
+    optional: !paired,
+  });
+
+  for (const companion of companions) {
+    const prefix = `atlas-${companion.id}`;
+    const installHint = `npx ${companion.npm} install`;
+    const optional = !paired;
+
+    const primaryGate = companion.gates[0] ?? "";
+    const gateOk = primaryGate
+      ? await pathExists(cwd, path.join(companion.scriptsDir, primaryGate))
+      : false;
+    checks.push({
+      id: `${prefix}-gate`,
+      label: `${companion.displayName}: routing gate (${companion.scriptsDir})`,
+      weight: 4,
+      pass: gateOk,
+      optional,
+      suggest: gateOk ? undefined : installHint,
+    });
+
+    const ruleOk = await pathExists(cwd, companion.ruleFile);
+    checks.push({
+      id: `${prefix}-rule`,
+      label: `${companion.displayName}: Cursor rule (${companion.ruleFile})`,
+      weight: 2,
+      pass: ruleOk,
+      optional,
+      suggest: ruleOk ? undefined : installHint,
+    });
+
+    const registryOk = projectContent
+      ? projectContent.includes(companion.projectSection)
+      : false;
+    checks.push({
+      id: `${prefix}-registry`,
+      label: `${companion.displayName}: PROJECT.md registry section`,
+      weight: 2,
+      pass: registryOk,
+      optional: true,
+      suggest: registryOk
+        ? undefined
+        : `${installHint} --sync-registry`,
+    });
+
+    if (paired) {
+      const mirrorName =
+        companion.gates.find((name) => name !== primaryGate) ?? "";
+      if (mirrorName) {
+        const mirrorOk = await pathExists(
+          cwd,
+          path.join(GUARDRAILS_SCRIPTS_DIR, mirrorName),
+        );
+        checks.push({
+          id: `${prefix}-mirror`,
+          label: `${companion.displayName}: gate mirror (${GUARDRAILS_SCRIPTS_DIR}/${mirrorName})`,
+          weight: 3,
+          pass: mirrorOk,
+          optional,
+          suggest: mirrorOk ? undefined : installHint,
+        });
+      }
+    }
+  }
+
+  return { paired, companions, checks };
+}
+
+/**
+ * @param {DoctorCheck[]} companionChecks
+ * @returns {{ ready: boolean, passed: number, total: number }}
+ */
+export function summarizeCompanionChecks(companionChecks) {
+  const scoped = companionChecks.filter((check) => check.id !== "atlas-companions");
+  const required = scoped.filter((check) => !check.optional);
+  const passed = scoped.filter((check) => check.pass).length;
+  const requiredPassed = required.filter((check) => check.pass).length;
+  return {
+    ready: required.length === 0 || requiredPassed === required.length,
+    passed,
+    total: scoped.length,
+  };
+}

package/lib/companions.js

@@ -0,0 +1,97 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export const COMPANIONS_DIR = ".specs/companions";
+
+export const COMPANIONS_INDEX_FILE = "INDEX.json";
+
+export const ATLAS_SCHEMA_VERSION = "1.0.0";
+
+/**
+ * @typedef {{
+ *   id: string,
+ *   npm: string,
+ *   version: string,
+ *   displayName: string,
+ *   scriptsDir: string,
+ *   gates: string[],
+ *   projectSection: string,
+ *   ruleFile: string,
+ *   preservePaths: string[],
+ * }} CompanionIndexEntry
+ */
+
+/**
+ * @typedef {{
+ *   schemaVersion: string,
+ *   generatedAt: string,
+ *   paired: boolean,
+ *   companions: CompanionIndexEntry[],
+ * }} CompanionsIndex
+ */
+
+/**
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function companionsIndexPath(cwd) {
+  return path.join(cwd, COMPANIONS_DIR, COMPANIONS_INDEX_FILE);
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<CompanionsIndex | null>}
+ */
+export async function readCompanionsIndex(cwd) {
+  try {
+    const raw = await fs.readFile(companionsIndexPath(cwd), "utf8");
+    return /** @type {CompanionsIndex} */ (JSON.parse(raw));
+  } catch (err) {
+    if (err && /** @type {NodeJS.ErrnoException} */ (err).code === "ENOENT") {
+      return null;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Collect preserve paths from all registered Atlas companions.
+ * Falls back to known Tech Atlas 0.5 paths when INDEX is absent.
+ *
+ * @param {string} cwd
+ * @returns {Promise<string[]>}
+ */
+export async function collectCompanionPreservePaths(cwd) {
+  const index = await readCompanionsIndex(cwd);
+  if (!index) {
+    return [
+      ".specs/tech-atlas",
+      ".specs/atlas",
+      ".specs/desks",
+      ".specs/companions",
+    ];
+  }
+
+  const paths = new Set();
+  for (const companion of index.companions) {
+    for (const preservePath of companion.preservePaths) {
+      paths.add(preservePath);
+    }
+    for (const gate of companion.gates) {
+      paths.add(path.posix.join(companion.scriptsDir, gate));
+    }
+    paths.add(companion.scriptsDir);
+    paths.add(path.dirname(companion.ruleFile));
+  }
+  paths.add(COMPANIONS_DIR);
+  return [...paths];
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<CompanionIndexEntry[]>}
+ */
+export async function listInstalledCompanions(cwd) {
+  const index = await readCompanionsIndex(cwd);
+  return index?.companions ?? [];
+}

package/lib/doctor.js

@@ -8,6 +8,11 @@ import {
   NPX,
   SKILL_DIRS,
 } from "./constants.js";
+import { listInstalledCompanions } from "./companions.js";
+import {
+  runCompanionDoctorChecks,
+  summarizeCompanionChecks,
+} from "./companion-doctor.js";
 import { resolvePython, resolveScriptsDir } from "./gates.js";
 import { readFileSafe } from "./fs-utils.js";
 import { listFeatureIds, readActiveFeatureFromState } from "./specs-utils.js";
@@ -198,6 +203,21 @@ export async function runDoctorChecks(cwd) {
     suggest: NPX("project-init"),
   });
 
+  const companionReport = await runCompanionDoctorChecks(cwd);
+  if (companionReport.checks.length > 0) {
+    checks.push(...companionReport.checks);
+  } else {
+    checks.push({
+      id: "atlas-companions",
+      label: "Atlas companions registry (.specs/companions/INDEX.json)",
+      weight: 5,
+      pass: false,
+      optional: true,
+      suggest:
+        "Optional: npx @luizsantiago/tech-atlas install (or another Atlas package)",
+    });
+  }
+
   const activeFeature = await readActiveFeature(cwd);
   let activeFeatureOk = true;
   let activeFeatureSuggest;
@@ -379,16 +399,45 @@ export async function doctor(cwd, options = {}) {
   const executeHint = await resolveExecuteHint(cwd, activeFeature);
   const pythonCheck = checks.find((check) => check.id === "python");
   const pythonMissing = pythonCheck ? !pythonCheck.pass : false;
+  const companions = await listInstalledCompanions(cwd);
+  const companionChecks = checks.filter((check) => check.id.startsWith("atlas-"));
+  const companionSummary = summarizeCompanionChecks(companionChecks);
+  const stackPaired = companions.length > 0 && companionChecks.some((c) => !c.optional);
 
   if (options.json) {
     console.log(
       JSON.stringify(
-        { score, modes, checks, suggestions, executeHint, pythonMissing },
+        {
+          score,
+          modes,
+          checks,
+          suggestions,
+          executeHint,
+          pythonMissing,
+          stack: {
+            paired: stackPaired,
+            companions: companions.map((c) => ({
+              id: c.id,
+              npm: c.npm,
+              version: c.version,
+              displayName: c.displayName,
+            })),
+            atlasReady: companionSummary.ready,
+          },
+        },
         null,
         2,
       ),
     );
-    return { score, modes, checks, suggestions, executeHint, pythonMissing };
+    return {
+      score,
+      modes,
+      checks,
+      suggestions,
+      executeHint,
+      pythonMissing,
+      stack: { paired: stackPaired, companions, atlasReady: companionSummary.ready },
+    };
   }
 
   if (pythonMissing) {
@@ -407,6 +456,13 @@ export async function doctor(cwd, options = {}) {
   console.log(`  Brakes:  ${modes.brakes.score}/100${brakesHint}\n`);
   console.log(`Guardrails Ready: ${score}/100\n`);
 
+  if (companions.length > 0) {
+    const stackLabel = stackPaired ? "paired Lego stack" : "solo + Atlas companions";
+    console.log(
+      `Atlas stack: ${stackLabel} — ${companions.length} companion(s), ${companionSummary.passed}/${companionSummary.total} checks passed\n`,
+    );
+  }
+
   for (const check of checks) {
     const mark = check.pass ? "✓" : "✗";
     const optional = check.optional ? " (optional)" : "";
@@ -427,5 +483,13 @@ export async function doctor(cwd, options = {}) {
     console.log(`\nExecute hint:\n  → ${executeHint}`);
   }
 
-  return { score, modes, checks, suggestions, executeHint, pythonMissing };
+  return {
+    score,
+    modes,
+    checks,
+    suggestions,
+    executeHint,
+    pythonMissing,
+    stack: { paired: stackPaired, companions, atlasReady: companionSummary.ready },
+  };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luizsantiago/spec-guardrails",
-  "version": "3.1.10",
+  "version": "3.1.11",
   "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: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_companions.test.js test/test_companion_doctor.test.js",
     "test:gates": "node test/run-gate-tests.mjs",
     "prepublishOnly": "npm test"
   },