@clue-ai/cli 0.0.4 → 0.0.6

package/src/setup-prepare.mjs

@@ -0,0 +1,289 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import {
+  buildSemanticWorkflowRequestFromFlags,
+  writeSemanticWorkflow,
+} from "./init-tool.mjs";
+import { runSetupDetect } from "./setup-detect.mjs";
+
+const DEFAULT_SETUP_MANIFEST_PATH = ".clue/setup-manifest.json";
+const BROWSER_INGEST_PATH = "/api/v1/ingest/browser";
+const BACKEND_INGEST_PATH = "/api/v1/ingest/backend";
+
+const writeJson = async ({ repoRoot, path, value }) => {
+  const absolutePath = join(resolve(repoRoot), path);
+  await mkdir(dirname(absolutePath), { recursive: true });
+  await writeFile(absolutePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+};
+
+const firstCandidateOrBlocker = (detection) => {
+  if (!detection.detected || detection.candidates.length === 0) {
+    return {
+      candidate: null,
+      blockers: detection.blockers.length
+        ? detection.blockers
+        : [
+            {
+              code: "NO_SETUP_CANDIDATE",
+              message: "No setup candidate was mechanically detected.",
+            },
+          ],
+    };
+  }
+  return {
+    candidate: detection.candidates[0],
+    blockers: [],
+  };
+};
+
+const DEFAULT_SETUP_LIFECYCLE = [
+  "init",
+  "identify",
+  "set-account",
+  "logout",
+  "event-sent",
+];
+
+const buildWatchTargets = (detection, fallbackCandidate) => {
+  const frontendServices = Array.isArray(detection.services?.frontend)
+    ? detection.services.frontend
+    : [];
+  const backendServices = Array.isArray(detection.services?.backend)
+    ? detection.services.backend
+    : [
+        {
+          kind: "backend",
+          framework: fallbackCandidate.framework,
+          root_path: fallbackCandidate.backend_root_path,
+          service_key: fallbackCandidate.service_key,
+          local_url_candidates: [],
+        },
+      ];
+  return [...frontendServices, ...backendServices].map((service) => ({
+    kind: service.kind,
+    framework: service.framework,
+    root_path: service.root_path,
+    service_key: service.service_key,
+    producer_id: service.service_key,
+    expected_lifecycle: DEFAULT_SETUP_LIFECYCLE,
+    local_url_candidates: service.local_url_candidates ?? [],
+    url_env_name:
+      service.kind === "frontend"
+        ? `CLUE_LOCAL_${service.service_key.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_FRONTEND_URL`
+        : `CLUE_LOCAL_${service.service_key.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_BACKEND_URL`,
+  }));
+};
+
+const optionalString = (value) =>
+  typeof value === "string" && value.trim() ? value.trim() : null;
+
+const trimTrailingSlash = (value) => String(value).replace(/\/+$/, "");
+
+const buildEndpoint = (baseUrl, path) => `${trimTrailingSlash(baseUrl)}${path}`;
+
+const setupContextFromInput = (input = {}) => ({
+  clue_api_key: optionalString(input.clueApiKey),
+  clue_api_base_url: optionalString(input.clueApiBaseUrl),
+  project_key: optionalString(input.projectKey),
+  environment: optionalString(input.environment),
+});
+
+const envFileCandidates = (target) => {
+  if (target.kind === "frontend") {
+    return target.framework === "nextjs" ? [".env.local"] : [".env"];
+  }
+  return [".env"];
+};
+
+const buildServiceEnvBlock = ({ target, setupContext }) => {
+  const ingestPath =
+    target.kind === "frontend" ? BROWSER_INGEST_PATH : BACKEND_INGEST_PATH;
+  const variables = [
+    {
+      name: "CLUE_INGEST_ENDPOINT",
+      value: buildEndpoint(setupContext.clue_api_base_url, ingestPath),
+    },
+    { name: "CLUE_PROJECT_KEY", value: setupContext.project_key },
+    { name: "CLUE_ENVIRONMENT", value: setupContext.environment },
+    { name: "CLUE_SERVICE_KEY", value: target.service_key },
+  ];
+  if (target.kind === "backend") {
+    variables.push({ name: "CLUE_API_KEY", value: setupContext.clue_api_key });
+  }
+  return variables.map(({ name, value }) => `${name}=${value}`).join("\n");
+};
+
+const buildEnvironmentInstructions = ({ manifest, setupContext }) => {
+  const missingFlags = [
+    ["clue_api_key", "--clue-api-key"],
+    ["clue_api_base_url", "--clue-api-base-url"],
+    ["project_key", "--project-key"],
+    ["environment", "--environment"],
+  ]
+    .filter(([key]) => !setupContext[key])
+    .map(([, flag]) => flag);
+
+  if (missingFlags.length > 0 || manifest.status !== "ready_for_ai") {
+    return {
+      status: "missing_setup_arguments",
+      required_flags: missingFlags,
+      message:
+        "Run setup with Clue values from the setup screen to print service-specific env blocks.",
+    };
+  }
+
+  const watchTargets = manifest.lifecycle_verification.watch_targets;
+  return {
+    status: "ready",
+    message: "各サービスの env ファイルに以下を設定してください。",
+    service_env_blocks: watchTargets.map((target) => ({
+      kind: target.kind,
+      framework: target.framework,
+      root_path: target.root_path,
+      service_key: target.service_key,
+      env_file_candidates: envFileCandidates(target),
+      env_block: buildServiceEnvBlock({ target, setupContext }),
+    })),
+    ci_github: {
+      secrets: [
+        { name: "CLUE_API_KEY", value: setupContext.clue_api_key },
+        {
+          name: "CLUE_AI_PROVIDER_API_KEY",
+          value: "<openai-or-anthropic-api-key>",
+        },
+      ],
+      variables: [
+        { name: "CLUE_AI_PROVIDER", value: "<openai-or-anthropic>" },
+        { name: "CLUE_AI_MODEL", value: "<selected-provider-model>" },
+      ],
+    },
+  };
+};
+
+export const runSetupPrepare = async ({
+  repoRoot,
+  target,
+  skillRoot,
+  setupContext: setupContextInput,
+  setupManifestPath = DEFAULT_SETUP_MANIFEST_PATH,
+}) => {
+  const resolvedRepoRoot = resolve(repoRoot ?? ".");
+  const setupContext = setupContextFromInput(setupContextInput);
+  const detection = await runSetupDetect({ repoRoot: resolvedRepoRoot });
+  const { candidate, blockers } = firstCandidateOrBlocker(detection);
+  if (!candidate) {
+    const manifest = {
+      status: "blocked",
+      target,
+      skill_root: skillRoot,
+      blockers,
+      detection,
+      ai_next_scope: "blocked_until_backend_routes_are_detected",
+      machine_owned_artifacts: [],
+      ai_owned_workstreams: [
+        "sdk_lifecycle_implementation_after_blockers_are_resolved",
+      ],
+    };
+    await writeJson({
+      repoRoot: resolvedRepoRoot,
+      path: setupManifestPath,
+      value: manifest,
+    });
+    return {
+      ...manifest,
+      environment_instructions: buildEnvironmentInstructions({
+        manifest,
+        setupContext,
+      }),
+    };
+  }
+
+  const request = buildSemanticWorkflowRequestFromFlags({
+    framework: candidate.framework,
+    backendRootPath: candidate.backend_root_path,
+    serviceKey: candidate.service_key,
+    projectKey: setupContext.project_key,
+    environment: setupContext.environment,
+    clueApiBaseUrl: setupContext.clue_api_base_url,
+  });
+  const workflow = await writeSemanticWorkflow({
+    repoRoot: resolvedRepoRoot,
+    request,
+  });
+
+  const manifest = {
+    status: "ready_for_ai",
+    target,
+    skill_root: skillRoot,
+    detected: {
+      framework: candidate.framework,
+      backend_root_path: candidate.backend_root_path,
+      service_key: candidate.service_key,
+    },
+    service_identity: {
+      canonical_field: "service_key",
+      backend_env_name: "CLUE_SERVICE_KEY",
+      frontend_env_name: "CLUE_SERVICE_KEY",
+      producer_id_derivation: "producer_id defaults to service_key",
+    },
+    clue_context: {
+      project_key: setupContext.project_key,
+      environment: setupContext.environment,
+      clue_api_base_url: setupContext.clue_api_base_url,
+      ingest_endpoints: setupContext.clue_api_base_url
+        ? {
+            browser: buildEndpoint(
+              setupContext.clue_api_base_url,
+              BROWSER_INGEST_PATH,
+            ),
+            backend: buildEndpoint(
+              setupContext.clue_api_base_url,
+              BACKEND_INGEST_PATH,
+            ),
+          }
+        : null,
+    },
+    lifecycle_verification: {
+      watch_target_format:
+        "frontend:<service-key>[init,identify,set-account,logout,event-sent]=<frontend-url>,backend:<service-key>[init,identify,set-account,logout,event-sent]=<backend-url>",
+      rule: "setup-watch --local uses the structured watch_targets below. Lifecycle checks are fixed for setup verification and are evaluated per service_key.",
+      watch_targets: buildWatchTargets(detection, candidate),
+    },
+    artifacts: {
+      ci_workflow_path: workflow.ci_workflow_path,
+      setup_manifest_path: setupManifestPath,
+      runtime_request_committed: false,
+    },
+    machine_owned_artifacts: [workflow.ci_workflow_path, setupManifestPath],
+    ai_must_not_edit: [workflow.ci_workflow_path],
+    ai_owned_workstreams: ["sdk_lifecycle_implementation"],
+    required_final_check: {
+      command:
+        `npx @clue-ai/cli setup-check --framework ${candidate.framework} ` +
+        `--backend-root-path ${candidate.backend_root_path} --repo . --target ${target} --require-sdk-lifecycle`,
+    },
+    required_env_names: [
+      "CLUE_SERVICE_KEY",
+      "CLUE_API_KEY",
+      "CLUE_AI_PROVIDER",
+      "CLUE_AI_PROVIDER_API_KEY",
+      "CLUE_PROJECT_KEY",
+      "CLUE_ENVIRONMENT",
+      "CLUE_INGEST_ENDPOINT",
+      "CLUE_API_BASE_URL",
+      "CLUE_AI_MODEL",
+    ],
+  };
+  await writeJson({
+    repoRoot: resolvedRepoRoot,
+    path: setupManifestPath,
+    value: manifest,
+  });
+  return {
+    ...manifest,
+    environment_instructions: buildEnvironmentInstructions({
+      manifest,
+      setupContext,
+    }),
+  };
+};

package/src/setup-tool.mjs

@@ -20,7 +20,10 @@ const TARGET_SKILL_ROOTS = {
 };
 
 const normalizeTarget = (target) => {
-  const normalized = String(target ?? "").trim().toLowerCase().replace(/[\s-]+/g, "_");
+  const normalized = String(target ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[\s-]+/g, "_");
   if (!TARGETS.has(normalized)) {
     throw new Error("AIツールは codex または claude_code を指定してください");
   }
@@ -32,7 +35,7 @@ const skillBody = (name) => {
     "clue-setup-orchestrator":
       "Use first when running the full Clue setup so one execution agent per implementation workstream and multiple monitoring agents coordinate separate setup phases.",
     "clue-route-semantic-snapshot":
-      "Use when analyzing backend routes, handlers, controllers, or endpoints to create privacy-safe Clue semantic snapshots.",
+      "Use when checking backend route coverage and semantic snapshot readiness without hand-authoring generated snapshot files.",
     "clue-semantic-ci":
       "Use when adding or updating Clue semantic snapshot CI for this repository.",
     "clue-sdk-instrumentation":
@@ -49,11 +52,14 @@ const skillBody = (name) => {
     "clue-setup-orchestrator": [
       "Use one execution agent per implementation workstream.",
       "Each execution agent owns exactly one workstream and its tests.",
-      "Required execution agents: SDK Lifecycle Execution Agent, Semantic Snapshot Execution Agent, and Semantic Snapshot CI Execution Agent.",
+      "Required execution agents: SDK Lifecycle Execution Agent, Semantic Snapshot Readiness Execution Agent, and Semantic Snapshot CI Execution Agent.",
       "Run execution agents in parallel only when file ownership does not conflict; otherwise run them sequentially with monitor gates between workstreams.",
       "Use multiple monitoring agents for read-only checks, or named review passes if subagents are unavailable.",
-      "Run setup phases separately in this order: repository discovery, semantic snapshot, semantic snapshot CI, SDK lifecycle implementation, verification, final report.",
-      "Treat only semantic snapshot, semantic snapshot CI, and SDK lifecycle implementation as implementation workstreams with execution agents.",
+      "The initial `clue-ai setup --clue-api-key <key> --clue-api-base-url <url> --project-key <key> --environment <environment>` command already performs repository discovery, semantic CI workflow generation, setup manifest generation, and service-specific environment guidance when backend routes can be detected.",
+      "Before implementation, read `.clue/setup-manifest.json` and treat it as the mechanical setup source of truth.",
+      "Use the service keys and watch targets from `.clue/setup-manifest.json`; do not invent service keys.",
+      "If `.clue/setup-manifest.json` has status `blocked`, stop and report its blockers instead of guessing.",
+      "Treat only semantic snapshot readiness, semantic snapshot CI, and SDK lifecycle implementation as implementation workstreams with execution agents.",
       "Before each workstream, read and apply the matching Clue setup skill.",
       "After each implementation workstream, run a monitoring check with `clue-setup-audit` before continuing.",
       "For final local verification, read and apply `clue-local-verification`.",
@@ -61,37 +67,71 @@ const skillBody = (name) => {
       "Do not continue past P0/P1 monitoring findings until fixed or reported as blocked.",
     ],
     "clue-route-semantic-snapshot": [
-      "Use this skill as the source of truth for semantic snapshot content and structure.",
-      "Keep semantic snapshot authoring separate from CI workflow creation and SDK lifecycle implementation.",
+      "Use this skill as the source of truth for semantic snapshot readiness and route coverage verification.",
+      "Do not hand-author semantic snapshot content files.",
+      "Do not create or commit `.clue/semantic-request.runtime.json`; the semantic CI request must be passed through the generated workflow environment instead of a repository file.",
+      "Keep route coverage/readiness checks separate from CI workflow creation and SDK lifecycle implementation.",
       "Do not create CI workflow files or SDK lifecycle calls from this skill.",
+      "Do not create or commit `.clue/semantic-routes.json`; route inventory is dynamic and must be recomputed mechanically by `clue-ai semantic-inventory`, `clue-ai setup-check`, or `clue-ai semantic-ci`.",
+      "If route inventory must be inspected locally, run `npx @clue-ai/cli semantic-inventory --framework <framework> --backend-root-path <path> --repo .` and review stdout instead of writing a repo file.",
       "Inspect only allowed source paths.",
-      "Identify route, handler, controller, and endpoint behavior from privacy-safe evidence.",
-      "Create route entries with operation_source_key, method/path_template when available, route_summary, route_confidence, confidence_reason, and source_evidence_refs.",
-      "Create layer_evidence for data effects, side effects, validation, permissions, failures, and component fingerprints when available.",
-      "Create operation_effects only when target object evidence and domain behavior evidence are sufficient.",
-      "Create target_object_profiles, target_object_catalog, and target_object_mappings for accepted operation effects.",
-      "Preserve unresolved_operation_effects with missing_context instead of fabricating unknown operation effects.",
-      "Include source_evidence_refs and ai_inference_evidence without raw source, secrets, prompts, or completions.",
-      "Create semantic snapshot inputs without raw source, secrets, prompts, or completions.",
-      "Report unresolved routes as blockers instead of guessing.",
+      "Identify the backend framework, backend root path, route files, controllers, handlers, and route declaration patterns from privacy-safe evidence.",
+      "Run `npx @clue-ai/cli semantic-inventory --framework <framework> --backend-root-path <path> --repo .` whenever possible to verify route discovery without AI or secrets.",
+      "If `npx` cannot be used in the current environment, use the local `clue-ai semantic-inventory` command equivalent.",
+      "Verify that every API route can be discovered from the selected backend root path and that unsupported frameworks are reported as blockers.",
+      "The semantic snapshot CI command must mechanically enumerate operation_source_key, method, path_template, route fingerprints, and privacy-safe evidence before AI interpretation.",
+      "AI interpretation may summarize each mechanically discovered route, but it must not create missing routes or operation_source_key values.",
+      "The expected generated snapshot structure includes route entries with operation_source_key, method/path_template when available, route_summary, route_confidence, confidence_reason, and source_evidence_refs.",
+      "The expected generated snapshot structure includes layer_evidence for data effects, side effects, validation, permissions, failures, and component fingerprints when available.",
+      "The expected generated snapshot structure includes operation_effects only when target object evidence and domain behavior evidence are sufficient.",
+      "The expected generated snapshot structure preserves unresolved_operation_effects with missing_context instead of fabricating unknown operation effects.",
+      "Report route coverage gaps, unsupported backend frameworks, and unclear backend roots as blockers instead of guessing.",
     ],
     "clue-semantic-ci": [
       "Use this skill as the source of truth for semantic snapshot CI workflow format.",
-      "Keep CI workflow creation separate from semantic snapshot content authoring and SDK lifecycle implementation.",
-      "Do not author semantic snapshot content or SDK lifecycle calls from this skill.",
-      "Create or update `.github/workflows/clue-semantic-snapshot.yml`.",
-      "Use `npx @clue-ai/cli semantic-ci --request .clue/semantic-request.runtime.json --repo .`.",
+      "Keep CI workflow creation separate from route coverage/readiness checks and SDK lifecycle implementation.",
+      "Do not author semantic snapshot content, runtime request files, or SDK lifecycle calls from this skill.",
+      "Treat `.github/workflows/clue-semantic-snapshot.yml` as a machine-owned artifact generated by `clue-ai setup`; do not hand-edit it.",
+      "Create or update `.github/workflows/clue-semantic-snapshot.yml` only by running `npx @clue-ai/cli semantic-workflow --framework <framework> --backend-root-path <path> --repo .` when it must be refreshed.",
+      "If `npx` cannot be used in the current environment, use the local `clue-ai semantic-workflow` command equivalent instead of hand-writing the workflow.",
+      "The workflow must pass `CLUE_SEMANTIC_REQUEST_JSON` through the workflow environment and then call `npx @clue-ai/cli semantic-ci --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .`.",
+      "Do not create, commit, or stage `.clue/semantic-request.runtime.json` in the customer repository.",
+      "The workflow must not send GitHub actor, triggering_actor, sender, repository owner, repository name, or default branch to Clue.",
+      "The workflow should send only repository id, commit sha, workflow run id, project key variable, service key, framework, source path allowlist, source path denylist, Clue API base URL variable, and AI model variable.",
+      "Use minimal GitHub permissions and checkout without persisted credentials when generating the workflow.",
       "Reference GitHub Secrets and Variables by name only.",
+      "Required GitHub secrets are `CLUE_API_KEY` and `CLUE_AI_PROVIDER_API_KEY`.",
+      "Required GitHub variables are `CLUE_AI_PROVIDER` and `CLUE_AI_MODEL`.",
       "Do not print or commit secret values.",
     ],
     "clue-sdk-instrumentation": [
       "Use this skill as the source of truth for Clue SDK lifecycle implementation.",
       "Keep SDK lifecycle implementation separate from semantic snapshot and CI workflow work.",
       "Do not create semantic snapshot content or semantic snapshot CI workflow files from this skill.",
+      "Do not create no-op wrappers around nonexistent `window.Clue*` globals or local placeholder functions.",
+      "Lifecycle calls must resolve to real Clue SDK imports or a real repository adapter that forwards to the Clue SDK.",
+      "Every Clue lifecycle call must be failure-isolated with try/catch, try/except, `.catch`, or an explicit safe Clue helper so Clue failure never stops the host service.",
+      "Never await a Clue lifecycle call in a way that can block login, logout, account selection, request handling, page rendering, or API responses.",
+      "Add or report the required SDK dependency instead of fabricating lifecycle APIs.",
+      "When lifecycle edits are clear, write an exact replacement plan to a temporary local JSON file and apply it with `npx @clue-ai/cli lifecycle-apply --plan <plan-file> --repo .`.",
+      "If `npx` cannot be used in the current environment, use the local `clue-ai lifecycle-apply` command equivalent instead of manually applying the exact replacements.",
+      "Delete the temporary lifecycle plan file after applying it unless the user explicitly asks to keep it for review.",
+      "Use environment variable names for Clue configuration values; do not paste project keys or API keys into code.",
+      "For local env files, use the service-specific env blocks printed by `clue-ai setup`; do not ask the user to guess `CLUE_SERVICE_KEY`.",
+      "For browser code, use `CLUE_PROJECT_KEY`, `CLUE_ENVIRONMENT`, and `CLUE_INGEST_ENDPOINT`. Let the target framework expose or inject those values safely without hard-coding a Next.js-only prefix.",
+      "For FastAPI code, add `clue-fastapi-sdk` to the backend dependency file when missing, import `clue_init_fastapi` plus `ClueIdentify`, `ClueSetAccount`, and `ClueLogout` where needed, and use `CLUE_PROJECT_KEY`, `CLUE_ENVIRONMENT`, `CLUE_API_KEY`, and `CLUE_INGEST_ENDPOINT`.",
+      "Use `CLUE_SERVICE_KEY` as the canonical local service identifier. Do not ask the user to manage a separate producer id; SDKs should send producer id as the service key for setup verification compatibility.",
+      "For frontend code, pass `serviceKey` from `CLUE_SERVICE_KEY` to `ClueInit`. Do not require a separate producer id unless the repository already has one for compatibility.",
+      "For Django code, add `clue-django-sdk` to the backend dependency file when missing and use the Django SDK lifecycle helpers.",
+      "For other backend frameworks, use the matching Clue backend SDK if one exists; if no backend SDK exists, report a blocker instead of silently frontend-only setup.",
+      "Do not send raw email, raw person names, tokens, workspace names, organization names, or tenant names as lifecycle traits unless the repository already has an explicit Clue privacy policy allowing them.",
+      "Prefer stable ids and non-PII booleans/counts for ClueIdentify and ClueSetAccount traits.",
       "Find the app/bootstrap entrypoint and add ClueInit only when the location is clear.",
-      "Find login success handling and add ClueIdentify only when the user identity is available.",
-      "Find account, workspace, organization, or tenant resolution and add ClueSetAccount only when the subject is available.",
-      "Find logout/sign-out completion and add ClueLogout only when the session reset point is clear.",
+      "Place ClueInit in a stable app bootstrap, SDK adapter, or client singleton; do not place ClueInit inside React component lifecycle hooks, page components, sidebars, login/register success callbacks, or other paths that can run repeatedly.",
+      "If the repository needs lifecycle calls from UI hooks, import a shared initialized Clue adapter instead of calling ClueInit again.",
+      "Find every clear frontend and backend login success path and add ClueIdentify to every one when the user identity is available.",
+      "Find every clear frontend and backend account, workspace, organization, or tenant resolution path and add ClueSetAccount to every one when the subject is available.",
+      "Find every clear frontend and backend logout/sign-out/session reset completion path and add ClueLogout to every one when the reset point is clear.",
       "Skip unclear lifecycle points and report blockers.",
     ],
     "clue-setup-audit": [
@@ -99,6 +139,14 @@ const skillBody = (name) => {
       "Check one completed workstream at a time and report P0/P1 issues before more implementation continues.",
       "Review changed files line by line.",
       "Verify semantic snapshot, semantic CI, and SDK lifecycle responsibilities did not bleed into each other.",
+      "Reject hand-authored semantic snapshot content and runtime request files.",
+      "Reject semantic CI workflows that were not generated by or equivalent to `clue-ai semantic-workflow`.",
+      "Reject semantic CI workflows that send GitHub actor, triggering_actor, sender, repository owner, repository name, or default branch to Clue.",
+      "Reject no-op lifecycle wrappers or lifecycle calls that do not resolve to a real Clue SDK import.",
+      "Reject backend setup when backend routes exist but no backend Clue SDK dependency/import/init was added.",
+      "Reject lifecycle calls that are not failure-isolated; Clue failure must never stop the host service.",
+      "Reject setup that covers only one login path when multiple login success paths are clearly present.",
+      "Reject ClueInit inside React component lifecycle hooks, page components, sidebars, login/register success callbacks, or any repeated user interaction path.",
       "Reject broad ClueTrack instrumentation and DOM clue tags.",
       "Confirm no project key, API key, secret, or env value appears in diff or report.",
       "Confirm lifecycle insertions are minimal and reviewable.",
@@ -108,6 +156,15 @@ const skillBody = (name) => {
       "Verify each workstream independently before the final setup report.",
       "Confirm generated skill files exist.",
       "Confirm workflow files and SDK lifecycle imports/calls exist when those phases have run.",
+      "Confirm backend routes have a backend Clue SDK dependency/import/init when a backend exists.",
+      "Confirm `.github/workflows/clue-semantic-snapshot.yml` calls `npx @clue-ai/cli semantic-ci --request-env CLUE_SEMANTIC_REQUEST_JSON`.",
+      "Confirm the semantic workflow does not send GitHub actor, triggering_actor, sender, repository owner, repository name, or default branch to Clue.",
+      "Confirm `.clue/semantic-request.runtime.json` is not created, committed, or staged.",
+      "Run `npx @clue-ai/cli setup-check --framework <framework> --backend-root-path <path> --repo . --target <codex|claude_code> --require-sdk-lifecycle` when possible.",
+      "For interactive local verification, run `npx @clue-ai/cli setup-watch --project-key <project-key> --environment <environment> --clue-api-base-url <clue-api-base-url> --watch-targets frontend:<service-key>[init,identify,set-account,event-sent]=<frontend-url>,backend:<service-key>[init,identify,set-account,logout,event-sent]=<backend-url>` and operate every local frontend/backend service until all expected checks pass.",
+      "Only include lifecycle checks that the implementation ownership plan expects for that service. If a service emits an undeclared lifecycle event, treat it as a possible duplicate instrumentation issue.",
+      "Never assume localhost ports. Ask the repository scripts, env examples, or the running service output for the actual frontend/backend URLs.",
+      "If `npx` cannot be used in the current environment, use the local `clue-ai setup-check` command equivalent.",
       "Confirm only env names are reported.",
       "Leave event delivery verification to the Clue setup screen.",
     ],
@@ -153,7 +210,10 @@ const skillBody = (name) => {
   ].join("\n");
 };
 
-const askTarget = async ({ input = process.stdin, output = process.stdout } = {}) => {
+const askTarget = async ({
+  input = process.stdin,
+  output = process.stdout,
+} = {}) => {
   const rl = readline.createInterface({ input, output });
   try {
     const answer = await rl.question(
@@ -171,9 +231,14 @@ export const installSetupSkills = async ({
   input,
   output,
 } = {}) => {
-  const resolvedTarget = target ? normalizeTarget(target) : await askTarget({ input, output });
+  const resolvedTarget = target
+    ? normalizeTarget(target)
+    : await askTarget({ input, output });
   const resolvedRepoRoot = resolve(repoRoot ?? ".");
-  const skillRoot = join(resolvedRepoRoot, ...TARGET_SKILL_ROOTS[resolvedTarget]);
+  const skillRoot = join(
+    resolvedRepoRoot,
+    ...TARGET_SKILL_ROOTS[resolvedTarget],
+  );
   const installed = [];
 
   for (const skillName of SKILL_NAMES) {
@@ -188,6 +253,8 @@ export const installSetupSkills = async ({
     target: resolvedTarget,
     skill_root: join(...TARGET_SKILL_ROOTS[resolvedTarget]),
     skills: SKILL_NAMES,
-    installed_files: installed.map((path) => path.replace(`${resolvedRepoRoot}/`, "")),
+    installed_files: installed.map((path) =>
+      path.replace(`${resolvedRepoRoot}/`, ""),
+    ),
   };
 };