sentinelayer-cli 0.6.2 → 0.8.1

package/src/agents/observability/tools/log-schema-check.js

@@ -0,0 +1,74 @@
+// log-schema-check — flag console.log in production code paths (#A20).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, findLineMatches, getLineContent, toPosix, walkRepoFiles } from "./base.js";
+
+const CODE_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".py"]);
+
+function isProductionSource(relPath) {
+  const p = toPosix(relPath);
+  if (/(^|\/)(tests?|__tests__|specs?)\//.test(p)) return false;
+  if (/\.(test|spec)\.(js|jsx|ts|tsx|mjs|cjs|py)$/.test(p)) return false;
+  if (/(^|\/)scripts\//.test(p)) return false;
+  if (/(^|\/)bin\//.test(p)) return false;
+  if (/(^|\/)docs?\//.test(p)) return false;
+  return true;
+}
+
+const UNSTRUCTURED_LOG_PATTERNS_JS = /\bconsole\.(log|info|warn|error|debug)\s*\(/;
+const UNSTRUCTURED_LOG_PATTERNS_PY = /\bprint\s*\(/;
+
+export async function runLogSchemaCheck({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions: CODE_EXTENSIONS });
+
+  const findings = [];
+  const reported = new Set();
+  for await (const { fullPath, relativePath } of iterator) {
+    if (!isProductionSource(relativePath)) continue;
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const ext = path.extname(fullPath).toLowerCase();
+    const pattern = ext === ".py" ? UNSTRUCTURED_LOG_PATTERNS_PY : UNSTRUCTURED_LOG_PATTERNS_JS;
+    const matches = findLineMatches(content, pattern);
+    if (matches.length === 0) continue;
+    const rel = toPosix(relativePath);
+    if (reported.has(rel)) continue;
+    reported.add(rel);
+    findings.push(
+      createFinding({
+        tool: "log-schema-check",
+        kind: "observability.unstructured-log",
+        severity: "P3",
+        file: rel,
+        line: matches[0].line,
+        evidence: getLineContent(content, matches[0].line),
+        rootCause: "Production code uses console.log / print() — unindexed output that can't be queried, correlated, or redacted at collection time.",
+        recommendedFix: "Route through a structured logger (pino, winston, structlog) with a shared schema. Configure PII fields to be automatically redacted.",
+        confidence: 0.55,
+      })
+    );
+  }
+  return findings;
+}
+
+async function* iterateExplicitFiles(resolvedRoot, files) {
+  for (const file of files) {
+    const trimmed = String(file || "").trim();
+    if (!trimmed) continue;
+    const fullPath = path.isAbsolute(trimmed) ? trimmed : path.join(resolvedRoot, trimmed);
+    const relativePath = path.relative(resolvedRoot, fullPath).replace(/\\/g, "/");
+    yield { fullPath, relativePath };
+  }
+}
+
+export { isProductionSource };

package/src/agents/observability/tools/span-coverage.js

@@ -0,0 +1,74 @@
+// span-coverage — flag route handlers without a tracing span (#A20).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, findLineMatches, getLineContent, toPosix, walkRepoFiles } from "./base.js";
+
+const CODE_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".py", ".go"]);
+
+const HANDLER_PATTERNS = [
+  /\b(?:app|router|server|fastify|hono)\.(get|post|put|patch|delete)\s*\(/,
+  /^export\s+async\s+function\s+(GET|POST|PUT|PATCH|DELETE)\s*\(/m,
+  /@(?:app|router|api_router)\.(?:get|post|put|patch|delete)\s*\(/,
+];
+
+const SPAN_SIGNALS = [
+  /tracer\.startSpan|tracer\.startActiveSpan|otel\.|opentelemetry|@tracing|withSpan|withActiveSpan/i,
+  /sentry\.(?:startTransaction|startSpan)/i,
+  /datadog|dd-trace|ddtrace/i,
+  /Sentry\.startTransaction/,
+];
+
+export async function runSpanCoverage({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions: CODE_EXTENSIONS });
+
+  const findings = [];
+  for await (const { fullPath, relativePath } of iterator) {
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const hasHandler = HANDLER_PATTERNS.some((p) => p.test(content));
+    if (!hasHandler) {
+      continue;
+    }
+    const hasSpan = SPAN_SIGNALS.some((p) => p.test(content));
+    if (hasSpan) {
+      continue;
+    }
+    const match = findLineMatches(content, HANDLER_PATTERNS[0])[0] ||
+      findLineMatches(content, HANDLER_PATTERNS[1])[0] ||
+      findLineMatches(content, HANDLER_PATTERNS[2])[0];
+    findings.push(
+      createFinding({
+        tool: "span-coverage",
+        kind: "observability.no-span",
+        severity: "P2",
+        file: toPosix(relativePath),
+        line: match?.line || 1,
+        evidence: getLineContent(content, match?.line || 1),
+        rootCause: "Route handler declared without any tracing-span signal (OpenTelemetry, Sentry, Datadog). Request latency / error breakdowns will be opaque.",
+        recommendedFix: "Wrap the handler body in tracer.startActiveSpan('<name>', …) or use framework middleware that auto-instruments handlers.",
+        confidence: 0.55,
+      })
+    );
+  }
+  return findings;
+}
+
+async function* iterateExplicitFiles(resolvedRoot, files) {
+  for (const file of files) {
+    const trimmed = String(file || "").trim();
+    if (!trimmed) continue;
+    const fullPath = path.isAbsolute(trimmed) ? trimmed : path.join(resolvedRoot, trimmed);
+    const relativePath = path.relative(resolvedRoot, fullPath).replace(/\\/g, "/");
+    yield { fullPath, relativePath };
+  }
+}

package/src/agents/persona-visuals.js

@@ -1,61 +1,102 @@
-/**
- * SentinelLayer Persona Visual Identity Registry
- *
- * All 13 personas — visual identity, domain specialty, and bias.
- * Shared across all persona packages, daemon services, and orchestrators.
- * NOT Jules-specific — this is platform infrastructure.
- */
-
-export const PERSONA_VISUALS = Object.freeze({
-  frontend:        { color: "cyan",    avatar: "\u{1F3AF}", shortName: "Jules",  fullName: "Jules Tanaka",     domain: "frontend_runtime",      specialty: "React/Next.js/Vue production specialist — hydration safety, render cost, accessibility, bundle weight, mobile responsiveness", bias: "user-perceived performance over vanity optimization" },
-  security:        { color: "red",     avatar: "\u{1F6E1}\uFE0F", shortName: "Nina",   fullName: "Nina Patel",       domain: "security_overlay",      specialty: "AuthZ breaks, secret exposure, injection paths, policy bypass, externally reachable abuse conditions", bias: "assume hostile inputs until proven safe" },
-  backend:         { color: "blue",    avatar: "\u2699\uFE0F",    shortName: "Maya",   fullName: "Maya Volkov",      domain: "backend_runtime",       specialty: "Unsafe request handling, runtime crashes, unbounded work, validation gaps, server-side trust boundary failures", bias: "every request is potentially adversarial" },
-  testing:         { color: "green",   avatar: "\u{1F9EA}",       shortName: "Priya",  fullName: "Priya Raman",      domain: "testing_correctness",   specialty: "Missing regression coverage, false confidence from shallow tests, broken invariants with no executable proof", bias: "tests that pass but miss real bugs are worse than no tests" },
-  release:         { color: "yellow",  avatar: "\u{1F680}",       shortName: "Omar",   fullName: "Omar Singh",       domain: "release_engineering",   specialty: "CI/CD integrity, workflow trust, artifact provenance, bypassable gates, unsafe deployment automation", bias: "every deployment is a security boundary" },
-  "code-quality":  { color: "purple",  avatar: "\u{1F48E}",       shortName: "Ethan",  fullName: "Ethan Park",       domain: "code_quality",          specialty: "Complexity hotspots, unsafe shortcuts, brittle structure, maintenance risks that hide future defects", bias: "simplicity is a security feature" },
-  infrastructure:  { color: "orange",  avatar: "\u{1F3D7}\uFE0F", shortName: "Kat",    fullName: "Kat Hughes",       domain: "infrastructure",        specialty: "IAM blast radius, public exposure, network posture, secrets placement, infrastructure policy drift", bias: "least privilege by default, explicit escalation required" },
-  data:            { color: "pink",    avatar: "\u{1F5C4}\uFE0F", shortName: "Linh",   fullName: "Linh Tran",        domain: "data_layer",            specialty: "Query safety, migration drift, integrity failures, tenancy leaks, schema/application mismatches", bias: "data integrity is non-negotiable" },
-  observability:   { color: "magenta", avatar: "\u{1F4CA}",       shortName: "Sofia",  fullName: "Sofia Alvarez",    domain: "observability",         specialty: "Missing telemetry, broken alerting, weak auditability, blind spots that hide failures or attacks", bias: "if you can't observe it, you can't secure it" },
-  reliability:     { color: "white",   avatar: "\u{1F504}",       shortName: "Noah",   fullName: "Noah Ben-David",   domain: "reliability_sre",       specialty: "Timeout safety, retry storms, backlog growth, partial failure handling, operational blast radius", bias: "graceful degradation over silent failure" },
-  documentation:   { color: "gray",    avatar: "\u{1F4DD}",       shortName: "Samir",  fullName: "Samir Okafor",     domain: "docs_knowledge",        specialty: "Operational drift between docs and code, missing runbook steps, misleading instructions that break operators", bias: "documentation is a contract, not decoration" },
-  "supply-chain":  { color: "brown",   avatar: "\u{1F4E6}",       shortName: "Nora",   fullName: "Nora Kline",       domain: "supply_chain",          specialty: "Dependency risk, provenance gaps, pinning drift, artifact trust, compromised build inputs", bias: "every dependency is a trust decision" },
-  "ai-governance": { color: "violet",  avatar: "\u{1F916}",       shortName: "Amina",  fullName: "Amina Chen",       domain: "ai_pipeline",           specialty: "Prompt injection, tool abuse, eval regressions, unsafe model routing, guardrail bypass, policy drift in agentic flows", bias: "AI autonomy requires proportional governance" },
-});
-
-/**
- * Resolve persona visual identity by agent ID or persona name.
- */
-export function resolvePersonaVisual(idOrName) {
-  if (!idOrName) return null;
-  const lower = String(idOrName).toLowerCase();
-
-  // Direct ID match
-  if (PERSONA_VISUALS[lower]) return { id: lower, ...PERSONA_VISUALS[lower] };
-
-  // Name match (first name or full name)
-  for (const [id, visual] of Object.entries(PERSONA_VISUALS)) {
-    if (visual.shortName.toLowerCase() === lower || visual.fullName.toLowerCase() === lower) {
-      return { id, ...visual };
-    }
-  }
-
-  return null;
-}
-
-/**
- * List all persona IDs for autocomplete.
- */
-export function listPersonaIds() {
-  return Object.keys(PERSONA_VISUALS);
-}
-
-/**
- * List all persona names (short + full) for autocomplete.
- */
-export function listPersonaNames() {
-  const names = [];
-  for (const [id, visual] of Object.entries(PERSONA_VISUALS)) {
-    names.push(id, visual.shortName.toLowerCase(), visual.fullName.toLowerCase());
-  }
-  return names;
-}
+/**
+ * SentinelLayer Persona Visual Identity Registry
+ *
+ * All 13 personas — visual identity, domain specialty, and bias.
+ * Shared across all persona packages, daemon services, and orchestrators.
+ * NOT Jules-specific — this is platform infrastructure.
+ */
+
+export const PERSONA_VISUALS = Object.freeze({
+  frontend:        { color: "cyan",    avatar: "\u{1F3AF}", shortName: "Jules",  fullName: "Jules Tanaka",     domain: "frontend_runtime",      specialty: "React/Next.js/Vue production specialist — hydration safety, render cost, accessibility, bundle weight, mobile responsiveness", bias: "user-perceived performance over vanity optimization" },
+  security:        { color: "red",     avatar: "\u{1F6E1}\uFE0F", shortName: "Nina",   fullName: "Nina Patel",       domain: "security_overlay",      specialty: "AuthZ breaks, secret exposure, injection paths, policy bypass, externally reachable abuse conditions", bias: "assume hostile inputs until proven safe" },
+  backend:         { color: "blue",    avatar: "\u2699\uFE0F",    shortName: "Maya",   fullName: "Maya Volkov",      domain: "backend_runtime",       specialty: "Unsafe request handling, runtime crashes, unbounded work, validation gaps, server-side trust boundary failures", bias: "every request is potentially adversarial" },
+  architecture:    { color: "blue",    avatar: "\u{1F3DB}\uFE0F", shortName: "Maya",   fullName: "Maya Volkov",      domain: "backend_architecture",  specialty: "Module boundaries, coupling, state sprawl, god components, circular dependencies, dead code", bias: "boundaries and contracts before cleverness" },
+  performance:     { color: "yellow",  avatar: "\u26A1",          shortName: "Arjun",  fullName: "Arjun Mehta",      domain: "performance_efficiency", specialty: "N+1 queries, blocking I/O, unbounded fetches, memory leaks, bundle bloat, missing caches", bias: "measure before optimizing, then measure again" },
+  compliance:      { color: "magenta", avatar: "\u{1F4CB}",       shortName: "Leila",  fullName: "Leila Farouk",     domain: "compliance_controls",   specialty: "PII handling, audit logging, GDPR/SOC2/HIPAA gaps, consent tracking, data classification", bias: "evidence, not assertions, per regulatory requirement" },
+  testing:         { color: "green",   avatar: "\u{1F9EA}",       shortName: "Priya",  fullName: "Priya Raman",      domain: "testing_correctness",   specialty: "Missing regression coverage, false confidence from shallow tests, broken invariants with no executable proof", bias: "tests that pass but miss real bugs are worse than no tests" },
+  release:         { color: "yellow",  avatar: "\u{1F680}",       shortName: "Omar",   fullName: "Omar Singh",       domain: "release_engineering",   specialty: "CI/CD integrity, workflow trust, artifact provenance, bypassable gates, unsafe deployment automation", bias: "every deployment is a security boundary" },
+  "code-quality":  { color: "purple",  avatar: "\u{1F48E}",       shortName: "Ethan",  fullName: "Ethan Park",       domain: "code_quality",          specialty: "Complexity hotspots, unsafe shortcuts, brittle structure, maintenance risks that hide future defects", bias: "simplicity is a security feature" },
+  infrastructure:  { color: "orange",  avatar: "\u{1F3D7}\uFE0F", shortName: "Kat",    fullName: "Kat Hughes",       domain: "infrastructure",        specialty: "IAM blast radius, public exposure, network posture, secrets placement, infrastructure policy drift", bias: "least privilege by default, explicit escalation required" },
+  data:            { color: "pink",    avatar: "\u{1F5C4}\uFE0F", shortName: "Linh",   fullName: "Linh Tran",        domain: "data_layer",            specialty: "Query safety, migration drift, integrity failures, tenancy leaks, schema/application mismatches", bias: "data integrity is non-negotiable" },
+  observability:   { color: "magenta", avatar: "\u{1F4CA}",       shortName: "Sofia",  fullName: "Sofia Alvarez",    domain: "observability",         specialty: "Missing telemetry, broken alerting, weak auditability, blind spots that hide failures or attacks", bias: "if you can't observe it, you can't secure it" },
+  reliability:     { color: "white",   avatar: "\u{1F504}",       shortName: "Noah",   fullName: "Noah Ben-David",   domain: "reliability_sre",       specialty: "Timeout safety, retry storms, backlog growth, partial failure handling, operational blast radius", bias: "graceful degradation over silent failure" },
+  documentation:   { color: "gray",    avatar: "\u{1F4DD}",       shortName: "Samir",  fullName: "Samir Okafor",     domain: "docs_knowledge",        specialty: "Operational drift between docs and code, missing runbook steps, misleading instructions that break operators", bias: "documentation is a contract, not decoration" },
+  "supply-chain":  { color: "brown",   avatar: "\u{1F4E6}",       shortName: "Nora",   fullName: "Nora Kline",       domain: "supply_chain",          specialty: "Dependency risk, provenance gaps, pinning drift, artifact trust, compromised build inputs", bias: "every dependency is a trust decision" },
+  "ai-governance": { color: "violet",  avatar: "\u{1F916}",       shortName: "Amina",  fullName: "Amina Chen",       domain: "ai_pipeline",           specialty: "Prompt injection, tool abuse, eval regressions, unsafe model routing, guardrail bypass, policy drift in agentic flows", bias: "AI autonomy requires proportional governance" },
+});
+
+/**
+ * Visual identity for the orchestrator tier (Dr. Kai Chen / Senti).
+ *
+ * Kept SEPARATE from PERSONA_VISUALS so the dispatch-invariant test
+ * (FULL_DEPTH_PERSONAS ⊆ PERSONA_VISUALS keys) isn't polluted by
+ * non-review entries. Consumers that need the orchestrator visual
+ * import ORCHESTRATOR_VISUALS or call resolveOrchestratorVisual().
+ */
+export const ORCHESTRATOR_VISUALS = Object.freeze({
+  "kai-chen": {
+    color: "gold",
+    avatar: "\u{1F3AD}",
+    shortName: "Kai",
+    fullName: "Dr. Kai Chen",
+    domain: "orchestration",
+    specialty: "Global orchestrator — picks personas, deduplicates across domains, ranks by severity × confidence × blast radius, demands reproduction steps",
+    bias: "performance budgets; operational simplicity; correctness over cleverness",
+    role: "Global Orchestrator / Senti",
+  },
+});
+
+export function resolveOrchestratorVisual(idOrName) {
+  if (!idOrName) return null;
+  const lower = String(idOrName).toLowerCase();
+  if (ORCHESTRATOR_VISUALS[lower]) {
+    return { id: lower, ...ORCHESTRATOR_VISUALS[lower] };
+  }
+  for (const [id, visual] of Object.entries(ORCHESTRATOR_VISUALS)) {
+    if (
+      visual.shortName.toLowerCase() === lower
+      || visual.fullName.toLowerCase() === lower
+    ) {
+      return { id, ...visual };
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve persona visual identity by agent ID or persona name.
+ */
+export function resolvePersonaVisual(idOrName) {
+  if (!idOrName) return null;
+  const lower = String(idOrName).toLowerCase();
+
+  // Direct ID match
+  if (PERSONA_VISUALS[lower]) return { id: lower, ...PERSONA_VISUALS[lower] };
+
+  // Name match (first name or full name)
+  for (const [id, visual] of Object.entries(PERSONA_VISUALS)) {
+    if (visual.shortName.toLowerCase() === lower || visual.fullName.toLowerCase() === lower) {
+      return { id, ...visual };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * List all persona IDs for autocomplete.
+ */
+export function listPersonaIds() {
+  return Object.keys(PERSONA_VISUALS);
+}
+
+/**
+ * List all persona names (short + full) for autocomplete.
+ */
+export function listPersonaNames() {
+  const names = [];
+  for (const [id, visual] of Object.entries(PERSONA_VISUALS)) {
+    names.push(id, visual.shortName.toLowerCase(), visual.fullName.toLowerCase());
+  }
+  return names;
+}

package/src/agents/release/index.js

@@ -0,0 +1,12 @@
+// Omar (release persona) — barrel export (#A19).
+
+export {
+  RELEASE_TOOLS,
+  RELEASE_TOOL_IDS,
+  dispatchReleaseTool,
+  runAllReleaseTools,
+  runChangelogDiff,
+  runFeatureFlagAudit,
+  runRollbackVerify,
+  runSemverCheck,
+} from "./tools/index.js";

package/src/agents/release/tools/base.js

@@ -0,0 +1,181 @@
+// Shared helpers for Omar's (release) domain tools (#A19).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+import ignore from "ignore";
+
+const DEFAULT_IGNORED_DIRS = new Set([
+  ".git",
+  "node_modules",
+  ".venv",
+  ".next",
+  "dist",
+  "build",
+  "coverage",
+  ".sentinelayer",
+  ".sentinel",
+  ".turbo",
+  ".idea",
+  ".vscode",
+  "__pycache__",
+  ".cache",
+]);
+const MAX_FILE_SIZE_BYTES = 1024 * 1024;
+const SEVERITIES = Object.freeze(["P0", "P1", "P2", "P3"]);
+
+export function toPosix(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+export function normalizeSeverity(value) {
+  const normalized = String(value || "").trim().toUpperCase();
+  if (SEVERITIES.includes(normalized)) {
+    return normalized;
+  }
+  return "P2";
+}
+
+export function createFinding({
+  severity,
+  kind,
+  file,
+  line = 0,
+  evidence = "",
+  rootCause = "",
+  recommendedFix = "",
+  confidence = null,
+  tool = "",
+  persona = "release",
+} = {}) {
+  return {
+    persona,
+    tool: String(tool || "").trim(),
+    kind: String(kind || "").trim() || "release",
+    severity: normalizeSeverity(severity),
+    file: toPosix(file || ""),
+    line: Number.isFinite(Number(line)) ? Math.max(0, Math.floor(Number(line))) : 0,
+    evidence: String(evidence || "").trim().slice(0, 400),
+    rootCause: String(rootCause || "").trim(),
+    recommendedFix: String(recommendedFix || "").trim(),
+    confidence:
+      confidence === null || confidence === undefined
+        ? null
+        : Math.max(0, Math.min(1, Number(confidence) || 0)),
+  };
+}
+
+async function readIgnorePatterns(filePath) {
+  try {
+    const raw = await fsp.readFile(filePath, "utf-8");
+    return String(raw || "")
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith("#"));
+  } catch (err) {
+    if (err && typeof err === "object" && err.code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
+}
+
+async function createIgnoreMatcher(rootPath) {
+  const matcher = ignore();
+  const gitignore = await readIgnorePatterns(path.join(rootPath, ".gitignore"));
+  const sentinel = await readIgnorePatterns(
+    path.join(rootPath, ".sentinelayerignore")
+  );
+  matcher.add([...gitignore, ...sentinel]);
+  return (relativePath, isDirectory) => {
+    const normalized = toPosix(relativePath);
+    if (!normalized) {
+      return false;
+    }
+    const candidate = isDirectory ? `${normalized}/` : normalized;
+    return matcher.ignores(candidate);
+  };
+}
+
+export async function* walkRepoFiles({
+  rootPath = process.cwd(),
+  extensions = new Set(),
+  maxFileSize = MAX_FILE_SIZE_BYTES,
+} = {}) {
+  const resolvedRoot = path.resolve(rootPath);
+  const ignoreMatcher = await createIgnoreMatcher(resolvedRoot);
+  const wantedExtensions =
+    extensions instanceof Set
+      ? extensions
+      : new Set(Array.isArray(extensions) ? extensions : []);
+  const stack = [resolvedRoot];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries = [];
+    try {
+      entries = await fsp.readdir(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      const relativePath = toPosix(path.relative(resolvedRoot, fullPath));
+      if (entry.isDirectory()) {
+        if (!relativePath || DEFAULT_IGNORED_DIRS.has(entry.name)) {
+          continue;
+        }
+        if (ignoreMatcher(relativePath, true)) {
+          continue;
+        }
+        stack.push(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      if (ignoreMatcher(relativePath, false)) {
+        continue;
+      }
+      const ext = path.extname(entry.name).toLowerCase();
+      if (wantedExtensions.size > 0 && !wantedExtensions.has(ext) && !wantedExtensions.has("")) {
+        continue;
+      }
+      let stat = null;
+      try {
+        stat = await fsp.stat(fullPath);
+      } catch {
+        stat = null;
+      }
+      if (!stat || stat.size > maxFileSize) {
+        continue;
+      }
+      yield { fullPath, relativePath, stat };
+    }
+  }
+}
+
+export function findLineMatches(content, pattern) {
+  const text = String(content || "");
+  if (!pattern) {
+    return [];
+  }
+  const global = new RegExp(
+    pattern.source,
+    pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`
+  );
+  const matches = [];
+  let match;
+  while ((match = global.exec(text)) !== null) {
+    const lineIndex = text.slice(0, match.index).split(/\r?\n/).length;
+    matches.push({ index: match.index, line: lineIndex, match: match[0] });
+  }
+  return matches;
+}
+
+export function getLineContent(content, line) {
+  const lines = String(content || "").split(/\r?\n/);
+  return (lines[Math.max(0, (Number(line) || 1) - 1)] || "").trim();
+}
+
+export { DEFAULT_IGNORED_DIRS, MAX_FILE_SIZE_BYTES, SEVERITIES };

package/src/agents/release/tools/changelog-diff.js

@@ -0,0 +1,86 @@
+// changelog-diff — verify the changelog has an entry for the current version (#A19).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, toPosix, walkRepoFiles } from "./base.js";
+
+export async function runChangelogDiff({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions: new Set([".json"]) });
+
+  const findings = [];
+  for await (const { fullPath, relativePath } of iterator) {
+    if (!/(^|\/)package\.json$/.test(toPosix(relativePath))) {
+      continue;
+    }
+    let raw;
+    try {
+      raw = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    if (!parsed?.version || parsed.private === true) {
+      continue;
+    }
+    const dir = path.dirname(fullPath);
+    let changelog = "";
+    for (const candidate of ["CHANGELOG.md", "CHANGES.md"]) {
+      try {
+        changelog = await fsp.readFile(path.join(dir, candidate), "utf-8");
+        break;
+      } catch {
+        /* try next */
+      }
+    }
+    if (!changelog) {
+      continue; // semver-check already advises on missing changelog
+    }
+    const versionPattern = new RegExp(
+      `##\\s*(?:\\[|v)?\\s*${String(parsed.version).replace(/\./g, "\\.")}\\b`
+    );
+    if (!versionPattern.test(changelog)) {
+      findings.push(
+        createFinding({
+          tool: "changelog-diff",
+          kind: "release.version-not-in-changelog",
+          severity: "P2",
+          file: toPosix(relativePath),
+          line: 0,
+          evidence: `package.json version "${parsed.version}" not found as a heading in the colocated changelog`,
+          rootCause:
+            "Changelog is out of sync with the manifest. Releases shipped without a changelog entry are invisible to consumers tracking what's new.",
+          recommendedFix:
+            "Add a `## [${version}] - YYYY-MM-DD` heading to the changelog before publishing. Wire release-please / changesets to keep them in sync automatically.",
+          confidence: 0.8,
+        })
+      );
+    }
+  }
+  return findings;
+}
+
+async function* iterateExplicitFiles(resolvedRoot, files) {
+  for (const file of files) {
+    const trimmed = String(file || "").trim();
+    if (!trimmed) {
+      continue;
+    }
+    const fullPath = path.isAbsolute(trimmed)
+      ? trimmed
+      : path.join(resolvedRoot, trimmed);
+    const relativePath = path
+      .relative(resolvedRoot, fullPath)
+      .replace(/\\/g, "/");
+    yield { fullPath, relativePath };
+  }
+}