@luizsantiago/spec-guardrails 4.5.2 → 4.7.0

package/README.md

@@ -10,7 +10,12 @@
 
 Spec Guardrails installs a working method into your repository: the agent writes down what it is going to build, gets your approval, implements in small waves, and proves the result before calling it done. Nothing about your stack changes — you get written requirements, a task plan, and verification evidence stored as files in the project.
 
-npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **4.5.x**
+npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **4.7.x**
+
+### Who it's for
+
+- **Any stack** — default SDD with gates and `.specs/` memory
+- **Python platform teams** — backend + DevOps + AI in one repo: use preset `python-platform`, Ship/AI Surface, and [Tutorial 04](docs/guide/tutorials/04-python-platform-ship-surface.md). Not a live observability platform — see [limitations](docs/guide/python-platform.md#limitations-honest).
 
 ---
 
@@ -60,7 +65,7 @@ In short: Python turns "trust the agent" into "the agent has to prove it."
 
 Which checks exist and what each one requires: [Gates](docs/guide/gates.md) · [Guarantees matrix](docs/guide/Guarantees-matrix.md)
 
-Read more: [Quick start](docs/guide/Quick-start.md) · [Platform parity](docs/guide/Platform-parity.md) · [CHANGELOG](docs/CHANGELOG.md)
+| Go deeper | [Quick start](docs/guide/Quick-start.md) · [CHANGELOG](docs/CHANGELOG.md) · [Product history](docs/guide/Product-history.md) · [Tutorials](docs/guide/tutorials/README.md) · [Platform parity](docs/guide/Platform-parity.md) |
 
 ---
 
@@ -212,7 +217,7 @@ See [Guarantees matrix](docs/guide/Guarantees-matrix.md) for the full product vi
 | Enforcement | [Gates](docs/guide/gates.md) | [Gates and guarantees](docs/guide/Gates-and-guarantees.md) |
 | Requirements | [Requirements analysis](docs/guide/requirements-analysis.md) | [Agent commands → /elicit](docs/guide/agent-commands.md) |
 | Long-running projects | [Memory](docs/guide/Memory.md) | [Brownfield context](docs/guide/brownfield-context.md) |
-| Questions | [FAQ](docs/guide/FAQ.md) | [Glossary](docs/guide/Glossary.md) · [Stability policy](docs/guide/Stability-policy.md) |
+| Questions | [FAQ](docs/guide/FAQ.md) | [Glossary](docs/guide/Glossary.md) · [Product history](docs/guide/Product-history.md) · [Stability policy](docs/guide/Stability-policy.md) |
 
 Full index: [docs/guide/README.md](docs/guide/README.md)
 

package/index.js

@@ -25,6 +25,10 @@ import {
   savePolicyState,
 } from "./lib/execution-policy.js";
 import { featureInit } from "./lib/feature.js";
+import {
+  featureOverview,
+  formatFeatureOverview,
+} from "./lib/feature-overview.js";
 import { featureStatus, formatFeatureStatus } from "./lib/feature-status.js";
 import { GATE_COMMANDS, AUX_COMMANDS, runGate, runGuardrailsScript } from "./lib/gates.js";
 import { install } from "./lib/install.js";
@@ -105,6 +109,9 @@ Commands:
     [--json]                         Machine-readable output
   feature-status [feature]           Artifact checklist + next step for a feature
     [--json]                         Machine-readable output
+  feature-overview [feature]           REQ → task → evidence dashboard (markdown)
+    [--write]                        Save .specs/features/<feature>/overview.md
+    [--json]                         Machine-readable output (no markdown body)
   phase-context <phase>              Print .specs/config.yaml context + rules for a phase
   doctor [path]                      Audit guardrails readiness (score + next actions)
     [--json]                         Machine-readable output
@@ -176,6 +183,7 @@ Commands:
   loop-plan [tasks.md|feature]       Next Execute wave — parallel groups + sub-agent hints
     [--json]                         Machine-readable plan for agents
   validate-traceability [feature]    REQ → tasks → validation coverage chain
+  validate-ship-surface [feature]    Ship Surface + AI Surface when infra/AI paths in tasks
   validate-quick [quick-folder]      Quick-mode TASK.md / SUMMARY.md structural gate
   validate-req-analysis [brief.md]   Requirements brief gate before /specify (/elicit)
   validate-state [feature]           Completion gate before declaring a feature done
@@ -1079,6 +1087,33 @@ if (command === "--version" || command === "-v" || command === "version") {
     console.error(`❌ ${err.message}`);
     process.exit(1);
   }
+} else if (command === "feature-overview") {
+  try {
+    let json = false;
+    let write = false;
+    const positional = [];
+    for (const arg of args) {
+      if (arg === "--json") {
+        json = true;
+      } else if (arg === "--write") {
+        write = true;
+      } else {
+        positional.push(arg);
+      }
+    }
+    const overview = await featureOverview(positional[0], { write });
+    if (json) {
+      console.log(JSON.stringify(overview, null, 2));
+    } else {
+      process.stdout.write(formatFeatureOverview(overview));
+      if (overview.writtenTo) {
+        process.stderr.write(`\nWrote ${overview.writtenTo}\n`);
+      }
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
 } else if (AUX_COMMANDS.includes(command)) {
   try {
     const code = await runGuardrailsScript(command, args);

package/lib/agent-contract.js

@@ -28,7 +28,7 @@ When planning architecture, specs, or multi-step features, read the hub first:
 Deterministic gates (\`python3\`, non-zero exit means STOP):
 
 - Scripts in \`.specs/guardrails/scripts/\` — the **agent** runs them at phase boundaries (see hub).
-- Humans: \`install\` once; optional \`feature-init\`, \`project-init\`, \`doctor\`, \`classify-change\`, \`feature-status\`.
+- Humans: \`install\` once; optional \`feature-init\`, \`project-init\`, \`doctor\`, \`classify-change\`, \`feature-status\`, \`feature-overview\`.
 - Full CLI: \`npx @luizsantiago/spec-guardrails --help\`
 - Onboarding: \`.specs/GETTING_STARTED.md\`
 

package/lib/brownfield.js

@@ -69,10 +69,41 @@ async function readRepoName(cwd) {
 
 /**
  * @param {string} cwd
- * @returns {Promise<{ stack: string, testCommand: string, lintCommand?: string, preset?: string, roots: string[] }>}
+ * @returns {Promise<boolean>}
+ */
+async function pathExists(target) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} dir
+ * @returns {Promise<boolean>}
+ */
+async function dirHasFilesMatching(dir, pattern) {
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && pattern.test(entry.name)) {
+        return true;
+      }
+    }
+  } catch {
+    // missing dir
+  }
+  return false;
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<{ stack: string, testCommand: string, lintCommand?: string, preset?: string, roots: string[], hasCompose?: boolean, hasTerraform?: boolean, hasHelm?: boolean, hasCi?: boolean, hasAiStack?: boolean, hasEvalHarness?: boolean }>}
  */
 export async function detectProjectStack(cwd) {
-  /** @type {{ stack: string, testCommand: string, lintCommand?: string, preset?: string, roots: string[] }} */
+  /** @type {{ stack: string, testCommand: string, lintCommand?: string, preset?: string, roots: string[], hasCompose?: boolean, hasTerraform?: boolean, hasHelm?: boolean, hasCi?: boolean, hasAiStack?: boolean, hasEvalHarness?: boolean }} */
   const result = {
     stack: "unknown",
     testCommand: "(fill in)",
@@ -137,6 +168,45 @@ export async function detectProjectStack(cwd) {
     }
   }
 
+  result.hasCompose =
+    (await pathExists(path.join(cwd, "Dockerfile"))) ||
+    (await dirHasFilesMatching(cwd, /^docker-compose.*\.(ya?ml)$/i));
+  result.hasTerraform =
+    (await pathExists(path.join(cwd, "terraform"))) ||
+    (await dirHasFilesMatching(cwd, /\.tf$/i));
+  result.hasHelm =
+    (await pathExists(path.join(cwd, "charts"))) ||
+    (await pathExists(path.join(cwd, "helm")));
+  result.hasCi = await dirHasFilesMatching(
+    path.join(cwd, ".github", "workflows"),
+    /\.ya?ml$/i,
+  );
+  result.hasEvalHarness =
+    (await pathExists(path.join(cwd, "evals"))) ||
+    (await pathExists(path.join(cwd, "tests", "eval")));
+
+  if (result.stack === "Python") {
+    try {
+      const pyproject = await readFileSafe(path.join(cwd, "pyproject.toml"));
+      result.hasAiStack = /\[(project|tool\.poetry)\.[^\]]*?(llm|ai)[^\]]*\]/i.test(
+        pyproject,
+      );
+    } catch {
+      result.hasAiStack = false;
+    }
+
+    const platformSignals =
+      result.hasCompose ||
+      result.hasTerraform ||
+      result.hasHelm ||
+      result.hasCi ||
+      result.hasAiStack ||
+      result.hasEvalHarness;
+    if (platformSignals) {
+      result.preset = "python-platform";
+    }
+  }
+
   return result;
 }
 
@@ -222,6 +292,20 @@ export function buildProjectMarkdown(input) {
   if (input.stack.lintCommand) {
     stackLines += `\n- Lint: ${input.stack.lintCommand}`;
   }
+  const flags = [
+    input.stack.hasCompose && "Docker/Compose",
+    input.stack.hasTerraform && "Terraform",
+    input.stack.hasHelm && "Helm",
+    input.stack.hasCi && "CI workflows",
+    input.stack.hasAiStack && "AI deps (pyproject)",
+    input.stack.hasEvalHarness && "eval harness dir",
+  ].filter(Boolean);
+  if (flags.length) {
+    stackLines += `\n- Platform signals: ${flags.join(", ")}`;
+  }
+  if (input.stack.preset) {
+    stackLines += `\n- Suggested preset: \`${input.stack.preset}\``;
+  }
 
   return `# Project: ${input.repoName}
 

package/lib/classify-change.js

@@ -34,6 +34,16 @@ const VAGUE_SIGNALS = [
   /\bwithout\s+(?:criteria|details|spec)\b/i,
 ];
 
+const AI_SIGNALS = [
+  /\bllm\b/i,
+  /\brag\b/i,
+  /\bembedding(s)?\b/i,
+  /\bmcp\b/i,
+  /\bagent(s)?\b/i,
+  /\bprompt(s)?\b/i,
+  /\bvector\b/i,
+];
+
 /**
  * @param {{ description?: string, files?: string[] }} input
  * @returns {{
@@ -41,6 +51,7 @@ const VAGUE_SIGNALS = [
  *   reasons: string[],
  *   next: string,
  *   suggestElicit: boolean,
+ *   suggestAiSkill: boolean,
  *   fileCount: number,
  * }}
  */
@@ -55,6 +66,11 @@ export function classifyChange(input = {}) {
   const hasMedium = MEDIUM_SIGNALS.some((re) => re.test(haystack));
   const hasNewDep = DEPENDENCY_SIGNALS.some((re) => re.test(haystack));
   const hasVague = VAGUE_SIGNALS.some((re) => re.test(haystack));
+  const hasAi = AI_SIGNALS.some((re) => re.test(haystack));
+
+  if (hasAi) {
+    reasons.push("AI engineering signal (llm/rag/mcp/agent/prompt)");
+  }
 
   if (hasComplex) {
     reasons.push("sensitive surface or architecture signal in description/paths");
@@ -77,6 +93,9 @@ export function classifyChange(input = {}) {
 
   if (hasComplex) {
     tier = "complex";
+  } else if (hasAi && (hasMedium || hasNewDep || fileCount > 3)) {
+    tier = "complex";
+    reasons.push("AI surface with feature-scale change — use full pipeline + AI Surface in design");
   } else if (
     !hasNewDep &&
     fileCount > 0 &&
@@ -121,7 +140,8 @@ export function classifyChange(input = {}) {
     tier,
     reasons,
     next: nextByTier[tier],
-    suggestElicit: hasVague && !hasComplex,
+    suggestElicit: (hasVague || hasAi) && !hasComplex,
+    suggestAiSkill: hasAi,
     fileCount,
   };
 }
@@ -141,5 +161,8 @@ export function formatClassifyChange(result) {
   if (result.suggestElicit) {
     lines.push("Suggest: /elicit (structured Q&A) or /specify if scope is already clear");
   }
+  if (result.suggestAiSkill) {
+    lines.push("Suggest: load ai-engineering.md sister skill + document AI Surface in design.md");
+  }
   return `${lines.join("\n")}\n`;
 }

package/lib/constants.js

@@ -67,6 +67,14 @@ export const SKILL_ASSETS = [
     file: "git-handoff.md",
     remotePath: "skills/git-handoff.md",
   },
+  {
+    file: "python-devops.md",
+    remotePath: "skills/python-devops.md",
+  },
+  {
+    file: "ai-engineering.md",
+    remotePath: "skills/ai-engineering.md",
+  },
   {
     file: "task-graph-engineering.md",
     remotePath: "skills/task-graph-engineering.md",
@@ -105,6 +113,7 @@ export const SCRIPT_ASSETS = [
   { file: "validate_tasks.py", remotePath: "scripts/validate_tasks.py" },
   { file: "validate_state.py", remotePath: "scripts/validate_state.py" },
   { file: "validate_traceability.py", remotePath: "scripts/validate_traceability.py" },
+  { file: "validate_ship_surface.py", remotePath: "scripts/validate_ship_surface.py" },
   { file: "validate_quick.py", remotePath: "scripts/validate_quick.py" },
   { file: "analyze_artifacts.py", remotePath: "scripts/analyze_artifacts.py" },
   { file: "check_commit.py", remotePath: "scripts/check_commit.py" },

package/lib/feature-overview.js

@@ -0,0 +1,332 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { readFileSafe } from "./fs-utils.js";
+import { featureStatus } from "./feature-status.js";
+import { featureDir, resolveFeatureId } from "./specs-utils.js";
+
+const REQ_ID = /\b[A-Z][A-Z0-9]{1,9}-\d{2,4}\b/g;
+const TASK_HEADING = /^#{2,6}\s*(T\d+)[:\s]+(.+)$/gim;
+const TASK_FIELD =
+  /^\s*[-*]?\s*\*{0,2}([A-Za-z][A-Za-z ]+?)\*{0,2}\s*:\s*(.+?)\s*$/gim;
+const EVIDENCE = /[\w./\\-]+\.[A-Za-z][A-Za-z0-9]{0,9}:\d{1,6}\b/g;
+const SHIP_SECTION = /^##\s+Ship\s+Surface\s*$/im;
+const AI_SECTION = /^##\s+AI\s+Surface\s*$/im;
+const NEXT_SECTION = /^##\s+/gm;
+const SURFACE_FIELD =
+  /^\s*(?:[-*]\s*)?\*{0,2}([^|*\n]+?)\*{0,2}\s*:\s*(.+?)\s*$/gim;
+const SURFACE_TABLE =
+  /^\s*\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|\s*$/gim;
+
+/**
+ * @param {string} text
+ * @param {RegExp} heading
+ * @returns {string | null}
+ */
+function extractDesignSection(text, heading) {
+  const match = heading.exec(text);
+  if (!match || match.index === undefined) {
+    return null;
+  }
+  const start = match.index + match[0].length;
+  const rest = text.slice(start);
+  const next = rest.search(/^##\s+/m);
+  return next >= 0 ? rest.slice(0, next) : rest;
+}
+
+/**
+ * @param {string | null} sectionText
+ * @returns {Record<string, string>}
+ */
+function parseSurfaceFields(sectionText) {
+  if (!sectionText) {
+    return {};
+  }
+  /** @type {Record<string, string>} */
+  const fields = {};
+  for (const match of sectionText.matchAll(SURFACE_FIELD)) {
+    const key = match[1].trim();
+    if (key.toLowerCase() === "field" || key === "---") {
+      continue;
+    }
+    fields[key] = match[2].trim();
+  }
+  for (const match of sectionText.matchAll(SURFACE_TABLE)) {
+    const key = match[1].trim();
+    if (key.toLowerCase() === "field" || key === "---") {
+      continue;
+    }
+    fields[key] = match[2].trim();
+  }
+  return fields;
+}
+
+/**
+ * @param {string} text
+ * @returns {string[]}
+ */
+function uniqueReqIds(text) {
+  return [...new Set(text.match(REQ_ID) ?? [])];
+}
+
+/**
+ * @param {string} tasksText
+ * @returns {Array<{ id: string, title: string, requirement: string | null, complete: boolean }>}
+ */
+function parseTasks(tasksText) {
+  const headings = [...tasksText.matchAll(TASK_HEADING)];
+  /** @type {Array<{ id: string, title: string, requirement: string | null, complete: boolean }>} */
+  const tasks = [];
+
+  for (let i = 0; i < headings.length; i += 1) {
+    const start = headings[i].index ?? 0;
+    const end = headings[i + 1]?.index ?? tasksText.length;
+    const block = tasksText.slice(start, end);
+    const id = headings[i][1];
+    const title = headings[i][2].trim();
+    let requirement = null;
+    for (const match of block.matchAll(TASK_FIELD)) {
+      if (match[1].trim().toLowerCase() === "requirement") {
+        requirement = match[2].trim();
+        break;
+      }
+    }
+    const complete = /-\s*\[x\]\s*complete\b/i.test(block);
+    tasks.push({ id, title, requirement, complete });
+  }
+  return tasks;
+}
+
+/**
+ * @param {string} validationText
+ * @param {string} reqId
+ * @returns {string | null}
+ */
+function evidenceForReq(validationText, reqId) {
+  for (const line of validationText.split(/\r?\n/)) {
+    if (!line.includes(reqId)) {
+      continue;
+    }
+    const hit = line.match(EVIDENCE);
+    if (hit?.[0]) {
+      return hit[0];
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} specText
+ * @returns {string | null}
+ */
+function summarizeGoal(specText) {
+  const title = specText.match(/^#\s+(.+)$/m)?.[1]?.trim();
+  if (title && !/^spec/i.test(title)) {
+    return title;
+  }
+  const firstReq = specText.match(
+    /^###\s+([A-Z][A-Z0-9]{1,9}-\d{2,4})\b[^\n]*\n+([^\n#]+)/m,
+  );
+  if (firstReq) {
+    return `${firstReq[1]} — ${firstReq[2].trim()}`;
+  }
+  return title ?? null;
+}
+
+/**
+ * @param {string} [featureArg]
+ * @param {{ cwd?: string }} [options]
+ */
+export async function buildFeatureOverview(featureArg, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const featureId = await resolveFeatureId(featureArg, cwd);
+  const status = await featureStatus(featureId, { cwd });
+  const dir = featureDir(featureId, cwd);
+
+  let specText = "";
+  let tasksText = "";
+  let validationText = "";
+  let designText = "";
+
+  try {
+    specText = await readFileSafe(path.join(dir, "spec.md"));
+  } catch {
+    // optional until Specify
+  }
+  try {
+    designText = await readFileSafe(path.join(dir, "design.md"));
+  } catch {
+    // optional until Design
+  }
+  try {
+    tasksText = await readFileSafe(path.join(dir, "tasks.md"));
+  } catch {
+    // optional until Tasks
+  }
+  try {
+    validationText = await readFileSafe(path.join(dir, "validation.md"));
+  } catch {
+    // optional until Verify
+  }
+
+  const reqIds = uniqueReqIds(specText);
+  const tasks = tasksText ? parseTasks(tasksText) : [];
+  const reqToTasks = new Map();
+  for (const task of tasks) {
+    if (!task.requirement) {
+      continue;
+    }
+    for (const reqId of uniqueReqIds(task.requirement)) {
+      const list = reqToTasks.get(reqId) ?? [];
+      list.push(task.id);
+      reqToTasks.set(reqId, list);
+    }
+  }
+
+  const traceability = reqIds.map((reqId) => ({
+    reqId,
+    tasks: reqToTasks.get(reqId) ?? [],
+    evidence: validationText ? evidenceForReq(validationText, reqId) : null,
+  }));
+
+  const shipSurface = designText
+    ? parseSurfaceFields(extractDesignSection(designText, SHIP_SECTION))
+    : {};
+  const aiSurface = designText
+    ? parseSurfaceFields(extractDesignSection(designText, AI_SECTION))
+    : {};
+
+  return {
+    featureId,
+    generatedAt: new Date().toISOString(),
+    goal: specText ? summarizeGoal(specText) : null,
+    status,
+    tasks,
+    traceability,
+    shipSurface,
+    aiSurface,
+  };
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof buildFeatureOverview>>} overview
+ * @returns {string}
+ */
+export function formatFeatureOverview(overview) {
+  const { status } = overview;
+  const artifactRows = Object.entries(status.artifacts)
+    .map(([name, present]) => `| ${name} | ${present ? "present" : "missing"} |`)
+    .join("\n");
+
+  const taskRows =
+    overview.tasks.length > 0
+      ? overview.tasks
+          .map(
+            (task) =>
+              `| ${task.id} | ${task.title} | ${task.requirement ?? "—"} | ${task.complete ? "done" : "open"} |`,
+          )
+          .join("\n")
+      : "| — | — | — | — |";
+
+  const traceRows =
+    overview.traceability.length > 0
+      ? overview.traceability
+          .map((row) => {
+            const tasks =
+              row.tasks.length > 0 ? row.tasks.join(", ") : "—";
+            return `| ${row.reqId} | ${tasks} | ${row.evidence ?? "—"} |`;
+          })
+          .join("\n")
+      : "| — | — | — |";
+
+  const shipRows =
+    Object.keys(overview.shipSurface ?? {}).length > 0
+      ? Object.entries(overview.shipSurface)
+          .map(([field, value]) => `| ${field} | ${value} |`)
+          .join("\n")
+      : "| — | — |";
+
+  const aiRows =
+    Object.keys(overview.aiSurface ?? {}).length > 0
+      ? Object.entries(overview.aiSurface)
+          .map(([field, value]) => `| ${field} | ${value} |`)
+          .join("\n")
+      : "| — | — |";
+
+  const taskSummary = status.tasks
+    ? `${status.tasks.complete}/${status.tasks.total} complete (${status.tasks.open} open)`
+    : "—";
+
+  return `# Feature overview: ${overview.featureId}
+
+> Generated ${overview.generatedAt}. Refresh with \`feature-overview ${overview.featureId} --write\`.
+
+## Summary
+
+| Field | Value |
+| --- | --- |
+| Goal | ${overview.goal ?? "—"} |
+| Phase | ${status.phase ?? "—"} |
+| Branch | ${status.branch ?? "—"} |
+| Tasks | ${taskSummary} |
+| Validation | ${status.verdict ?? "—"} |
+| Next | ${status.next} |
+
+## Artifacts
+
+| Artifact | Status |
+| --- | --- |
+${artifactRows}
+
+## Tasks
+
+| Task | Title | Requirement | Status |
+| --- | --- | --- | --- |
+${taskRows}
+
+## Traceability (REQ → task → evidence)
+
+| REQ | Task(s) | Test evidence |
+| --- | --- | --- |
+${traceRows}
+
+## Operational traceability (Ship Surface)
+
+| Field | Value |
+| --- | --- |
+${shipRows}
+
+_Parsed from \`design.md\` when present. Does not infer undeclared deploy paths._
+
+## AI traceability (AI Surface)
+
+| Field | Value |
+| --- | --- |
+${aiRows}
+
+_Eval harness and fallback must be documented for AI paths — gate \`validate_ship_surface\` enforces structure only._
+
+_Evidence rows populate after \`validation.md\` exists. Structural gaps are caught by \`validate-traceability\` and \`validate-ship-surface\`._
+`;
+}
+
+/**
+ * @param {string} [featureArg]
+ * @param {{ cwd?: string; write?: boolean }} [options]
+ */
+export async function featureOverview(featureArg, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const overview = await buildFeatureOverview(featureArg, { cwd });
+  const markdown = formatFeatureOverview(overview);
+
+  if (options.write) {
+    const outPath = path.join(
+      featureDir(overview.featureId, cwd),
+      "overview.md",
+    );
+    await fs.writeFile(outPath, markdown, "utf8");
+    overview.writtenTo = outPath;
+  }
+
+  return overview;
+}

package/lib/gates.js

@@ -33,6 +33,7 @@ const GATE_SCRIPTS = {
   "validate-tasks": "validate_tasks.py",
   "validate-state": "validate_state.py",
   "validate-traceability": "validate_traceability.py",
+  "validate-ship-surface": "validate_ship_surface.py",
   "validate-quick": "validate_quick.py",
   "validate-req-analysis": "validate_req_analysis.py",
   "analyze-artifacts": "analyze_artifacts.py",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luizsantiago/spec-guardrails",
-  "version": "4.5.2",
+  "version": "4.7.0",
   "description": "Governed spec-driven development for AI coding agents. Your agent writes the spec, gets your approval, builds in small waves, and proves the result — plans and project memory stored as files in your repo.",
   "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_platform_detect.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/test_context_guard.test.js test/test_solution_exploration.test.js test/test_memory_doctor.test.js test/test_cursor_hooks_cleanup.test.js test/test_sandbox_policy.test.js test/test_req_analysis.test.js",
+    "test:node": "node --test test/install.test.js test/test_platform_detect.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_feature_overview.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/test_context_guard.test.js test/test_solution_exploration.test.js test/test_memory_doctor.test.js test/test_cursor_hooks_cleanup.test.js test/test_sandbox_policy.test.js test/test_req_analysis.test.js",
     "test:gates": "node test/run-gate-tests.mjs",
     "prepublishOnly": "npm test"
   },

package/rules/engineering-baseline.mdc

@@ -34,6 +34,8 @@ Chat language is a personal preference. Set it in your own agent settings if you
 | `.cursor/skills/code-simplify.md` | Simplification sister (load on demand) |
 | `.cursor/skills/ship-ready.md` | Ship-ready sister (load on demand) |
 | `.cursor/skills/git-handoff.md` | Git sync and session handoff |
+| `.cursor/skills/python-devops.md` | Python DevOps — Ship Surface (load on demand) |
+| `.cursor/skills/ai-engineering.md` | AI engineering — AI Surface (load on demand) |
 <!-- guardrails-managed:skills-map:end -->
 
 # Deterministic Gates