superdev-cli 0.1.0

package/skills/docs/scripts/profile-detect.mjs

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+/**
+ * Documentation-profile detection with evidence and confidence.
+ * Never guesses silently: low confidence is reported as such; an adapter, when
+ * present, is authoritative. Read-only; writes only with an explicit --out.
+ *
+ * Exit codes: 0 detection completed (including "none"), 2 usage error.
+ */
+import { parseArgs } from "node:util";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const USAGE = `Usage: node profile-detect.mjs [--root <path>] [--json] [--out <file>] [--help]
+  --root <path>  project root to inspect (default: current directory)
+  --json         machine-readable JSON on stdout
+  --out <file>   also write the JSON report to this exact path
+  --help         show this help`;
+
+/** Minimal YAML subset reader for the talks adapter: nested "key: value" maps,
+ *  block and flow string lists, inline comments. The adapter file format is
+ *  owned by this project and stays inside this documented subset; content
+ *  outside the subset is ignored rather than misparsed into other keys. */
+export function readYamlSubset(text) {
+  const root = {};
+  // Each frame: the map receiving keys at deeper indents, plus (for empty-value
+  // keys) where that map hangs, so list items can convert it into an array.
+  const stack = [{ indent: -1, node: root, parentNode: null, key: null }];
+  for (const raw of text.split(/\r?\n/)) {
+    if (!raw.trim() || raw.trim().startsWith("#")) continue;
+    const indent = raw.length - raw.trimStart().length;
+    const line = raw.trim();
+    const isList = /^-\s+/.test(line);
+    // List items may sit at the same indent as their key; keys at that indent
+    // close the frame. Hence strict "<" for list lines, "<=" for key lines.
+    while (
+      stack.length > 1 &&
+      (isList ? indent < stack[stack.length - 1].indent : indent <= stack[stack.length - 1].indent)
+    )
+      stack.pop();
+    const frame = stack[stack.length - 1];
+    if (isList) {
+      const item = line.replace(/^-\s+/, "");
+      if (frame.parentNode && frame.key) {
+        if (!Array.isArray(frame.parentNode[frame.key])) frame.parentNode[frame.key] = [];
+        frame.parentNode[frame.key].push(stripQuotes(stripComment(item)));
+      }
+      continue;
+    }
+    const kv = line.match(/^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (!kv) continue;
+    const [, key, rawValue] = kv;
+    const value = stripComment(rawValue);
+    if (value === "") {
+      frame.node[key] = {};
+      stack.push({ indent, node: frame.node[key], parentNode: frame.node, key });
+    } else if (value.startsWith("[") && value.endsWith("]")) {
+      frame.node[key] = value
+        .slice(1, -1)
+        .split(",")
+        .map((s) => stripQuotes(s.trim()))
+        .filter(Boolean);
+    } else {
+      frame.node[key] = stripQuotes(value);
+    }
+  }
+  return root;
+}
+
+/** Inline comments on unquoted values: `talks-v1 # note` → `talks-v1`. */
+function stripComment(value) {
+  if (/^["']/.test(value)) return value;
+  return value.replace(/\s+#.*$/, "").trim();
+}
+
+function stripQuotes(s) {
+  const m = s.match(/^["'](.*)["']$/);
+  return m ? m[1] : s;
+}
+
+function exists(...parts) {
+  return fs.existsSync(path.join(...parts));
+}
+
+function dirNames(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+    .map((e) => e.name);
+}
+
+const TYPE_FOLDERS = ["features", "apis", "api", "data", "database", "workflows", "schemas"];
+const DOCS_ROOT_CANDIDATES = ["docs/project", "docs", "documentation"];
+
+/** First docs-root candidate that exists - used so adapter-declared profiles
+ *  still learn where documentation lives when canonicalRoot is omitted. */
+function findDocsRoot(root) {
+  for (const candidate of DOCS_ROOT_CANDIDATES) {
+    if (fs.existsSync(path.join(root, candidate))) return candidate;
+  }
+  return null;
+}
+
+export function detectProfile(root) {
+  const evidence = [];
+  const adapterPath = path.join(root, "talks", "project.yaml");
+  if (fs.existsSync(adapterPath)) {
+    const adapter = readYamlSubset(fs.readFileSync(adapterPath, "utf8"));
+    const profile = adapter.docs?.profile;
+    if (profile) {
+      evidence.push({ what: "adapter declares profile", where: "talks/project.yaml" });
+      const docsRoot = adapter.docs?.canonicalRoot ?? findDocsRoot(root);
+      return { profile, confidence: "high", source: "adapter", evidence, adapter, docsRoot };
+    }
+    evidence.push({ what: "adapter present without docs.profile", where: "talks/project.yaml" });
+  }
+
+  if (exists(root, "talks", "state", "schema-version.json")) {
+    evidence.push({ what: "talks/state/schema-version.json present", where: "talks/state/schema-version.json" });
+    return { profile: "talks-v1", confidence: "high", source: "structure", evidence, docsRoot: "talks" };
+  }
+
+  for (const candidate of DOCS_ROOT_CANDIDATES) {
+    const docsRoot = path.join(root, candidate);
+    if (!fs.existsSync(docsRoot)) continue;
+
+    const modulesDir = path.join(docsRoot, "modules");
+    const moduleDirs = dirNames(modulesDir);
+    const registered = moduleDirs.filter((m) => exists(modulesDir, m, "module.md"));
+    if (registered.length) {
+      evidence.push({ what: `modules root with ${registered.length} registered module(s)`, where: path.relative(root, modulesDir) });
+      return { profile: "module-docs", confidence: "high", source: "structure", evidence, docsRoot: candidate };
+    }
+    if (moduleDirs.length) {
+      evidence.push({ what: "modules folder present but no module.md registrations", where: path.relative(root, modulesDir) });
+      return { profile: "module-docs", confidence: "low", source: "structure", evidence, docsRoot: candidate };
+    }
+
+    const typeFolders = dirNames(docsRoot).filter((d) => TYPE_FOLDERS.includes(d));
+    if (typeFolders.length >= 2) {
+      evidence.push({ what: `sibling type folders: ${typeFolders.join(", ")}`, where: candidate });
+      return { profile: "legacy-flat-docs", confidence: "medium", source: "structure", evidence, docsRoot: candidate };
+    }
+
+    const mdFiles = fs.readdirSync(docsRoot).filter((f) => f.endsWith(".md"));
+    if (mdFiles.length || dirNames(docsRoot).length) {
+      evidence.push({ what: "documentation present matching no known profile", where: candidate });
+      return { profile: "custom", confidence: "low", source: "structure", evidence, docsRoot: candidate };
+    }
+  }
+
+  evidence.push({ what: "no documentation structure found", where: "." });
+  return { profile: "none", confidence: "high", source: "structure", evidence };
+}
+
+/** Workspace-aware dependency inventory: root manifest plus every workspace
+ *  member. Supported declaration shapes (documented safe subset):
+ *   - npm/yarn `workspaces` as an array, or an object with a `packages` array
+ *   - pnpm-workspace.yaml `packages` list
+ *   - exact member paths ("services/api") at any depth
+ *   - one trailing-level globs ("packages/*", "apps/web/plugins/*")
+ *  Anything else (multi-star, "**", mid-path stars, traversal, absolute paths,
+ *  non-string entries, malformed declarations) is NEVER silently ignored - it
+ *  is reported in `unsupported` so callers can surface incomplete inspection. */
+export function dependencyInventory(root) {
+  const packages = [];
+  const unsupported = [];
+  const seen = new Set();
+  const rootPkgPath = path.join(root, "package.json");
+  if (!fs.existsSync(rootPkgPath)) return { packages, unsupported };
+  const readPkg = (p, rel) => {
+    const resolved = path.resolve(p);
+    if (seen.has(resolved)) return null;
+    seen.add(resolved);
+    try {
+      const pkg = JSON.parse(fs.readFileSync(p, "utf8"));
+      packages.push({
+        path: rel.split(path.sep).join("/"),
+        name: pkg.name ?? rel,
+        dependencies: Object.keys({ ...pkg.dependencies, ...pkg.devDependencies }),
+        scripts: pkg.scripts ?? {},
+      });
+      return pkg;
+    } catch {
+      unsupported.push({ pattern: rel, reason: "unreadable or malformed package manifest" });
+      return null;
+    }
+  };
+  const rootPkg = readPkg(rootPkgPath, "package.json");
+  const globs = [];
+  const ws = rootPkg?.workspaces;
+  if (Array.isArray(ws)) globs.push(...ws);
+  else if (ws && typeof ws === "object" && Array.isArray(ws.packages)) globs.push(...ws.packages);
+  else if (ws !== undefined) unsupported.push({ pattern: String(ws), reason: "malformed workspaces declaration" });
+  const pnpmWs = path.join(root, "pnpm-workspace.yaml");
+  if (fs.existsSync(pnpmWs)) {
+    const y = readYamlSubset(fs.readFileSync(pnpmWs, "utf8"));
+    if (Array.isArray(y.packages)) globs.push(...y.packages);
+    else if (y.packages !== undefined) unsupported.push({ pattern: "pnpm-workspace.yaml#packages", reason: "malformed packages declaration" });
+  }
+  for (const glob of globs) {
+    if (typeof glob !== "string" || !glob.trim()) {
+      unsupported.push({ pattern: String(glob), reason: "non-string workspace entry" });
+      continue;
+    }
+    const g = glob.replace(/^\.\//, "").replace(/\/$/, "");
+    if (path.isAbsolute(g) || /^[A-Za-z]:[\\/]/.test(g) || g.split(/[\\/]/).includes("..")) {
+      unsupported.push({ pattern: g, reason: "absolute or traversing workspace path rejected" });
+      continue;
+    }
+    const stars = (g.match(/\*/g) ?? []).length;
+    if (stars === 0) {
+      const p = path.join(root, g, "package.json");
+      if (fs.existsSync(p)) readPkg(p, path.join(g, "package.json"));
+      continue;
+    }
+    if (stars === 1 && g.endsWith("/*")) {
+      const base = g.slice(0, -2);
+      for (const member of dirNames(path.join(root, base))) {
+        const p = path.join(root, base, member, "package.json");
+        if (fs.existsSync(p)) readPkg(p, path.join(base, member, "package.json"));
+      }
+      continue;
+    }
+    unsupported.push({ pattern: g, reason: "unsupported glob shape (supported: exact paths and one trailing '/*')" });
+  }
+  return { packages, unsupported };
+}
+
+/** Presence-only environment markers; never opens or decrypts anything. */
+export function envMarkers(root) {
+  const markers = [];
+  let entries = [];
+  try {
+    entries = fs.readdirSync(root);
+  } catch {
+    return markers;
+  }
+  for (const name of entries) {
+    if (/^\.env.*\.gpg$/.test(name) || name === ".envxrc") markers.push({ kind: "envx", file: name });
+    else if (/^\.env\.(example|template|sample)$/.test(name)) markers.push({ kind: "conventional-example", file: name });
+    else if (/^\.env(\..+)?$/.test(name)) markers.push({ kind: "conventional", file: name });
+  }
+  return markers;
+}
+
+function main() {
+  let args;
+  try {
+    args = parseArgs({
+      options: {
+        root: { type: "string", default: "." },
+        json: { type: "boolean", default: false },
+        out: { type: "string" },
+        help: { type: "boolean", default: false },
+      },
+      allowPositionals: false,
+    }).values;
+  } catch (err) {
+    console.error(String(err.message ?? err));
+    console.error(USAGE);
+    process.exit(2);
+  }
+  if (args.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  if (!fs.existsSync(args.root) || !fs.statSync(args.root).isDirectory()) {
+    console.error(`root is not a directory: ${args.root}`);
+    console.error(USAGE);
+    process.exit(2);
+  }
+  const report = {
+    version: 1,
+    ...detectProfile(args.root),
+    workspace: dependencyInventory(args.root),
+    envMarkers: envMarkers(args.root),
+  };
+  if (args.json) console.log(JSON.stringify(report, null, 2));
+  else {
+    console.log(`profile: ${report.profile} (confidence: ${report.confidence}, source: ${report.source})`);
+    for (const e of report.evidence) console.log(`  evidence: ${e.what} [${e.where}]`);
+    console.log(`workspace packages: ${report.workspace.packages.length}`);
+    if (report.envMarkers.length) console.log(`env markers: ${report.envMarkers.map((m) => m.kind).join(", ")}`);
+  }
+  if (args.out) {
+    const outDir = path.dirname(path.resolve(args.out));
+    const tmpOut = path.join(outDir, `.tmp-report-${process.pid}`);
+    fs.mkdirSync(outDir, { recursive: true });
+    fs.writeFileSync(tmpOut, JSON.stringify(report, null, 2) + "\n");
+    fs.renameSync(tmpOut, path.resolve(args.out));
+  }
+  process.exit(0);
+}
+
+// Main-module guard: realpath both sides - Node resolves symlinks (e.g. /tmp
+// on macOS) when building import.meta.url for the entry module.
+if (process.argv[1] && import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href) main();

package/skills/docs/scripts/screen.mjs

@@ -0,0 +1,96 @@
+/**
+ * Source-material screening (library, not a CLI): secret-shaped values,
+ * credential URLs, key material, PII shapes, prompt-injection shapes,
+ * executable-instruction shapes, and unsupported authority claims.
+ *
+ * Defense in depth, stated honestly: these detectors are tripwires that catch
+ * known shapes - they do not prove absence. The PRIMARY control is structural:
+ * ingested content is never executed and never treated as instructions,
+ * whether or not a detector fires.
+ *
+ * Safety: findings carry stable codes, severity, and span coordinates.
+ * Sensitive matches (secrets/PII) NEVER include the matched excerpt; injection
+ * and authority matches may carry a short quoted excerpt as evidence - they are
+ * quotes of untrusted data, never directives.
+ */
+
+const SENSITIVE_RULES = [
+  { code: "SCR-KEY", severity: "P0", re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
+  { code: "SCR-SECRET", severity: "P0", re: /\b[A-Za-z0-9_]*(?:password|passwd|secret|token|api[_-]?key|credential)[A-Za-z0-9_]*s?\s*[:=]\s*["']?[^\s"']{6,}/i },
+  { code: "SCR-URLCRED", severity: "P0", re: /:\/\/[^/\s:@]+:[^@\s]{4,}@/ },
+  { code: "SCR-JWT", severity: "P0", re: /\beyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{10,}/ },
+  { code: "SCR-PII-EMAIL", severity: "P1", re: /[A-Za-z0-9._%+-]+@(?!example\.(?:com|org|net))[A-Za-z0-9.-]+\.[A-Za-z]{2,}/ },
+  { code: "SCR-PII-PHONE", severity: "P1", re: /(?:^|\s)\+?\d{1,3}[-. (]{1,2}\d{3}[-. )]{1,2}\d{3}[-. ]?\d{4}\b/ },
+];
+
+const EVIDENCE_RULES = [
+  { code: "SCR-INJECT", severity: "P0", re: /ignore\s+(?:all\s+)?(?:previous|prior|above)\s+instructions|disregard\s+(?:your|all)\s+(?:instructions|rules)|you\s+are\s+now\s+(?:a|an|in)\b|<\/?system>|\[system\]|jailbreak/i },
+  { code: "SCR-EXEC", severity: "P0", re: /^\s*(?:\$|#|>)\s*(?:rm|curl|wget|bash|sh|eval|sudo)\b|```(?:bash|sh|shell)[\s\S]{0,40}\b(?:rm -|curl |wget )|"tool_call"|"function_call"|<tool_use>/im },
+  { code: "SCR-AUTHORITY", severity: "P1", re: /\b(?:the\s+)?(?:CEO|CTO|CFO|legal(?:\s+team)?|compliance(?:\s+team)?|board)\s+(?:has\s+)?(?:decided|approved|requires|mandated|signed\s+off)|\blegally\s+required\b|\bregulation\s+requires\b/i },
+];
+
+/** Screen text; returns findings with line/span coordinates. Sensitive rules
+ *  never echo the excerpt; evidence rules carry a bounded quote. */
+export function screenText(text) {
+  const findings = [];
+  const lines = text.split("\n");
+  let offset = 0;
+  lines.forEach((line, i) => {
+    for (const rule of SENSITIVE_RULES) {
+      const m = rule.re.exec(line);
+      if (m) findings.push({ code: rule.code, severity: rule.severity, line: i + 1, span: { start: offset + m.index, length: m[0].length } });
+      rule.re.lastIndex = 0;
+    }
+    for (const rule of EVIDENCE_RULES) {
+      const m = rule.re.exec(line);
+      if (m)
+        findings.push({
+          code: rule.code, severity: rule.severity, line: i + 1,
+          span: { start: offset + m.index, length: m[0].length },
+          quotedEvidence: m[0].slice(0, 120),
+        });
+      rule.re.lastIndex = 0;
+    }
+    offset += line.length + 1;
+  });
+  // Multi-line EXEC shapes (fenced blocks) checked against the whole text once.
+  const fence = /```(?:bash|sh|shell)[\s\S]{0,200}?```/g;
+  let fm;
+  while ((fm = fence.exec(text))) {
+    if (/\b(?:rm -rf|curl |wget |sudo )/.test(fm[0]))
+      findings.push({ code: "SCR-EXEC", severity: "P0", line: text.slice(0, fm.index).split("\n").length, span: { start: fm.index, length: fm[0].length }, quotedEvidence: "fenced shell block with destructive/network commands" });
+  }
+  return findings;
+}
+
+const BINARY_EXTENSIONS = new Set([".exe", ".dll", ".so", ".dylib", ".bin", ".o", ".class", ".jar", ".wasm", ".app", ".msi", ".sh", ".bat", ".cmd", ".ps1"]);
+export const MAX_SOURCE_BYTES = 2 * 1024 * 1024; // boundary, reported not guessed
+
+// Codes whose matched value is sensitive and must NEVER be excerpted, stored,
+// or echoed anywhere (secrets AND PII - the latter is P1 by report severity but
+// sensitive for persistence). Injection/exec/authority are NOT here: those are
+// facts about source data, carried as bounded quoted evidence.
+export const SENSITIVE_CODES = new Set(["SCR-KEY", "SCR-SECRET", "SCR-URLCRED", "SCR-JWT", "SCR-PII-EMAIL", "SCR-PII-PHONE"]);
+
+/** True if a text value carries any sensitive (secret/PII) shape. */
+export function hasSensitive(text) {
+  return screenText(String(text)).some((f) => SENSITIVE_CODES.has(f.code));
+}
+
+/** Intake safety on raw bytes: executables/unsupported/oversize/malformed. */
+export function screenIntake(name, buf) {
+  const findings = [];
+  const ext = name.slice(name.lastIndexOf(".")).toLowerCase();
+  if (BINARY_EXTENSIONS.has(ext)) findings.push({ code: "SCR-EXECUTABLE", severity: "P0", detail: "executable or script file - rejected from extraction; never executed" });
+  if (buf.length > MAX_SOURCE_BYTES) findings.push({ code: "SCR-OVERSIZE", severity: "P1", detail: `exceeds ${MAX_SOURCE_BYTES} byte boundary` });
+  const probe = buf.subarray(0, 8000);
+  if (probe.includes(0)) findings.push({ code: "SCR-BINARY", severity: "P1", detail: "binary content - inventoried but not extracted" });
+  else {
+    try {
+      new TextDecoder("utf-8", { fatal: true }).decode(probe);
+    } catch {
+      findings.push({ code: "SCR-ENCODING", severity: "P1", detail: "malformed text encoding - inventoried but not extracted" });
+    }
+  }
+  return findings;
+}

package/skills/docs/scripts/template-lint.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * Template neutrality lint: checks universal templates and capability fragments
+ * against known vendor, latency, cloud-region, compliance-regime, and env-var
+ * patterns. A denylist scan - it catches known violations; it does not prove
+ * absence. Placeholders ({{...}}) and HTML comments are exempt.
+ *
+ * Finding codes:
+ *  TL-001 P0 concrete latency/availability number
+ *  TL-002 P0 cloud region identifier
+ *  TL-003 P0 concrete compliance regime asserted
+ *  TL-004 P1 concrete environment-variable name
+ *  TL-005 P0 vendor/product name
+ *
+ * Exit codes: 0 clean, 1 findings, 2 usage error.
+ */
+import { parseArgs } from "node:util";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const USAGE = `Usage: node template-lint.mjs [--dir <path>] [--json] [--out <file>] [--help]
+  --dir <path>  assets directory to lint (default: the skill's own assets/)
+  --json        machine-readable JSON on stdout
+  --out <file>  also write the JSON report to this exact path
+  --help        show this help`;
+
+/** Shared CLI reporting contract: --out writes exactly the machine-readable
+ *  report, atomically, with a trailing newline; no --out, no report file. */
+function writeReport(outPath, report) {
+  if (!outPath) return;
+  const dir = path.dirname(path.resolve(outPath));
+  const tmp = path.join(dir, `.tmp-report-${process.pid}`);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(tmp, JSON.stringify(report, null, 2) + "\n");
+  fs.renameSync(tmp, path.resolve(outPath));
+}
+
+// Public product names that must never be baked into neutral templates.
+// (Naming them here is the enforcement mechanism, not an endorsement or a leak -
+// these are all public products.) "envx" is excluded: it is a declared external
+// provider (see the repository's references/provider-contracts.md).
+const VENDORS =
+  /\b(aws|amazon|azure|gcp|vercel|netlify|heroku|cloudflare|firebase|supabase|stripe|paypal|razorpay|twilio|sendgrid|mailgun|postmark|postgres(?:ql)?|mysql|mariadb|mongodb|dynamodb|redis|kafka|rabbitmq|sqs|auth0|okta|cognito|keycloak|sentry|datadog|posthog|mixpanel|amplitude|segment|launchdarkly|algolia|elasticsearch|next\.?js|react|vue|angular|svelte|drizzle|prisma|hasura|graphql-yoga|expo)\b/i;
+const LATENCY = /\b\d+(?:\.\d+)?\s?(?:ms|milliseconds|seconds?)\b|\b\d{2}\.\d+\s?%|\b99\.\d+\b/;
+// Region shapes: AWS-style (us-east-1), GCP-style (us-central1, europe-west1),
+// Azure-style (westus2, northeurope).
+const REGION =
+  /\b(?:us|eu|ap|sa|ca|me|af)-(?:east|west|north|south|central|northeast|southeast|southwest|northwest)-\d\b|\b(?:us|europe|asia|australia|northamerica|southamerica)-(?:east|west|north|south|central)\d\b|\b(?:east|west|north|south|central)(?:us|europe|asia)\d?\b/i;
+const REGIME = /\b(GDPR|HIPAA|CCPA|CPRA|DPDP|PCI[- ]?DSS|SOC\s?2|ISO\s?27001|FedRAMP|COPPA|FERPA)\b/;
+const ENVVAR = /\b[A-Z][A-Z0-9]{1,}(?:_[A-Z0-9]+){1,}\b/;
+
+export function stripExempt(text) {
+  return text.replace(/<!--[\s\S]*?-->/g, "").replace(/\{\{[^}]*\}\}/g, "");
+}
+
+export function lintFile(relFile, text) {
+  const findings = [];
+  const lines = text.split("\n");
+  let inComment = false;
+  lines.forEach((rawLine, i) => {
+    let line = rawLine;
+    if (inComment) {
+      const end = line.indexOf("-->");
+      if (end === -1) return;
+      line = line.slice(end + 3);
+      inComment = false;
+    }
+    line = line.replace(/<!--[\s\S]*?-->/g, "");
+    const open = line.indexOf("<!--");
+    if (open !== -1) {
+      line = line.slice(0, open);
+      inComment = true;
+    }
+    line = line.replace(/\{\{[^}]*\}\}/g, "");
+    const loc = { file: relFile, line: i + 1 };
+    if (LATENCY.test(line)) findings.push({ ruleId: "TL-001", severity: "P0", ...loc, detail: "concrete latency/availability number" });
+    if (REGION.test(line)) findings.push({ ruleId: "TL-002", severity: "P0", ...loc, detail: "cloud region identifier" });
+    if (REGIME.test(line)) findings.push({ ruleId: "TL-003", severity: "P0", ...loc, detail: "concrete compliance regime" });
+    if (ENVVAR.test(line)) findings.push({ ruleId: "TL-004", severity: "P1", ...loc, detail: "concrete env-var name" });
+    if (VENDORS.test(line)) findings.push({ ruleId: "TL-005", severity: "P0", ...loc, detail: "vendor/product name" });
+  });
+  return findings;
+}
+
+export function lintDir(assetsDir) {
+  const findings = [];
+  const stack = [assetsDir];
+  while (stack.length) {
+    const dir = stack.pop();
+    if (!fs.existsSync(dir)) continue;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) stack.push(full);
+      else if (entry.name.endsWith(".md"))
+        findings.push(...lintFile(path.relative(assetsDir, full), fs.readFileSync(full, "utf8")));
+    }
+  }
+  return findings;
+}
+
+function main() {
+  let args;
+  try {
+    args = parseArgs({
+      options: {
+        dir: { type: "string" },
+        json: { type: "boolean", default: false },
+        out: { type: "string" },
+        help: { type: "boolean", default: false },
+      },
+      allowPositionals: false,
+    }).values;
+  } catch (err) {
+    console.error(String(err.message ?? err));
+    console.error(USAGE);
+    process.exit(2);
+  }
+  if (args.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  const assetsDir = args.dir ?? path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "assets");
+  if (!fs.existsSync(assetsDir) || !fs.statSync(assetsDir).isDirectory()) {
+    console.error(`assets directory not found: ${assetsDir}`);
+    console.error(USAGE);
+    process.exit(2);
+  }
+  const findings = lintDir(assetsDir);
+  const report = { version: 1, dir: path.resolve(assetsDir), count: findings.length, findings };
+  if (args.json) console.log(JSON.stringify(report, null, 2));
+  else {
+    console.log(`template lint - ${findings.length} finding(s)`);
+    for (const f of findings) console.log(`  [${f.severity}] ${f.ruleId} ${f.file}:${f.line} - ${f.detail}`);
+    if (!findings.length) console.log("  clean");
+  }
+  writeReport(args.out, report);
+  process.exit(findings.length ? 1 : 0);
+}
+
+// Main-module guard: realpath both sides - Node resolves symlinks (e.g. /tmp
+// on macOS) when building import.meta.url for the entry module.
+if (process.argv[1] && import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href) main();