@luizsantiago/spec-guardrails 4.6.0 → 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.6.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) · [Tutorials](docs/guide/tutorials/README.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

@@ -183,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

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

@@ -10,6 +10,56 @@ 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
@@ -96,12 +146,18 @@ export async function buildFeatureOverview(featureArg, options = {}) {
   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 {
@@ -133,6 +189,13 @@ export async function buildFeatureOverview(featureArg, options = {}) {
     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(),
@@ -140,6 +203,8 @@ export async function buildFeatureOverview(featureArg, options = {}) {
     status,
     tasks,
     traceability,
+    shipSurface,
+    aiSurface,
   };
 }
 
@@ -174,6 +239,20 @@ export function formatFeatureOverview(overview) {
           .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)`
     : "—";
@@ -211,7 +290,23 @@ ${taskRows}
 | --- | --- | --- |
 ${traceRows}
 
-_Evidence rows populate after \`validation.md\` exists. Structural gaps are caught by \`validate-traceability\`._
+## 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\`._
 `;
 }
 

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.6.0",
+  "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": {

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

package/scripts/_project_config.py

@@ -21,6 +21,27 @@ DEFAULT_SUPPRESSION_PATTERNS = [
 
 DEFAULT_MAX_STAGED_LINES = 500
 
+DEFAULT_INFRA_GLOBS = [
+    "**/Dockerfile",
+    "**/docker-compose*.yml",
+    "**/docker-compose*.yaml",
+    "**/terraform/**",
+    "**/*.tf",
+    "**/charts/**",
+    "**/helm/**",
+    "**/.github/workflows/**",
+]
+
+DEFAULT_AI_GLOBS = [
+    "**/prompts/**",
+    "**/mcp/**",
+    "**/evals/**",
+    "**/tests/eval/**",
+    "**/*embed*",
+    "**/*llm*",
+    "**/*rag*",
+]
+
 
 def config_path(cwd: Path | str | None = None) -> Path:
     root = Path(cwd) if cwd is not None else Path.cwd()
@@ -64,6 +85,10 @@ def load_project_config(cwd: Path | str | None = None) -> dict:
         "quality": {"checks": []},
         "suppressions": {"patterns": list(DEFAULT_SUPPRESSION_PATTERNS)},
         "commit": {"max_staged_lines": DEFAULT_MAX_STAGED_LINES},
+        "ship_surface": {
+            "infra_globs": list(DEFAULT_INFRA_GLOBS),
+            "ai_globs": list(DEFAULT_AI_GLOBS),
+        },
     }
 
     path = config_path(cwd)
@@ -102,9 +127,27 @@ def load_project_config(cwd: Path | str | None = None) -> dict:
             index += 1
             continue
 
+        if stripped == "ship_surface:":
+            section = "ship_surface"
+            section_indent = indent
+            index += 1
+            continue
+
         if section and indent <= section_indent and not stripped.endswith(":"):
             section = None
 
+        if section == "ship_surface" and stripped == "infra_globs:":
+            items, index = _parse_list_block(lines, index + 1, indent)
+            if items:
+                config["ship_surface"]["infra_globs"] = items
+            continue
+
+        if section == "ship_surface" and stripped == "ai_globs:":
+            items, index = _parse_list_block(lines, index + 1, indent)
+            if items:
+                config["ship_surface"]["ai_globs"] = items
+            continue
+
         if section == "quality" and stripped == "checks:":
             items, index = _parse_list_block(lines, index + 1, indent)
             config["quality"]["checks"] = items
@@ -124,3 +167,9 @@ def load_project_config(cwd: Path | str | None = None) -> dict:
         index += 1
 
     return config
+
+
+def load_ship_surface_config(cwd: Path | str | None = None) -> dict:
+    """Return ship_surface globs with defaults for validate_ship_surface.py."""
+
+    return load_project_config(cwd)["ship_surface"]

package/scripts/validate_ship_surface.py

@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+"""Ship Surface + AI Surface structural gate for python-platform teams.
+
+Run after Tasks (before Execute) and again before Verify when infra or AI paths
+are listed in task Files:
+
+    python3 validate_ship_surface.py auth
+    python3 validate_ship_surface.py .specs/features/003-rag-api
+
+Checks (markdown structure only — not deploy safety or eval quality):
+  * when task Files match infra_globs → design.md ## Ship Surface with required fields
+  * when task Files match ai_globs → design.md ## AI Surface with Eval harness + Fallback
+  * fields must be non-empty and not placeholder tokens
+
+Limitations (documented honestly):
+  * does not run terraform plan, helm diff, or live LLM eval
+  * does not validate semantic correctness of rollback or fallback strategies
+  * globs are configurable via ship_surface.infra_globs / ai_globs in .specs/config.yaml
+
+Exit codes: 0 pass, 1 blocking issues, 2 usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import re
+import sys
+from pathlib import Path
+
+from _common import Report, resolve_feature_dir, visible_markdown
+from _project_config import load_ship_surface_config
+from validate_tasks import parse_files
+
+GATE = "validate-ship-surface"
+
+SHIP_SECTION = re.compile(r"^##\s+Ship\s+Surface\s*$", re.MULTILINE | re.IGNORECASE)
+AI_SECTION = re.compile(r"^##\s+AI\s+Surface\s*$", re.MULTILINE | re.IGNORECASE)
+NEXT_SECTION = re.compile(r"^##\s+", re.MULTILINE)
+
+SHIP_REQUIRED_FIELDS = ("Deploy unit", "CI", "Rollback")
+AI_REQUIRED_FIELDS = ("Eval harness", "Fallback / degrade")
+
+FIELD_LINE = re.compile(
+    r"^\s*(?:[-*]\s*)?\*{0,2}(?P<key>[^|*\n]+?)\*{0,2}\s*:\s*(?P<value>.+?)\s*$",
+    re.MULTILINE,
+)
+TABLE_ROW = re.compile(
+    r"^\s*\|\s*(?P<key>[^|]+?)\s*\|\s*(?P<value>[^|]+?)\s*\|\s*$",
+    re.MULTILINE,
+)
+
+PLACEHOLDER_VALUES = frozenset(
+    {
+        "",
+        "—",
+        "-",
+        "n/a",
+        "na",
+        "none",
+        "tbd",
+        "todo",
+        "(fill in)",
+        "(fill me)",
+    }
+)
+
+
+def extract_section(text: str, heading: re.Pattern[str]) -> str | None:
+    match = heading.search(text)
+    if not match:
+        return None
+    start = match.end()
+    rest = text[start:]
+    next_heading = NEXT_SECTION.search(rest)
+    end = start + next_heading.start() if next_heading else len(text)
+    return text[start:end]
+
+
+def parse_surface_fields(section_text: str | None) -> dict[str, str]:
+    if not section_text:
+        return {}
+
+    fields: dict[str, str] = {}
+    visible = visible_markdown(section_text)
+
+    for match in FIELD_LINE.finditer(visible):
+        key = match.group("key").strip().strip("*")
+        value = match.group("value").strip().strip("*")
+        if key.lower() in {"field", "key", "---"}:
+            continue
+        fields[key] = value
+
+    for match in TABLE_ROW.finditer(visible):
+        key = match.group("key").strip()
+        value = match.group("value").strip()
+        if key.lower() in {"field", "key", "---"}:
+            continue
+        fields[key] = value
+
+    return fields
+
+
+def is_placeholder(value: str) -> bool:
+    cleaned = value.strip().strip("`").lower()
+    if cleaned in PLACEHOLDER_VALUES:
+        return True
+    return cleaned.startswith("(fill")
+
+
+def normalize_path(path: str) -> str:
+    return path.replace("\\", "/").lstrip("./")
+
+
+def path_matches_globs(file_path: str, globs: list[str]) -> bool:
+    normalized = normalize_path(file_path)
+    name = Path(normalized).name
+    for pattern in globs:
+        pat = pattern.replace("\\", "/").lstrip("./")
+        if fnmatch.fnmatch(normalized, pat) or fnmatch.fnmatch(name, pat):
+            return True
+        if pat.endswith("/**"):
+            prefix = pat[:-3].rstrip("/")
+            if normalized == prefix or normalized.startswith(f"{prefix}/"):
+                return True
+        tail = pat.rsplit("/", 1)[-1]
+        if tail and tail != "**" and "*" in tail and fnmatch.fnmatch(name, tail):
+            return True
+    return False
+
+
+def collect_task_files(tasks_text: str) -> list[str]:
+    files: list[str] = []
+    for match in FIELD_LINE.finditer(tasks_text):
+        if match.group("key").strip().lower() != "files":
+            continue
+        files.extend(parse_files(match.group("value")))
+    return files
+
+
+def find_field(fields: dict[str, str], *candidates: str) -> str | None:
+    lowered = {key.lower(): value for key, value in fields.items()}
+    for candidate in candidates:
+        value = lowered.get(candidate.lower())
+        if value is not None:
+            return value
+    return None
+
+
+def missing_required(fields: dict[str, str], required: tuple[str, ...]) -> list[str]:
+    missing: list[str] = []
+    for name in required:
+        value = find_field(fields, name)
+        if value is None or is_placeholder(value):
+            missing.append(name)
+    return missing
+
+
+def read_optional(feature_dir: Path, filename: str) -> str | None:
+    path = feature_dir / filename
+    if not path.is_file():
+        return None
+    text = path.read_text(encoding="utf-8")
+    return text if text.strip() else None
+
+
+def build_report(feature_dir: Path, cwd: Path | None = None) -> Report:
+    report = Report(gate=GATE, target=str(feature_dir))
+    config = load_ship_surface_config(cwd or feature_dir.parent.parent.parent)
+    infra_globs = config["infra_globs"]
+    ai_globs = config["ai_globs"]
+
+    tasks_text = read_optional(feature_dir, "tasks.md")
+    if not tasks_text:
+        report.warn("tasks.md missing — skipping ship/AI surface checks")
+        return report
+
+    task_files = collect_task_files(tasks_text)
+    if not task_files:
+        report.warn("no Files paths in tasks.md — skipping ship/AI surface checks")
+        return report
+
+    needs_ship = any(path_matches_globs(path, infra_globs) for path in task_files)
+    needs_ai = any(path_matches_globs(path, ai_globs) for path in task_files)
+
+    if not needs_ship and not needs_ai:
+        report.ok("no infra or AI paths in task Files — gate not required")
+        return report
+
+    design_text = read_optional(feature_dir, "design.md")
+    if not design_text:
+        report.error("design.md missing or empty — required when tasks touch infra or AI paths")
+        return report
+
+    if needs_ship:
+        ship_fields = parse_surface_fields(extract_section(design_text, SHIP_SECTION))
+        if not ship_fields:
+            report.error("design.md missing or empty — required when tasks touch infra or AI paths")
+        else:
+            report.ok(f"Ship Surface: {len(ship_fields)} field(s) parsed")
+            for field in missing_required(ship_fields, SHIP_REQUIRED_FIELDS):
+                report.error(f"Ship Surface missing or placeholder field: {field}")
+
+    if needs_ai:
+        ai_fields = parse_surface_fields(extract_section(design_text, AI_SECTION))
+        if not ai_fields:
+            report.error("## AI Surface missing or empty in design.md")
+        else:
+            report.ok(f"AI Surface: {len(ai_fields)} field(s) parsed")
+            for field in missing_required(ai_fields, AI_REQUIRED_FIELDS):
+                report.error(f"AI Surface missing or placeholder field: {field}")
+
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Validate Ship Surface and AI Surface in design.md")
+    parser.add_argument(
+        "feature",
+        nargs="?",
+        help="Feature id, slug, or path to .specs/features/<feature>",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        feature_dir = resolve_feature_dir(args.feature)
+    except SystemExit as exc:
+        print(exc, file=sys.stderr)
+        return 2
+
+    cwd = feature_dir.parent.parent.parent
+    report = build_report(feature_dir, cwd)
+    return report.emit()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/agent-architecture.md

@@ -64,6 +64,7 @@ Structural gates run **before** owner review, so they cannot drift when the mode
 | During Verify, when `quality.checks` is configured | `python3 .specs/guardrails/scripts/run_quality_checks.py` |
 | Before declaring a feature done | `python3 .specs/guardrails/scripts/validate_state.py [feature]` |
 | Traceability (Medium+ features) | `python3 .specs/guardrails/scripts/validate_traceability.py [feature]` |
+| Ship / AI Surface (when infra or AI paths in tasks) | `python3 .specs/guardrails/scripts/validate_ship_surface.py [feature]` |
 | Quick mode evidence | `python3 .specs/guardrails/scripts/validate_quick.py [feature]` |
 | After Verify PASS | `npx @luizsantiago/spec-guardrails archive-feature [feature]` (Tier 0) |
 | Before a phase procedure (optional) | `npx @luizsantiago/spec-guardrails phase-context <phase>` |
@@ -93,7 +94,7 @@ EXPLORE (optional) → ELICIT (optional) → SPECIFY → DISCUSS (conditional)
 | **Tasks** | No | `references/tasks.md` | `task-graph-engineering.md` | `validate_tasks.py` |
 | **Analyze** | Before task approval | `references/analyze.md` | — | `analyze_artifacts.py` |
 | **Execute** | Yes | `references/implement.md` | `engineering-standards.md` | `check_commit.py`, `check_suppressions.py` |
-| **Verify** | Yes | `references/validate.md` | `security-review.md` | `validate_traceability.py`, `validate_state.py`, `run_quality_checks.py` |
+| **Verify** | Yes | `references/validate.md` | `security-review.md` | `validate_traceability.py`, `validate_ship_surface.py`, `validate_state.py`, `run_quality_checks.py` |
 | **Archive** | After Verify PASS | `references/archive.md` | `git-handoff.md` | `archive-feature` |
 | **Converge** | On drift | `references/converge.md` | — | `analyze_artifacts.py` |
 | **Handoff** | Yes | `references/memory.md` | `git-handoff.md` | — |
@@ -113,8 +114,10 @@ Not in the default phase-map cell. Load only on `/verify` after `validate.md` +
 | --- | --- | --- |
 | `appsec.md` | **Complex**, or auth / payments / PII / secrets / upload / SSRF / network trust boundary | Quick; Simple without those surfaces; copy/docs/styling |
 | `qa-strategy.md` | **Complex**, or multi-step user-facing flow, or owner asked for regression/QA | Quick; Simple one-file; evidence-or-zero alone is enough |
+| `python-devops.md` | Infra/docker/terraform/helm/CI paths in tasks, or `python-platform` preset | No deploy surface in the change |
+| `ai-engineering.md` | LLM/RAG/MCP/agent/prompt paths or classify-change AI signal | No AI paths in tasks |
 
-**Sequence.** If both triggers fire: AppSec → write `## AppSec` → **drop** `appsec.md` from the working set → QA → write `## QA`. Never load both together. Neither section is enforced by `validate_state.py` (verifier judgment).
+**Sequence.** If both AppSec and QA triggers fire: AppSec → write `## AppSec` → **drop** `appsec.md` → QA → write `## QA`. Never load AppSec + QA together. For platform work, `python-devops.md` and `ai-engineering.md` are independent of Verify sisters — load at most one on-demand sister during Design/Tasks/Execute when paths match; never with AppSec/QA in the same window.
 
 ## Complexity Router
 

package/skills/ai-engineering.md

@@ -0,0 +1,68 @@
+# AI Engineering
+
+Sister skill for **AI Surface** — model scope, tools/MCP, eval harness, fallback, and PII policy in `design.md`. Load when `classify-change` detects llm/rag/mcp/agent/prompt signals or tasks touch `prompts/`, `evals/`, MCP paths.
+
+**Not a substitute for** LangSmith/Coze Loop (live traces), MLOps platforms, or `security-review.md`.
+
+## Limitations
+
+- No live LLM observability — governance is versioned in git + structural gates, not production traces.
+- Eval quality is the team's responsibility — the gate requires a documented harness, not passing scores.
+- Semantic memory (`memory.retrieval.semantic`) is optional and off by default in `python-platform` preset.
+- Does not run paid API calls during gates — offline eval (`pytest -m "not live"`) is the default pattern.
+
+## When to Use
+
+- Vague kickoff ("add RAG", "agent with tools") — pair with `/elicit` first
+- Tasks list `Files` under `prompts/`, `evals/`, `tests/eval/`, `mcp/`, embeddings, or `*rag*`
+- Spec criteria describe non-deterministic model behavior
+
+## When NOT to Use
+
+- Deterministic CRUD with no model — skip AI Surface
+- Security-only review — use `security-review.md` / `appsec.md`
+
+## AI Surface (design.md)
+
+| Field | Purpose |
+| --- | --- |
+| **Capability** | chat, RAG, tool-use, batch embed, etc. |
+| **Model / provider** | e.g. gpt-4o, claude-sonnet, Ollama — no API keys in git |
+| **Tools / MCP scope** | allowlist / deny list for agent tools |
+| **Eval harness** | `pytest tests/eval/` or dataset path — **required by gate** |
+| **PII / data policy** | what must not reach the model; redaction path |
+| **Fallback / degrade** | timeout, rate limit, safe response — **required by gate** |
+| **Cost guard** | link to `execution-policy` / budget in `.specs/config.yaml` |
+
+Gate requires **Eval harness** and **Fallback / degrade** when AI globs match task `Files`.
+
+## Workflow connections (already shipped — do not reinvent)
+
+| Tool | Use when |
+| --- | --- |
+| `/elicit` + `req-analysis` | Brief is vague before `/specify` |
+| `solution-explore` | Choosing RAG vs fine-tune vs rules |
+| `memory-retrieve` | Finding past AI decisions in `.specs/` |
+| Discrimination sensor (`validate.md`) | Adversarial checks on behavior tests |
+| `execution-policy` + `sandbox` | Budget and dangerous commands |
+| `lessons.py` | After verify FAIL on eval — feed next sprint |
+
+## Specs for non-deterministic behavior
+
+- Write **testable** criteria: golden set, score thresholds, property bounds — not "answers well".
+- Version prompts in repo (`prompts/`) — anti-pattern: prompt only in code.
+- Eval tasks get explicit `Gate` commands; add offline eval to `quality.checks` when stable.
+
+## Anti-patterns
+
+- Tool without allowlist / MCP scope documented
+- Eval only manual in chat — no harness in repo
+- No fallback when model times out or refuses
+- PII in prompts without policy line in AI Surface
+
+## Related
+
+- `docs/guide/python-platform.md` — capabilities and honest limits
+- `python-devops.md` — when the same feature also ships infra
+- `references/design.md` — AI Surface template
+- `security-review.md` — PII, secrets, SSRF at verify

package/skills/python-devops.md

@@ -0,0 +1,60 @@
+# Python DevOps
+
+Sister skill for **Ship Surface** — deploy, CI, IaC, and rollback evidence in `design.md`. Load on demand when tasks touch Docker, Compose, Terraform, Helm, CI workflows, or when the project uses the `python-platform` preset.
+
+**Not a substitute for** `ship-ready.md` (owner go-live checklist) or `security-review.md` (secrets/PII).
+
+## Limitations
+
+- Structural gate only — `validate_ship_surface.py` checks that fields exist, not that `terraform plan` is safe or rollback was tested in production.
+- No Kubernetes runtime management — Helm template validation is optional via `quality.checks`, not built-in.
+- Framework-agnostic — FastAPI/Django/worker patterns live in tutorial appendices, not in this skill.
+
+## When to Use
+
+- Tasks list `Files` under `Dockerfile`, `docker-compose*.yml`, `terraform/`, `charts/`, `.github/workflows/`
+- Owner asks about deploy, rollback, migrations before ship
+- `project-init` suggested preset `python-platform`
+
+## When NOT to Use
+
+- Pure library/CLI changes with no infra touch — skip Ship Surface
+- Live observability or incident response — use your APM stack, not Spec Guardrails
+
+## Ship Surface (design.md)
+
+Document before Execute when infra paths appear in tasks:
+
+| Field | Purpose |
+| --- | --- |
+| **API / contract** | OpenAPI path, health route, or N/A for workers/CLIs |
+| **Migrations** | Alembic, Django migrate, or N/A |
+| **Env / secrets** | Which vars come from where — never values in git |
+| **Deploy unit** | Container service, Helm release, worker + broker |
+| **CI** | Workflow or command that must pass before merge |
+| **Rollback** | How to undo a bad deploy |
+| **Observability** | Logs, metrics, alerts minimum for this change |
+
+Gate requires **Deploy unit**, **CI**, and **Rollback** non-empty when infra globs match task `Files`.
+
+## Procedure
+
+1. **Reuse existing infra** — extend compose/terraform/chart before inventing parallel paths.
+2. **Migration before deploy** — document order in tasks; gate does not run migrations.
+3. **Quality checks** — uncomment matching lines in `quality.checks` (`docker compose config`, `terraform validate`, `helm template`).
+4. **Before Verify** — run `validate_ship_surface.py`; fix `design.md` on FAIL.
+5. **Owner tiers** — local commits are Tier 0; push/deploy need explicit go-ahead (`git-handoff.md`).
+
+## Anti-patterns
+
+- Tasks touch `docker-compose.yml` but `design.md` has no Ship Surface
+- Rollback = "revert commit" with no deploy-specific steps
+- Secrets in spec or design artifacts
+- Skipping CI gate in tasks when compose/terraform changed
+
+## Related
+
+- `docs/guide/python-platform.md` — full platform map
+- `ai-engineering.md` — when the same feature also touches LLM/RAG/MCP paths
+- `references/design.md` — Ship Surface template
+- `ship-ready.md` — after Verify PASS, when owner asks to go live

package/skills/references/design.md

@@ -75,11 +75,40 @@ Skipping Design is the default for Simple and Medium tiers.
 
 ## Out of Scope for This Design
 - [explicitly excluded]
+
+## Ship Surface
+
+Fill when tasks touch infra paths (Docker, Compose, Terraform, Helm, CI workflows). Required fields for the gate: **Deploy unit**, **CI**, **Rollback**.
+
+| Field | Value |
+| --- | --- |
+| API / contract | OpenAPI path, health route, or N/A (worker/CLI) |
+| Migrations | Command or N/A |
+| Env / secrets | Source of config — no secret values |
+| Deploy unit | Service/chart/worker unit that ships |
+| CI | Workflow or command before merge |
+| Rollback | How to undo a bad deploy |
+| Observability | Logs/metrics/alerts for this change |
+
+## AI Surface
+
+Fill when tasks touch AI paths (`prompts/`, `evals/`, MCP, embeddings, LLM/RAG code). Required fields for the gate: **Eval harness**, **Fallback / degrade**.
+
+| Field | Value |
+| --- | --- |
+| Capability | chat, RAG, tool-use, embed batch, etc. |
+| Model / provider | Model name — no API keys |
+| Tools / MCP scope | Allowlist / deny list |
+| Eval harness | `pytest tests/eval/` or dataset path |
+| PII / data policy | What must not reach the model |
+| Fallback / degrade | Behavior on timeout/failure/rate limit |
+| Cost guard | Budget link or execution-policy note |
 ```
 
 ## Rules
 
 - No implementation code in `design.md` — interfaces and signatures only when they clarify a contract.
+- If tasks touch infra or AI `Files`, run `validate_ship_surface.py` after Tasks and before Verify.
 - If the design reveals that the spec is wrong or incomplete, stop and update `spec.md` first; re-run the spec gate.
 - When multiple defensible implementations exist for the same spec, use explicit **solution exploration** (`references/solution-exploration.md`) before Execute — not parallel ad-hoc spikes.
 - Prefer the smallest design that satisfies the spec. Extensibility that no requirement asks for is speculation.

package/skills/references/implement.md

@@ -24,6 +24,7 @@ Orchestrate tasks from `tasks.md` and `task-graph.md`: **parallel waves with sub
 1. Read this file completely.
 2. **Discover this repo’s test command** from `package.json`, `Makefile`, CI, or README — prefer the focused command the task `Gate` names. Do not assume `npm test` if the project uses another runner.
 3. Run `python3 .specs/guardrails/scripts/validate_tasks.py` when a formal `tasks.md` exists.
+4. When tasks touch infra or AI `Files`, run `validate_ship_surface.py` before the first Execute edit on those paths.
 4. If Tasks was skipped, list the atomic steps inline now. More than 5 steps or real dependencies means the Tasks phase was skipped in error — stop and create `tasks.md`.
 5. **Plan the wave** — run `python3 .specs/guardrails/scripts/loop_plan.py [feature]` (or `loop-plan --json`) at the start of Execute and after every batch completes. It lists the next runnable tasks and marks **parallel groups** (disjoint `Files`) vs inline work.
 6. When `loop-plan` shows a **parallel group** (2+ tasks), prepare isolated workspaces before dispatch:

package/skills/references/tasks.md

@@ -46,6 +46,14 @@ Break the work into atomic tasks with real dependencies and binary done criteria
    python3 .specs/guardrails/scripts/validate_tasks.py [feature]
    ```
 
+**Ship / AI surfaces.** When task `Files` touch infra or AI paths (see `python-platform` preset globs), ensure `design.md` includes **Ship Surface** and/or **AI Surface** before approval. Run:
+
+```bash
+python3 .specs/guardrails/scripts/validate_ship_surface.py [feature]
+```
+
+Load `python-devops.md` or `ai-engineering.md` sister skills when those paths apply.
+
 **Authoring vs gate.** `validate_tasks.py` already enforces REQ coverage and `Tests`/`Gate` fields. The matrix and Gate Check Commands sections are an owner/verifier checklist (judgment) until a future form gate — do not skip them when Tasks ran.
 
 ## Gate

package/skills/references/validate.md

@@ -110,12 +110,15 @@ The completion gate searches for `file:line` (for example `test/routes/login.tes
 ## Gate
 
 ```bash
+python3 .specs/guardrails/scripts/validate_ship_surface.py [feature]   # when infra/AI paths in tasks
 python3 .specs/guardrails/scripts/validate_state.py .specs/features/[feature]
 python3 .specs/guardrails/scripts/validate_state.py [feature]
 python3 .specs/guardrails/scripts/validate_state.py          # single-feature projects
 npx @luizsantiago/spec-guardrails quality-checks             # when quality.checks is configured
 ```
 
+**Ship / AI surfaces (python-platform).** When `design.md` documents Ship or AI Surface, cite deploy/eval evidence in the report (CI workflow path, eval command output, or `file:line` from `tests/eval/`). `validate_ship_surface.py` checks design structure only — not eval quality or deploy safety.
+
 Checks that the report exists, the verdict is exactly PASS in the **preamble** (before the first `##` section) or under a dedicated `## Verdict` / `## Result` / `## Status` heading, every spec requirement ID shares a line with test `file:line` evidence, and no task remains open. A `- Verdict: PASS` buried under Discrimination Sensor or Coverage does not count. Preamble and `## Verdict` must not disagree. Evidence inside fenced samples or HTML comments does not count. `PASS` with any surviving mutant on a sensor/mutant line fails. `PASS` with open `Gaps` bullets or Security Review `Result: fail` fails. On Medium+ features (`design.md` with content, 4+ tasks, or 2+ phases) a discrimination-sensor **outcome** is **blocking** — the section heading alone is not enough — and a Medium+ `PASS` requires at least one `killed` mutant in the sensor focus (`injected` alone, or `killed` only under Gaps, is not enough). Below Medium+ a missing outcome is a warning (`--strict` still promotes warnings). Non-zero exit means the feature is not done.
 
 The gate cannot judge whether a cited test actually asserts the criterion. Run `quality-checks` when `.specs/config.yaml` lists project commands (`npm test`, …) and cite the passing output in the validation report. That judgment is still the verifier's; a green gate with a weak assertion is still a FAIL in the report.

package/templates/config.yaml.example

@@ -4,8 +4,8 @@
 
 schema: spec-driven
 
-# Extend a built-in preset (default | node-ts | python):
-# extends: node-ts
+# Extend a built-in preset (default | node-ts | python | python-platform):
+# extends: python-platform
 
 context: |
   Tech stack: (fill in)
@@ -101,6 +101,17 @@ quality:
   checks:
     - npm test
 
+# Ship / AI surface globs (optional — used by validate_ship_surface.py)
+# ship_surface:
+#   infra_globs:
+#     - "**/Dockerfile"
+#     - "**/docker-compose*.yml"
+#     - "**/.github/workflows/**"
+#   ai_globs:
+#     - "**/prompts/**"
+#     - "**/evals/**"
+#     - "**/tests/eval/**"
+
 # Commit policy (optional — used with check-commit --staged)
 commit:
   max_staged_lines: 500

package/templates/presets/python-platform.yaml

@@ -0,0 +1,78 @@
+# Python platform preset — backend + DevOps + AI engineering
+# See docs/guide/python-platform.md for capabilities and limitations.
+schema: spec-driven
+
+branch_prefix: feat
+
+extends: python
+
+context: |
+  Stack: Python 3.10+ (framework-agnostic — FastAPI, Django, workers, or plain modules)
+  Test command: pytest
+  Lint: ruff check .
+  Branch prefix: feat
+  DevOps: docker compose config, terraform validate, helm template (enable in quality.checks)
+  AI: run eval suite when AI Surface is present in design.md
+  Ship/AI surfaces: document in design.md; gate validate_ship_surface.py enforces structure
+
+rules:
+  specify:
+    - Prefer EARS acceptance criteria
+    - Mark unknowns with [NEEDS CLARIFICATION: question]
+    - For model behavior, write testable criteria (golden set, bounds) — not only HTTP 200
+  tasks:
+    - Every REQ must appear in the Test Coverage Matrix
+    - Gate Check Commands must include pytest
+    - When Files touch infra or AI paths, design.md must include Ship Surface and/or AI Surface
+  implement:
+    - Run pytest before each commit
+    - Run infra/AI quality checks from quality.checks when the task Gate references them
+  verify:
+    - Evidence must cite test file:line paths under tests/
+    - When AI Surface exists, validation.md must cite eval evidence (file:line or command output)
+    - Run validate_ship_surface before validate_state when tasks touch infra or AI paths
+
+elicitation:
+  max_questions_per_turn: 5
+  kickoff_discovery_paths:
+    - prd.md
+    - docs/brief.md
+    - docs/prd.md
+    - .specs/project/kickoff.md
+    - docs/ai-brief.md
+
+memory:
+  retrieval:
+  # Semantic search is optional — enable after `memory-index embed` when the team wants it.
+    semantic: false
+    provider: none
+    model: text-embedding-3-small
+
+quality:
+  checks:
+    - pytest
+    - ruff check .
+    # Uncomment the checks your repo uses:
+    # - docker compose config --quiet
+    # - terraform -chdir=infra validate
+    # - helm template release ./charts/app
+    # - pytest tests/eval -m "not live"
+
+ship_surface:
+  infra_globs:
+    - "**/Dockerfile"
+    - "**/docker-compose*.yml"
+    - "**/docker-compose*.yaml"
+    - "**/terraform/**"
+    - "**/*.tf"
+    - "**/charts/**"
+    - "**/helm/**"
+    - "**/.github/workflows/**"
+  ai_globs:
+    - "**/prompts/**"
+    - "**/mcp/**"
+    - "**/evals/**"
+    - "**/tests/eval/**"
+    - "**/*embed*"
+    - "**/*llm*"
+    - "**/*rag*"