@clue-ai/cli 0.0.9 → 0.0.10

package/src/setup-check.mjs

@@ -1,9 +1,15 @@
 import { access, readFile } from "node:fs/promises";
-import { join, relative, resolve } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { validateSemanticCiRequest } from "./contracts.mjs";
 import {
+  SEMANTIC_GEN_WORKFLOW_COMMAND,
+  workflowHasCompatibleSemanticGenCommand,
+} from "./cli-invocation.mjs";
+import {
+  extractExecutableModuleStatements,
   findLifecycleCallApiNames,
   findLifecycleGuardViolations,
+  stripSourceNoise,
 } from "./lifecycle-guard.mjs";
 import { listAllowedSourceFiles } from "./path-policy.mjs";
 import { runSemanticInventory } from "./semantic-ci.mjs";
@@ -21,6 +27,45 @@ const SETUP_SKILLS = [
   "clue-local-verification",
   "clue-setup-report",
 ];
+const SETUP_SKILL_CONTENT_VERSION = "2026-05-10.lifecycle-placement-only.v1";
+const REQUIRED_SETUP_SKILL_PHRASES = {
+  "clue-sdk-instrumentation": [
+    "Do not create no-op wrappers",
+    "Lifecycle calls must resolve to real Clue SDK imports",
+    "add the real `@clue-ai/browser-sdk` dependency",
+    "Do not invent `clue-js-sdk`",
+    "The implementation scope is only ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout placement",
+    "For Django code, use `clue-django-sdk` only after package-manager or registry verification confirms it is installable",
+  ],
+  "clue-setup-audit": [
+    "Reject wrong SDK package names",
+    "Reject Django SDK setup when `clue-django-sdk` installability has not been verified",
+    "Reject ClueTrack instrumentation unless the user explicitly requested product event tracking",
+    "Reject unrelated refactors, renames, file moves",
+    "Execution agents must not approve, certify, or mark their own work complete",
+  ],
+  "clue-local-verification": [
+    "`setup-check --require-sdk-lifecycle` is a static source check only",
+    "Verify frontend SDK installability/import",
+    "Verify backend SDK installability/import",
+    "Do not run `npx -y @clue-ai/cli setup-watch --local` automatically",
+    "user_verification_pending",
+    `Confirm \`.github/workflows/clue-semantic-snapshot.yml\` calls \`${SEMANTIC_GEN_WORKFLOW_COMMAND}\``,
+  ],
+  "clue-setup-orchestrator": [
+    "Clue CLI public npm package: `@clue-ai/cli`",
+    "help --json",
+    "Required implementation agent: SDK Lifecycle Placement Agent only",
+    "Treat semantic snapshot readiness and semantic CI as generated/static verification surfaces",
+    "Do not search for a global `clue-ai` binary",
+    "Read `.clue/setup-manifest.json` `cli_invocation`",
+  ],
+  "clue-setup-report": [
+    "Never claim `setup completed` from `setup-check --require-sdk-lifecycle` alone",
+    "Completion requires all applicable evidence",
+    "For every completion claim, include the evidence source",
+  ],
+};
 const TARGET_SKILL_ROOTS = {
   codex: [".agents", "skills"],
   claude_code: [".claude", "skills"],
@@ -50,14 +95,25 @@ const semanticRequestFromWorkflow = (workflow) => {
     return null;
   }
 };
-const BACKEND_SDK_MARKERS = [
-  "clue-fastapi-sdk",
-  "clue-django-sdk",
-  "clue-python-sdk-core",
-  "clue_fastapi_sdk",
-  "clue_django_sdk",
-  "clue_python_sdk_core",
-];
+const FRONTEND_SDK_PACKAGE = "@clue-ai/browser-sdk";
+const WRONG_FRONTEND_SDK_PACKAGES = ["clue-js-sdk", "@clue/browser-sdk"];
+const BACKEND_SDK_BY_FRAMEWORK = {
+  fastapi: {
+    packages: ["clue-fastapi-sdk"],
+    imports: ["clue_fastapi_sdk"],
+    initPattern: /clue_init_fastapi|CluePythonBootstrapConfig/,
+    installabilityStatus: "published",
+  },
+  django: {
+    packages: ["clue-django-sdk"],
+    imports: ["clue_django_sdk"],
+    initPattern:
+      /clue_init_django|configure_settings|CluePythonBootstrapConfig/,
+    installabilityStatus: "unverified",
+    blocker:
+      "clue-django-sdk installability has not been verified; Django setup must remain blocked until the package is published and import-checked",
+  },
+};
 const DEPENDENCY_FILE_CANDIDATES = [
   "package.json",
   "pnpm-lock.yaml",
@@ -78,6 +134,124 @@ const exists = async (path) => {
   }
 };
 
+const readSetupManifest = async (repoRoot) => {
+  const manifestPath = join(repoRoot, ".clue", "setup-manifest.json");
+  if (!(await exists(manifestPath))) return undefined;
+  try {
+    return JSON.parse(await readFile(manifestPath, "utf8"));
+  } catch {
+    return undefined;
+  }
+};
+
+const validateSetupManifestContract = (manifest) => {
+  if (!manifest || typeof manifest !== "object") {
+    return {
+      checked: false,
+      findings: [],
+    };
+  }
+  const findings = [];
+  if (
+    manifest.cli_invocation?.ai_help_command !==
+    "npx -y @clue-ai/cli help --json"
+  ) {
+    findings.push("cli_invocation.ai_help_command is missing or stale");
+  }
+  if (manifest.lifecycle_verification?.owner !== "user") {
+    findings.push("lifecycle_verification.owner must be user");
+  }
+  if (
+    manifest.lifecycle_verification?.ai_agent_must_run_setup_watch !== false
+  ) {
+    findings.push(
+      "lifecycle_verification.ai_agent_must_run_setup_watch must be false",
+    );
+  }
+  if (
+    !String(manifest.lifecycle_verification?.rule ?? "").includes(
+      "AI implementation agents must not run setup-watch automatically",
+    )
+  ) {
+    findings.push("lifecycle_verification.rule must prohibit AI setup-watch");
+  }
+  if (
+    !Array.isArray(manifest.ai_owned_workstreams) ||
+    manifest.ai_owned_workstreams.length !== 1 ||
+    manifest.ai_owned_workstreams[0] !== "sdk_lifecycle_placement"
+  ) {
+    findings.push("ai_owned_workstreams must be sdk_lifecycle_placement only");
+  }
+  const lifecycleApis = manifest.ai_implementation_scope?.lifecycle_apis;
+  if (
+    !Array.isArray(lifecycleApis) ||
+    lifecycleApis.length !== REQUIRED_LIFECYCLE_APIS.length ||
+    !REQUIRED_LIFECYCLE_APIS.every((apiName) => lifecycleApis.includes(apiName))
+  ) {
+    findings.push(
+      "ai_implementation_scope.lifecycle_apis must contain only ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout",
+    );
+  }
+  if (
+    !Array.isArray(manifest.ai_implementation_scope?.out_of_scope_by_default) ||
+    !manifest.ai_implementation_scope.out_of_scope_by_default.includes(
+      "ClueTrack",
+    )
+  ) {
+    findings.push("ai_implementation_scope must mark ClueTrack out of scope");
+  }
+  const localEventDelivery = Array.isArray(manifest.required_final_verification)
+    ? manifest.required_final_verification.find(
+        (entry) => entry?.id === "local_event_delivery",
+      )
+    : null;
+  if (
+    localEventDelivery?.command !==
+    "user runs npx -y @clue-ai/cli setup-watch --local"
+  ) {
+    findings.push(
+      "required_final_verification.local_event_delivery must be user-operated",
+    );
+  }
+  if (
+    !String(localEventDelivery?.completion_meaning ?? "").includes(
+      "user_verification_pending",
+    )
+  ) {
+    findings.push(
+      "required_final_verification.local_event_delivery must report user_verification_pending without user evidence",
+    );
+  }
+  return {
+    checked: true,
+    findings,
+  };
+};
+
+const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+const validateSetupSkillContent = async ({ skillRoot, rootParts }) => {
+  const missingRequiredPhrases = [];
+  for (const skillName of SETUP_SKILLS) {
+    const skillPath = join(skillRoot, skillName, "SKILL.md");
+    if (!(await exists(skillPath))) continue;
+    const text = await readFile(skillPath, "utf8");
+    const requiredPhrases = [
+      `setup_skill_version: ${SETUP_SKILL_CONTENT_VERSION}`,
+      ...(REQUIRED_SETUP_SKILL_PHRASES[skillName] ?? []),
+    ];
+    for (const phrase of requiredPhrases) {
+      if (!text.includes(phrase)) {
+        missingRequiredPhrases.push({
+          file_path: join(...rootParts, skillName, "SKILL.md"),
+          phrase,
+        });
+      }
+    }
+  }
+  return missingRequiredPhrases;
+};
+
 const normalizeTarget = (target) => {
   if (typeof target !== "string" || target.trim() === "") return undefined;
   const normalized = target
@@ -116,9 +290,12 @@ const readAllowedSourceText = async ({
 };
 
 const readDependencyText = async ({ repoRoot, roots }) => {
+  const expandedRoots = roots.flatMap((root) =>
+    root.endsWith("/src") ? [root, dirname(root)] : [root],
+  );
   const candidatePaths = [
     ...DEPENDENCY_FILE_CANDIDATES,
-    ...roots.flatMap((root) =>
+    ...expandedRoots.flatMap((root) =>
       DEPENDENCY_FILE_CANDIDATES.map((file) => join(root, file)),
     ),
   ];
@@ -174,26 +351,342 @@ const findSecretLeaks = (sources) =>
 const startsWithRoot = (filePath, root) =>
   filePath === root || filePath.startsWith(`${root.replace(/\/+$/, "")}/`);
 
-const hasAnyMarker = (text, markers) =>
-  markers.some((marker) => text.includes(marker));
+const packageJsonDependencyNames = (text) => {
+  try {
+    const parsed = JSON.parse(text);
+    return [
+      "dependencies",
+      "devDependencies",
+      "optionalDependencies",
+      "peerDependencies",
+    ].flatMap((field) =>
+      parsed && typeof parsed[field] === "object" && parsed[field] !== null
+        ? Object.keys(parsed[field])
+        : [],
+    );
+  } catch {
+    return [];
+  }
+};
+
+const dependencySourceHasPackage = (source, packageName) => {
+  if (source.file_path.endsWith("package.json")) {
+    return packageJsonDependencyNames(source.text).includes(packageName);
+  }
+  const packagePattern = new RegExp(
+    `(^|[\\s"'=,{\\[]+)${escapeRegex(packageName)}($|[\\s"'=<>~!,}\\]]+)`,
+    "i",
+  );
+  return source.text
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith("#"))
+    .some((line) => packagePattern.test(line));
+};
+
+const dependencyHasAnyPackage = (dependencySources, packageNames) =>
+  dependencySources.some((source) =>
+    packageNames.some((packageName) =>
+      dependencySourceHasPackage(source, packageName),
+    ),
+  );
+
+const sourceHasPythonImport = (source, importName) => {
+  const importPattern = new RegExp(
+    `(^|\\n)\\s*(?:from\\s+${escapeRegex(importName)}\\b|import\\s+${escapeRegex(importName)}\\b)`,
+  );
+  return importPattern.test(
+    stripSourceNoise(source.text, { stripStrings: true }),
+  );
+};
+
+const sourcesHavePythonImport = (sources, importNames) =>
+  sources.some((source) =>
+    importNames.some((importName) => sourceHasPythonImport(source, importName)),
+  );
+
+const sourcesHaveFrontendSdkImport = (sources) =>
+  sources.some((source) => sourceImportsFrontendSdk(source));
+
+const sourceImportsFrontendSdk = (source) =>
+  sourceTextImportsFrontendSdk(source.text);
+
+const sourceTextImportsFrontendSdk = (text) =>
+  extractExecutableModuleStatements(text).some((statement) =>
+    new RegExp(
+      `(?:from\\s*["']${escapeRegex(FRONTEND_SDK_PACKAGE)}["']|import\\s*["']${escapeRegex(FRONTEND_SDK_PACKAGE)}["'])`,
+    ).test(statement),
+  );
+
+const parseNamedSpecifiers = (specifiers) =>
+  specifiers
+    .split(",")
+    .map((specifier) => specifier.trim())
+    .filter(Boolean)
+    .map((specifier) => {
+      const match = /^([A-Za-z_$][\w$]*)(?:\s+as\s+([A-Za-z_$][\w$]*))?$/.exec(
+        specifier,
+      );
+      if (!match) return null;
+      return {
+        imported: match[1],
+        local: match[2] ?? match[1],
+        exported: match[2] ?? match[1],
+      };
+    })
+    .filter(Boolean);
+
+const sourceDirectlyProvidesApiFromFrontendSdk = (text, apiName) => {
+  const statements = extractExecutableModuleStatements(text);
+  for (const match of statements
+    .join("\n")
+    .matchAll(/import\s*{([^}]+)}\s*from\s*["']([^"']+)["']/g)) {
+    if (match[2] !== FRONTEND_SDK_PACKAGE) continue;
+    if (
+      parseNamedSpecifiers(match[1]).some(
+        (specifier) =>
+          specifier.imported === apiName && specifier.local === apiName,
+      )
+    ) {
+      return true;
+    }
+  }
+  for (const match of statements
+    .join("\n")
+    .matchAll(/export\s*{([^}]+)}\s*from\s*["']([^"']+)["']/g)) {
+    if (match[2] !== FRONTEND_SDK_PACKAGE) continue;
+    if (
+      parseNamedSpecifiers(match[1]).some(
+        (specifier) =>
+          specifier.imported === apiName && specifier.exported === apiName,
+      )
+    ) {
+      return true;
+    }
+  }
+  return false;
+};
+
+const frontendSdkImportedLocalsForApi = (text, apiName) => {
+  const locals = [];
+  for (const match of extractExecutableModuleStatements(text)
+    .join("\n")
+    .matchAll(/import\s*{([^}]+)}\s*from\s*["']([^"']+)["']/g)) {
+    if (match[2] !== FRONTEND_SDK_PACKAGE) continue;
+    for (const specifier of parseNamedSpecifiers(match[1])) {
+      if (specifier.imported === apiName) {
+        locals.push(specifier.local);
+      }
+    }
+  }
+  return locals;
+};
+
+const frontendSdkNamespaces = (text) =>
+  [
+    ...extractExecutableModuleStatements(text)
+      .join("\n")
+      .matchAll(
+        /import\s*\*\s*as\s*([A-Za-z_$][\w$]*)\s*from\s*["']([^"']+)["']/g,
+      ),
+  ]
+    .filter((match) => match[2] === FRONTEND_SDK_PACKAGE)
+    .map((match) => match[1]);
+
+const sourceExportsLocalAsApi = (text, localName, apiName) => {
+  const statements = extractExecutableModuleStatements(text).join("\n");
+  for (const match of statements.matchAll(
+    /export\s*{([^}]+)}(?:\s*from\s*["'][^"']+["'])?/g,
+  )) {
+    if (match[0].includes(" from ")) continue;
+    if (
+      parseNamedSpecifiers(match[1]).some(
+        (specifier) =>
+          specifier.imported === localName && specifier.exported === apiName,
+      )
+    ) {
+      return true;
+    }
+  }
+  return new RegExp(
+    `export\\s+const\\s+${escapeRegex(apiName)}\\s*=\\s*${escapeRegex(localName)}\\b`,
+  ).test(statements);
+};
+
+const sourceForwardsFrontendSdkApi = (source, apiName) => {
+  const text = source.text;
+  if (sourceDirectlyProvidesApiFromFrontendSdk(text, apiName)) return true;
+  const importedLocals = frontendSdkImportedLocalsForApi(text, apiName);
+  if (
+    importedLocals.some((localName) =>
+      sourceExportsLocalAsApi(text, localName, apiName),
+    )
+  ) {
+    return true;
+  }
+  return frontendSdkNamespaces(text).some((namespaceName) =>
+    new RegExp(
+      `export\\s+const\\s+${escapeRegex(apiName)}\\s*=\\s*${escapeRegex(namespaceName)}\\.${escapeRegex(apiName)}\\b`,
+    ).test(text),
+  );
+};
+
+const localImportSpecifiersForApi = (text, apiName) =>
+  [
+    ...extractExecutableModuleStatements(text)
+      .join("\n")
+      .matchAll(/import\s*{([^}]+)}\s*from\s*["']([^"']+)["']/g),
+  ]
+    .filter((match) => match[2].startsWith(".") || match[2].startsWith("@/"))
+    .flatMap((match) =>
+      parseNamedSpecifiers(match[1])
+        .filter(
+          (specifier) =>
+            specifier.imported === apiName && specifier.local === apiName,
+        )
+        .map(() => match[2]),
+    );
+
+const importSpecifiers = (text) =>
+  [
+    ...extractExecutableModuleStatements(text)
+      .join("\n")
+      .matchAll(/import\s+(?:[\s\S]*?\s+from\s+)?["']([^"']+)["']/g),
+  ]
+    .map((match) => match[1] ?? match[2])
+    .filter(Boolean);
+
+const candidateSourcePaths = (basePath) => [
+  basePath,
+  ...SOURCE_EXTENSIONS.map((extension) => `${basePath}${extension}`),
+  ...SOURCE_EXTENSIONS.map((extension) => join(basePath, `index${extension}`)),
+];
+
+const resolveLocalSource = ({ importerPath, sourceByPath, specifier }) => {
+  const candidates = [];
+  if (specifier.startsWith(".")) {
+    candidates.push(
+      ...candidateSourcePaths(join(dirname(importerPath), specifier)),
+    );
+  }
+  if (specifier.startsWith("@/")) {
+    const srcIndex = importerPath.lastIndexOf("/src/");
+    if (srcIndex >= 0) {
+      candidates.push(
+        ...candidateSourcePaths(
+          join(
+            importerPath.slice(0, srcIndex + "/src".length),
+            specifier.slice(2),
+          ),
+        ),
+      );
+    }
+    for (const root of [
+      "src",
+      "frontend/src",
+      "apps/web/src",
+      "apps/admin/src",
+      "apps/visitor/src",
+    ]) {
+      candidates.push(...candidateSourcePaths(join(root, specifier.slice(2))));
+    }
+  }
+  return candidates
+    .map((candidate) => sourceByPath.get(candidate))
+    .find(Boolean);
+};
+
+const sourceHasVerifiedFrontendSdkAccess = ({
+  apiNames,
+  source,
+  sourceByPath,
+}) =>
+  apiNames.every((apiName) => {
+    if (sourceDirectlyProvidesApiFromFrontendSdk(source.text, apiName)) {
+      return true;
+    }
+    return localImportSpecifiersForApi(source.text, apiName).some(
+      (specifier) => {
+        const importedSource = resolveLocalSource({
+          importerPath: source.file_path,
+          sourceByPath,
+          specifier,
+        });
+        return importedSource
+          ? sourceForwardsFrontendSdkApi(importedSource, apiName)
+          : false;
+      },
+    );
+  });
+
+const findWrongFrontendSdkPackages = ({ sources, dependencySources }) => {
+  const combined = [...sources, ...dependencySources]
+    .map((source) => stripSourceNoise(source.text))
+    .join("\n");
+  return WRONG_FRONTEND_SDK_PACKAGES.filter((packageName) =>
+    combined.includes(packageName),
+  );
+};
+
+const backendSdkSpec = (framework) =>
+  BACKEND_SDK_BY_FRAMEWORK[String(framework ?? "").toLowerCase()] ?? {
+    packages: Object.values(BACKEND_SDK_BY_FRAMEWORK).flatMap(
+      (spec) => spec.packages,
+    ),
+    imports: Object.values(BACKEND_SDK_BY_FRAMEWORK).flatMap(
+      (spec) => spec.imports,
+    ),
+    initPattern:
+      /clue_init_fastapi|clue_init_django|configure_settings|CluePythonBootstrapConfig/,
+    installabilityStatus: "framework_unverified",
+  };
 
 const checkSdkLifecycle = ({
   backendRootPaths = [],
   dependencySources = [],
+  framework,
   sources,
 }) => {
-  const combined = sources.map((source) => source.text).join("\n");
+  const combined = sources
+    .map((source) => stripSourceNoise(source.text, { stripStrings: true }))
+    .join("\n");
   const backendSources = sources.filter((source) =>
     backendRootPaths.some((root) => startsWithRoot(source.file_path, root)),
   );
+  const frontendSources = sources.filter(
+    (source) =>
+      !backendRootPaths.some((root) => startsWithRoot(source.file_path, root)),
+  );
   const backendCombined = backendSources
-    .map((source) => source.text)
+    .map((source) => stripSourceNoise(source.text, { stripStrings: true }))
     .join("\n");
-  const dependencyCombined = dependencySources
-    .map((source) => source.text)
+  const frontendCombined = frontendSources
+    .map((source) => stripSourceNoise(source.text, { stripStrings: true }))
     .join("\n");
   const foundApiNames = findLifecycleCallApiNames(combined);
   const backendFoundApiNames = findLifecycleCallApiNames(backendCombined);
+  const frontendFoundApiNames = findLifecycleCallApiNames(frontendCombined);
+  const sourceByPath = new Map(
+    sources.map((source) => [source.file_path, source]),
+  );
+  const frontendLifecycleFilesWithoutVerifiedSdk = frontendSources
+    .filter(
+      (source) =>
+        findLifecycleCallApiNames(
+          stripSourceNoise(source.text, { stripStrings: true }),
+        ).length > 0,
+    )
+    .filter((source) => {
+      const apiNames = findLifecycleCallApiNames(
+        stripSourceNoise(source.text, { stripStrings: true }),
+      );
+      return !sourceHasVerifiedFrontendSdkAccess({
+        apiNames,
+        source,
+        sourceByPath,
+      });
+    })
+    .map((source) => source.file_path);
   const foundApis = REQUIRED_LIFECYCLE_APIS.filter((api) =>
     foundApiNames.includes(api),
   );
@@ -204,30 +697,49 @@ const checkSdkLifecycle = ({
     /window\.Clue(?:Init|Identify|SetAccount|Logout)|(?:function|const|let|var)\s+Clue(?:Init|Identify|SetAccount|Logout)\b/;
   const componentLifecycleInitFiles = sources
     .filter((source) =>
-      /useEffect\s*\([\s\S]{0,1200}ClueInit/.test(source.text),
+      /useEffect\s*\([\s\S]{0,1200}ClueInit/.test(
+        stripSourceNoise(source.text, { stripStrings: true }),
+      ),
     )
     .map((source) => source.file_path);
-  const unguardedLifecycleCalls = sources.flatMap((source) =>
-    findLifecycleGuardViolations(source.text).map((violation) => ({
+  const blockingLifecycleCalls = sources.flatMap((source) =>
+    findLifecycleGuardViolations(
+      stripSourceNoise(source.text, { stripStrings: true }),
+    ).map((violation) => ({
       file_path: source.file_path,
       ...violation,
     })),
   );
-  const unguardedLifecycleFiles = [
-    ...new Set(unguardedLifecycleCalls.map((violation) => violation.file_path)),
+  const blockingLifecycleFiles = [
+    ...new Set(blockingLifecycleCalls.map((violation) => violation.file_path)),
   ];
   const backendPresent = backendSources.length > 0;
-  const backendSdkPresent =
+  const backendSpec = backendSdkSpec(framework);
+  const backendSdkDependencyPresent =
     !backendPresent ||
-    hasAnyMarker(
-      `${backendCombined}\n${dependencyCombined}`,
-      BACKEND_SDK_MARKERS,
-    );
-  const backendInitPresent =
+    dependencyHasAnyPackage(dependencySources, backendSpec.packages);
+  const backendSdkImportPresent =
     !backendPresent ||
-    /clue_init_fastapi|clue_init_django|configure_settings|CluePythonBootstrapConfig/.test(
-      backendCombined,
-    );
+    sourcesHavePythonImport(backendSources, backendSpec.imports);
+  const backendSdkPresent =
+    !backendPresent || (backendSdkDependencyPresent && backendSdkImportPresent);
+  const backendSdkInstallabilityVerified =
+    !backendPresent || backendSpec.installabilityStatus !== "unverified";
+  const backendInitPresent =
+    !backendPresent || backendSpec.initPattern.test(backendCombined);
+  const frontendLifecyclePresent = frontendFoundApiNames.length > 0;
+  const frontendSdkDependencyPresent =
+    !frontendLifecyclePresent ||
+    dependencyHasAnyPackage(dependencySources, [FRONTEND_SDK_PACKAGE]);
+  const frontendSdkImportPresent =
+    !frontendLifecyclePresent || sourcesHaveFrontendSdkImport(frontendSources);
+  const frontendSdkPresent =
+    !frontendLifecyclePresent ||
+    (frontendSdkDependencyPresent && frontendSdkImportPresent);
+  const wrongFrontendSdkPackages = findWrongFrontendSdkPackages({
+    sources: frontendSources,
+    dependencySources,
+  });
   const backendIdentityRequired =
     backendPresent &&
     /\b(login|signin|sign_in|auth|token|session)\b/i.test(backendCombined);
@@ -256,6 +768,15 @@ const checkSdkLifecycle = ({
       backend_present: backendPresent,
       backend_root_paths: backendRootPaths,
       dependency_files: dependencySources.map((source) => source.file_path),
+      expected_sdk_packages: backendSpec.packages,
+      expected_sdk_imports: backendSpec.imports,
+      sdk_installability_status: backendSpec.installabilityStatus,
+      sdk_installability_verified: backendSdkInstallabilityVerified,
+      sdk_blocker: backendSdkInstallabilityVerified
+        ? null
+        : backendSpec.blocker,
+      sdk_dependency_present: backendSdkDependencyPresent,
+      sdk_import_present: backendSdkImportPresent,
       sdk_dependency_or_import_present: backendSdkPresent,
       sdk_init_present: backendInitPresent,
       required_apis: [
@@ -265,18 +786,35 @@ const checkSdkLifecycle = ({
       ],
       missing_apis: backendMissingApis,
     },
+    frontend_lifecycle: {
+      lifecycle_present: frontendLifecyclePresent,
+      found_apis: frontendFoundApiNames,
+      expected_sdk_package: FRONTEND_SDK_PACKAGE,
+      sdk_dependency_present: frontendSdkDependencyPresent,
+      sdk_import_present: frontendSdkImportPresent,
+      sdk_dependency_or_import_present: frontendSdkPresent,
+      lifecycle_files_without_verified_sdk:
+        frontendLifecycleFilesWithoutVerifiedSdk,
+      wrong_sdk_packages: wrongFrontendSdkPackages,
+    },
     has_noop_wrapper: noOpPattern.test(combined),
     component_lifecycle_init_files: componentLifecycleInitFiles,
-    unguarded_lifecycle_files: unguardedLifecycleFiles,
-    unguarded_lifecycle_calls: unguardedLifecycleCalls,
+    blocking_lifecycle_files: blockingLifecycleFiles,
+    blocking_lifecycle_calls: blockingLifecycleCalls,
+    unguarded_lifecycle_files: blockingLifecycleFiles,
+    unguarded_lifecycle_calls: blockingLifecycleCalls,
     passed:
       missingApis.length === 0 &&
       backendSdkPresent &&
+      backendSdkInstallabilityVerified &&
       backendInitPresent &&
       backendMissingApis.length === 0 &&
+      frontendSdkPresent &&
+      frontendLifecycleFilesWithoutVerifiedSdk.length === 0 &&
+      wrongFrontendSdkPackages.length === 0 &&
       !noOpPattern.test(combined) &&
       componentLifecycleInitFiles.length === 0 &&
-      unguardedLifecycleFiles.length === 0,
+      blockingLifecycleFiles.length === 0,
   };
 };
 
@@ -288,22 +826,39 @@ export const runSetupCheck = async ({
 }) => {
   const resolvedRepoRoot = resolve(repoRoot ?? ".");
   const checks = [];
-  const normalizedTarget = normalizeTarget(target);
+  const setupManifest = await readSetupManifest(resolvedRepoRoot);
+  const manifestContract = validateSetupManifestContract(setupManifest);
+  addCheck(
+    checks,
+    "setup_manifest_contract",
+    !manifestContract.checked || manifestContract.findings.length === 0,
+    manifestContract.checked
+      ? manifestContract.findings.length === 0
+        ? "setup manifest contains current AI setup responsibility boundaries"
+        : "setup manifest is missing current AI setup responsibility boundaries"
+      : "setup manifest contract was not checked because .clue/setup-manifest.json is absent or unreadable",
+    {
+      checked: manifestContract.checked,
+      findings: manifestContract.findings,
+    },
+  );
+  const normalizedTarget =
+    normalizeTarget(target) ?? normalizeTarget(setupManifest?.target);
 
   if (normalizedTarget) {
-    const skillRoot = join(
-      resolvedRepoRoot,
-      ...TARGET_SKILL_ROOTS[normalizedTarget],
-    );
+    const rootParts = TARGET_SKILL_ROOTS[normalizedTarget];
+    const skillRoot = join(resolvedRepoRoot, ...rootParts);
     const missingSkills = [];
     for (const skillName of SETUP_SKILLS) {
       const skillPath = join(skillRoot, skillName, "SKILL.md");
       if (!(await exists(skillPath))) {
-        missingSkills.push(
-          join(...TARGET_SKILL_ROOTS[normalizedTarget], skillName, "SKILL.md"),
-        );
+        missingSkills.push(join(...rootParts, skillName, "SKILL.md"));
       }
     }
+    const missingRequiredPhrases = await validateSetupSkillContent({
+      skillRoot,
+      rootParts,
+    });
     addCheck(
       checks,
       "setup_skills",
@@ -313,6 +868,36 @@ export const runSetupCheck = async ({
         : "setup skills are missing",
       { missing_files: missingSkills },
     );
+    addCheck(
+      checks,
+      "setup_skill_content",
+      missingSkills.length === 0 && missingRequiredPhrases.length === 0,
+      missingSkills.length === 0 && missingRequiredPhrases.length === 0
+        ? "setup skills contain current safety rules"
+        : "setup skills are stale or missing required safety rules",
+      {
+        expected_version: SETUP_SKILL_CONTENT_VERSION,
+        missing_required_phrases: missingRequiredPhrases,
+      },
+    );
+  } else {
+    addCheck(
+      checks,
+      "setup_skills",
+      false,
+      "setup target is required or must be inferable from .clue/setup-manifest.json",
+      { missing_target: true },
+    );
+    addCheck(
+      checks,
+      "setup_skill_content",
+      false,
+      "setup skills were not checked because setup target is missing",
+      {
+        expected_version: SETUP_SKILL_CONTENT_VERSION,
+        missing_required_phrases: [],
+      },
+    );
   }
 
   const workflowPath = request?.ci_workflow_path ?? DEFAULT_WORKFLOW_PATH;
@@ -323,9 +908,7 @@ export const runSetupCheck = async ({
     addCheck(
       checks,
       "semantic_workflow",
-      workflow.includes(
-        "npx @clue-ai/cli semantic-gen --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .",
-      ) &&
+      workflowHasCompatibleSemanticGenCommand(workflow) &&
         semanticRequest !== null &&
         workflow.includes("CLUE_SEMANTIC_REQUEST_JSON: |") &&
         workflow.includes("CLUE_API_KEY: ${{ secrets.CLUE_API_KEY }}") &&
@@ -341,7 +924,7 @@ export const runSetupCheck = async ({
         workflow.includes("permissions:\n  contents: read") &&
         workflow.includes("persist-credentials: false") &&
         !disallowedWorkflowMetadataPattern.test(workflow),
-      "semantic workflow uses the canonical env runtime request, least-privilege checkout, and privacy-minimized GitHub metadata",
+      "semantic workflow uses a compatible env runtime request, least-privilege checkout, and privacy-minimized GitHub metadata",
       { workflow_path: workflowPath },
     );
   } else {
@@ -406,7 +989,7 @@ export const runSetupCheck = async ({
   });
   const dependencySources = await readDependencyText({
     repoRoot: resolvedRepoRoot,
-    roots: request?.allowed_source_paths ?? [],
+    roots: sourcePaths,
   });
   const secretLeaks = findSecretLeaks([
     ...sources,
@@ -434,22 +1017,26 @@ export const runSetupCheck = async ({
     const sdkLifecycle = checkSdkLifecycle({
       backendRootPaths: request?.allowed_source_paths ?? [],
       dependencySources,
+      framework: request?.framework,
       sources,
     });
     addCheck(
       checks,
       "sdk_lifecycle",
       sdkLifecycle.passed,
-      "static SDK lifecycle references are present and guarded; dependency install, import, app startup, and event delivery are not verified by this check",
+      "static SDK lifecycle references are present and non-blocking; dependency install, import, app startup, and event delivery are not verified by this check",
       {
         found_apis: sdkLifecycle.foundApis,
         missing_apis: sdkLifecycle.missingApis,
         verification_scope:
           "static_source_only_not_dependency_install_or_runtime_event_delivery",
         backend_lifecycle: sdkLifecycle.backend_lifecycle,
+        frontend_lifecycle: sdkLifecycle.frontend_lifecycle,
         has_noop_wrapper: sdkLifecycle.has_noop_wrapper,
         component_lifecycle_init_files:
           sdkLifecycle.component_lifecycle_init_files,
+        blocking_lifecycle_files: sdkLifecycle.blocking_lifecycle_files,
+        blocking_lifecycle_calls: sdkLifecycle.blocking_lifecycle_calls,
         unguarded_lifecycle_files: sdkLifecycle.unguarded_lifecycle_files,
         unguarded_lifecycle_calls: sdkLifecycle.unguarded_lifecycle_calls,
       },
@@ -459,6 +1046,13 @@ export const runSetupCheck = async ({
   const passed = checks.every((check) => check.passed);
   return {
     passed,
+    static_passed: passed,
+    completion_status:
+      passed && requireSdkLifecycle
+        ? "static_passed_runtime_verification_required"
+        : passed
+          ? "passed"
+          : "failed",
     checks,
   };
 };