swallowkit 2.0.0-alpha.4 → 2.0.0-alpha.5

package/src/core/project/agent-templates/AGENTS.md

@@ -319,6 +319,20 @@ custom endpoints that derive the scoping key (e.g. `learnerId`) from the
 verified principal — never from the request body — and restrict the generated
 write endpoints to admin roles.
 
+Configure authentication with `plan auth` / `apply auth` **before** declaring
+`authPolicy`. Without authentication, an explicit policy
+blocks plan/apply/scaffold with `auth-policy-without-auth` before file writes;
+follow `nextActions`, then re-plan. Do not remove a required policy just to pass
+generation.
+An empty `authPolicy = {}` means no explicit policy; it does not enable authentication.
+
+With named `auth.schemes`, define `auth.authorization.policies` selecting the
+required schemes and roles, then use `authPolicy = { policy: 'adminOnly' }` (or
+read/write policy names). Role-only declarations do not select a named scheme
+and block with `auth-policy-requires-named-policy`. Conversely, single-provider
+`auth.provider` supports role lists only; a named policy (including a named
+`defaultPolicy`) blocks with `auth-named-policy-requires-named-scheme`.
+
 ## Verification Is a Completion Gate
 
 Before treating an agent-driven implementation as complete, run SwallowKit
@@ -330,8 +344,17 @@ verification:
 
 or the equivalent MCP operation.
 
-Verification covers SwallowKit structural correctness, drift, type correctness,
-and configured project checks.
+Default checks are `structure`, `drift`, `typecheck`, `backend-build`, plus
+configured project checks. `backend-build` checks standalone `functions/`:
+C# uses `dotnet build`, TypeScript uses the project's `tsc --noEmit`, and Python
+uses Python 3 `compileall` (syntax only, not imports or type checking), preferring
+`functions/.venv` over PATH. Missing toolchains are `skip` with an explanation;
+a skipped backend check is **not** evidence that the backend works. Restore the
+toolchain and re-run it before claiming backend validation.
+
+Root `build` scripts do not replace standalone backend verification. To include
+frontend production builds, use `--checks "structure,drift,typecheck,backend-build,build"`.
+Quote comma-separated values in PowerShell.
 
 When verification fails, use the structured failure explanation:
 
@@ -474,7 +497,9 @@ same generated structure.
 - Model schema files use `shared/models/{kebab-case}.ts`.
 - The Zod schema constant and inferred TypeScript type use the same PascalCase
   name: `export const Todo = z.object(...); export type Todo = z.infer<typeof Todo>`.
-- Re-export models from `shared/index.ts`.
+- Re-export models from `shared/index.ts`. create-model and plan/apply scaffold
+  append missing exports, including manually authored models. Manual exports
+  are allowed; this file has no managed markers and existing content is preserved.
 - `id` is a required `z.string()`; only `createdAt` / `updatedAt` are optional
   backend-managed fields.
 - Models may declare `partitionKey`, `authPolicy`, `displayName`,

package/src/core/project/agent-templates/CLAUDE.md

@@ -25,6 +25,10 @@ Always-on rules:
 - Use plan/apply for deterministic generation.
 - Respect all `requires-human` states and provisioning approval gates.
 - Run SwallowKit verification before considering implementation complete.
+- Default verification includes `backend-build` for standalone Functions.
+  Skipped toolchains are not validation; Python compilation checks syntax only.
+- Configure auth via plan/apply auth before adding `authPolicy`; otherwise
+  scaffold blocks before file writes. Scaffold appends missing shared model exports.
 
 Task-specific SwallowKit Agent Skills are available under `.github/skills/`.
 Equivalent agent-agnostic runbooks are available under

package/src/core/project/agent-templates/copilot-instructions.md

@@ -24,6 +24,10 @@ Key rules:
 - Use plan/apply for deterministic generation.
 - Respect `requires-human` states and other human approval gates.
 - Run SwallowKit verification before completion.
+- Default verification includes `backend-build` for standalone Functions.
+  Skipped toolchains are not validation; Python compilation checks syntax only.
+- Configure auth via plan/apply auth before adding `authPolicy`; otherwise
+  scaffold blocks before file writes. Scaffold appends missing shared model exports.
 
 Task-specific SwallowKit Agent Skills live under `.github/skills/`.
 Agent-agnostic equivalents live under `.swallowkit/workflows/`.

package/src/core/project/agent-templates/shared-models.instructions.md

@@ -18,8 +18,9 @@ source-of-truth models, subject to the current result of
 - `createdAt` and `updatedAt` are **optional** string fields
   (`z.string().optional()`). The backend manages their values.
 - Export a `displayName` string for UI display.
-- Re-export every model from `shared/index.ts`, outside managed markers where
-  applicable.
+- create-model and plan/apply scaffold append missing model exports to
+  `shared/index.ts`, including manually authored models. Manual exports are
+  allowed; there are no managed markers and existing content is preserved.
 - For relationships, use nested schemas rather than duplicating model shapes.
 
 ## Optional model declarations (exact formats)
@@ -30,7 +31,7 @@ These are the only declarations SwallowKit parses from a model file:
 // Cosmos DB partition key (default '/id'). Must reference a schema field.
 export const partitionKey = '/learnerId';
 
-// Role-based access control on generated CRUD.
+// Role-based access control on generated CRUD (requires plan/apply auth first).
 export const authPolicy = { roles: ['admin'] };
 // or: { read: ['user'], write: ['admin'] } or: { policy: 'adminOnly' }
 
@@ -48,6 +49,13 @@ export const connectorConfig = {
 The full machine-readable contract:
 `{{runCmd}} swallowkit machine inspect capabilities`
 
+An explicit `authPolicy` without authentication blocks plan/apply/scaffold with
+`auth-policy-without-auth` before writing files. Follow `nextActions` to configure
+auth, then re-plan. Do not drop a required guard to bypass the prerequisite.
+For named `auth.schemes`, use named authorization policies selecting schemes
+and roles, referenced by `policy` or read/write names. Role-only declarations
+block with `auth-policy-requires-named-policy` rather than emitting missing helpers.
+
 After changing a model, do not manually patch generated artifacts.
 
 ## After changing a model

package/src/core/project/boundaries.ts

@@ -86,7 +86,7 @@ export const OWNERSHIP_POLICIES: OwnershipPolicy[] = [
     zone: "shared",
     editPolicy: "edit-outside-markers",
     howToChange:
-      "SwallowKit appends only inside marked sections (e.g. `# SwallowKit scaffold registrations`). Edit anywhere outside the markers freely; do not remove the markers.",
+      "SwallowKit appends at the file-specific extension point: marked sections (e.g. `# SwallowKit scaffold registrations`) or append-only files such as shared/index.ts. Follow the path rule; preserve existing generated entries and any markers.",
   },
   {
     ownership: "metadata",
@@ -134,8 +134,8 @@ const COMMON_LEADING_RULES: BoundaryPathRule[] = [
   {
     pattern: "shared/index.ts",
     zone: "shared",
-    editPolicy: "edit-outside-markers",
-    description: "SwallowKit appends model exports; other exports may be added freely.",
+    editPolicy: "free-edit",
+    description: "create-model and scaffold append missing model exports while preserving existing content. No managed markers; manual exports are allowed. Keep exports needed by generated code.",
   },
 ];
 

package/src/core/project/capabilities.ts

@@ -65,6 +65,7 @@ export interface CapabilitiesContract {
     defaultChecks: string[];
     optInChecks: string[];
     customChecks: string;
+    backendBuild: string;
   };
 }
 
@@ -109,6 +110,11 @@ export function inspectCapabilities(): CapabilitiesContract {
           "Role-based access control metadata applied to the generated CRUD Functions. `roles` guards all operations; `read`/`write` guard per-operation; `policy` references a named authorization policy from swallowkit.config auth.authorization.policies.",
         format:
           "export const authPolicy = { roles: ['admin'] };\n// or per-operation:\nexport const authPolicy = { read: ['user'], write: ['admin'] };\n// or a named policy:\nexport const authPolicy = { policy: 'adminOnly' };",
+        notes: [
+          "An explicit authPolicy without configured authentication blocks plan/apply/generate scaffold with auth-policy-without-auth before any artifacts are written. Run plan auth, apply auth, then re-plan scaffold. An empty {} declaration keeps the existing behavior: no explicit policy.",
+          "With named auth.schemes, define auth.authorization.policies selecting schemes and roles, then reference them via policy or read/write names. A role-only declaration cannot select a named scheme and blocks with auth-policy-requires-named-policy; it is supported by legacy single-provider authentication.",
+          "Conversely, single-provider authentication (auth.provider) supports role lists only. Referencing a named policy (authPolicy.policy, read/write names, or a named auth.authorization.defaultPolicy) blocks with auth-named-policy-requires-named-scheme; add a named scheme first.",
+        ],
       },
       {
         name: "references",
@@ -186,7 +192,7 @@ export function inspectCapabilities(): CapabilitiesContract {
         "Without authentication, plan scaffold reports user-scoped-data-without-auth when the partition key or an owner-like field (userId, learnerId, ownerId, ...) suggests per-user data.",
       ],
       guidance: [
-        "For multi-user data where users may only touch their own records, add ai-authored custom endpoints that derive the scoping key (e.g. learnerId) from the verified principal — never from the request body — and restrict generated write endpoints to admin roles or disable them.",
+        "Configure authentication via plan/apply auth before declaring authPolicy. For multi-user data where users may only touch their own records, add ai-authored custom endpoints that derive the scoping key (e.g. learnerId) from the verified principal — never from the request body — and restrict generated write endpoints to admin roles or disable them.",
       ],
     },
     sharedModels: {
@@ -200,7 +206,7 @@ export function inspectCapabilities(): CapabilitiesContract {
         "String formats (email/uuid/url), refinements, and transforms are not re-implemented natively; the BFF Zod schemas remain the authoritative validation.",
       ],
       buildNote:
-        "verify typecheck resolves the shared package from its built dist/. SwallowKit rebuilds shared automatically during verify; when typechecking manually, build the shared package first (errors like \"no exported member\" usually mean a stale dist).",
+        "create-model and plan/apply scaffold append missing model exports to shared/index.ts, including manually authored models. Manual exports are allowed (no markers); existing content is preserved. verify typecheck resolves the shared package from its built dist/. SwallowKit rebuilds shared automatically during verify; when typechecking manually, build shared first.",
     },
     seeding: {
       createTemplates: "swallowkit create-dev-seeds <environment> — writes dev-seeds/<environment>/<model>.json templates.",
@@ -219,9 +225,10 @@ export function inspectCapabilities(): CapabilitiesContract {
       "(regular CLI) configure-mcp [--version auto|latest|<semver>] — re-select the MCP launcher version in .mcp.json",
     ],
     verifyChecks: {
-      defaultChecks: ["structure", "drift", "typecheck"],
+      defaultChecks: ["structure", "drift", "typecheck", "backend-build"],
       optInChecks: ["build", "lint", "test"],
       customChecks: "swallowkit.config verify.checks: [{ id, command, title?, timeoutMs? }]",
+      backendBuild: "Runs dotnet build in functions/ (C#), the project tsc --noEmit (TypeScript), or Python 3 compileall (syntax only, using functions/.venv before PATH). Missing toolchains are skip with a reason, not proof of validation. Root build scripts do not replace backend-build; use --checks \"structure,drift,typecheck,backend-build,build\" for both.",
     },
   };
 }

package/src/core/project/react-project.ts

@@ -407,7 +407,7 @@ live in \`functions/local.settings.json\`. Keep their secrets out of source cont
 \`\`\`sh
 ${pm} run build
 ${cmd.exec} swallowkit machine verify project
-${cmd.exec} swallowkit machine verify project --checks structure,drift,typecheck,build
+${cmd.exec} swallowkit machine verify project --checks "structure,drift,typecheck,backend-build,build"
 \`\`\`
 
 The build compiles shared schemas, checks the SPA, builds static assets, and

package/src/core/project/workflows.ts

@@ -62,6 +62,13 @@ Goal: add a data model and derive CRUD/BFF/UI/infra deterministically.
      the plan warns \`infra-skipped\`; later run \`${runCmd} swallowkit migrations add-model <name>\` to add only the container migration.
    - Read \`data.warnings\`. \`user-scoped-data-without-auth\` means generated CRUD would expose every user's documents;
      add auth (\`swallowkit-add-auth\`) and owner-scoped ai-authored endpoints before exposing the model.
+   - \`auth-policy-without-auth\` blocks generation before file writes: configure authentication with plan/apply auth,
+     then re-plan. Do not remove a required policy to bypass this prerequisite.
+     For named \`auth.schemes\`, define named authorization policies selecting schemes/roles and reference them from
+     \`authPolicy.policy\` or read/write names; role-only declarations block with \`auth-policy-requires-named-policy\`.
+     Single-provider \`auth.provider\` supports role lists only; named policies block with \`auth-named-policy-requires-named-scheme\`.
+   - Scaffold appends missing exports to \`shared/index.ts\` for hand-authored models too.
+     Manual exports are allowed; no managed markers exist in that file.
 4. Apply:
    \`${runCmd} swallowkit machine apply scaffold --plan <planId>\`
 5. Verify:
@@ -160,7 +167,7 @@ the scoping key from the verified principal, never from the request body.
     title: "Verify and repair loop",
     skillName: "swallowkit-verify-repair",
     skillDescription:
-      "Converge a SwallowKit project to a verified state: run structure/drift/typecheck (and build/lint/test) checks, read evidence with explain failure, repair, and repeat. Use after any code or schema change, when verification fails, when the build/lint/tests are broken, or before finishing a task.",
+      "Converge a SwallowKit project to a verified state: run structure/drift/typecheck/backend-build (and build/lint/test) checks, read evidence with explain failure, repair, and repeat. Use after any code or schema change, when verification fails, when the build/lint/tests are broken, or before finishing a task.",
     content: `# Workflow: Verify and repair
 
 Goal: converge the project to a verified state after any change.
@@ -168,14 +175,16 @@ Goal: converge the project to a verified state after any change.
 ## Loop
 
 1. \`${runCmd} swallowkit machine verify project\`
-   - default checks: structure, drift, typecheck (+ project-specific checks from swallowkit.config \`verify.checks\`)
-   - opt-in heavier checks: \`--checks structure,drift,typecheck,build,lint,test\`
+   - default checks: structure, drift, typecheck, backend-build (+ project-specific checks from swallowkit.config \`verify.checks\`)
+   - backend-build: standalone C# \`dotnet build\`, TypeScript \`tsc --noEmit\`, Python 3 \`compileall\` (syntax only).
+     Missing toolchains are skipped with a reason, not proof of a working backend. Restore them and re-run.
+   - opt-in heavier checks: \`--checks "structure,drift,typecheck,backend-build,build,lint,test"\` (quote CSV in PowerShell)
 2. If \`summary.done\` is false:
    - \`${runCmd} swallowkit machine explain failure\` → evidence (logTail, findings, violations) and suggestedActions per check.
    - Repair:
      - \`drift\` failures → follow each finding's \`repairAction\` (usually re-run plan/apply scaffold).
      - \`structure\` failures → follow \`suggestedFix\` per violation.
-     - \`typecheck\`/\`build\`/\`lint\`/\`test\` failures → fix the code in ai-authored files.
+     - \`typecheck\`/\`backend-build\`/\`build\`/\`lint\`/\`test\` failures → fix the source code, not generated artifacts.
 3. Repeat until \`summary.done: true\`.
 
 ## Exit criteria
@@ -254,7 +263,8 @@ under \`.github/skills/\` so skills-aware agents load them automatically.
 
 - **ai-authored** (write freely): \`shared/models/\`, business logic, custom pages/components, tests.
 - **deterministic** (never hand-edit): artifacts generated by SwallowKit (see \`.swallowkit/artifacts.json\`) and \`.swallowkit/\` metadata. Change models/config and regenerate via plan/apply.
-- **shared** (edit outside markers): \`shared/index.ts\`, plus backend registration files for the configured language (Python: \`functions/function_app.py\`).
+- **shared**: \`shared/index.ts\` allows manual exports (no markers; SwallowKit appends missing entries).
+  For Python \`functions/function_app.py\`, edit outside the registration marker.
 - **infrastructure**: baseline \`infra/\` files are checksum-locked by \`infra/migrations/manifest.json\`; add resources as new migrations (\`swallowkit create-migration <slug>\`, \`swallowkit migrations add-model <model>\`).
 
 Full machine-readable contract: \`${runCmd} swallowkit machine inspect boundaries\`

package/src/core/scaffold/auth-generator.ts

@@ -117,8 +117,7 @@ export function generateNamedAuthRouterCSharp(config: NormalizedAuthConfig): str
 using System.Text;
 using System.Text.Json;
 using Microsoft.Azure.Functions.Worker.Http;
-using Functions.Auth.Schemes;
-namespace Functions.Auth;
+${externalCases ? "using Functions.Auth.Schemes;\n" : ""}namespace Functions.Auth;
 public record AuthPrincipal(string Subject, string Scheme, string Issuer, string[] Roles, IReadOnlyDictionary<string, object?> Claims)
 {
     [Obsolete("Use Subject")] public string UserId => Subject;
@@ -171,15 +170,15 @@ ${externalCases}
 export function generateNamedAuthRouterPython(config: NormalizedAuthConfig): string {
   const external = Object.entries(config.schemes).filter(([,s])=>s.provider === "external-token");
   const imports = external.map(([n])=>`from auth.schemes.${schemeSlug(n).replace(/-/g,"_")}.verifier import verify_external_token as verify_${safeIdentifier(n)}, ExternalTokenVerificationError as Error_${safeIdentifier(n)}`).join("\n");
-  const cases = external.map(([n], index)=>`        ${index === 0 ? "if" : "elif"} scheme == ${JSON.stringify(n)}:
-            try:
-                value = verify_${safeIdentifier(n)}(bearer)
-            except Error_${safeIdentifier(n)} as exc:
-                raise AuthError(503 if exc.identity_provider_unavailable else 401, "Identity provider unavailable" if exc.identity_provider_unavailable else "Invalid token")
-            except Exception:
-                raise AuthError(503, "External token verifier unavailable")
-            if not value.get("subject") or not isinstance(value.get("roles"), list): raise AuthError(401, "Invalid external principal")
-            principal = {"subject": value["subject"], "scheme": scheme, "issuer": value.get("issuer", scheme), "roles": value["roles"], "claims": value.get("claims", {}), "userId": value["subject"]}`).join("\n");
+  const cases = external.map(([n], index)=>`    ${index === 0 ? "if" : "elif"} scheme == ${JSON.stringify(n)}:
+        try:
+            value = verify_${safeIdentifier(n)}(bearer)
+        except Error_${safeIdentifier(n)} as exc:
+            raise AuthError(503 if exc.identity_provider_unavailable else 401, "Identity provider unavailable" if exc.identity_provider_unavailable else "Invalid token")
+        except Exception:
+            raise AuthError(503, "External token verifier unavailable")
+        if not value.get("subject") or not isinstance(value.get("roles"), list): raise AuthError(401, "Invalid external principal")
+        principal = {"subject": value["subject"], "scheme": scheme, "issuer": value.get("issuer", scheme), "roles": value["roles"], "claims": value.get("claims", {}), "userId": value["subject"]}`).join("\n");
   return `import base64
 import json
 import azure.functions as func
@@ -199,14 +198,14 @@ def require_auth(req: func.HttpRequest, policy_name: str):
     if len(candidates) != 1: raise AuthError(401, "Authentication required" if not candidates else "Ambiguous credentials")
     scheme = candidates[0]
 ${cases}
-        ${external.length ? "elif" : "if"} PROVIDERS[scheme] == "swa":
-            try:
-                value=json.loads(base64.b64decode(swa).decode("utf-8")); roles=[r for r in value.get("userRoles",[]) if isinstance(r,str)]
-                if not value.get("userId") or "authenticated" not in roles: raise ValueError()
-                if ALLOWED_PROVIDERS[scheme] and value.get("identityProvider") not in ALLOWED_PROVIDERS[scheme]: raise ValueError()
-                principal={"subject":value["userId"],"scheme":scheme,"issuer":"swa:"+value.get("identityProvider", "unknown"),"roles":roles,"claims":value,"userId":value["userId"]}
-            except Exception: raise AuthError(401,"Invalid SWA client principal")
-        else: raise AuthError(401,"Authentication adapter is not configured")
+    ${external.length ? "elif" : "if"} PROVIDERS[scheme] == "swa":
+        try:
+            value=json.loads(base64.b64decode(swa).decode("utf-8")); roles=[r for r in value.get("userRoles",[]) if isinstance(r,str)]
+            if not value.get("userId") or "authenticated" not in roles: raise ValueError()
+            if ALLOWED_PROVIDERS[scheme] and value.get("identityProvider") not in ALLOWED_PROVIDERS[scheme]: raise ValueError()
+            principal={"subject":value["userId"],"scheme":scheme,"issuer":"swa:"+value.get("identityProvider", "unknown"),"roles":roles,"claims":value,"userId":value["userId"]}
+        except Exception: raise AuthError(401,"Invalid SWA client principal")
+    else: raise AuthError(401,"Authentication adapter is not configured")
     require_roles(principal, policy.get("roles", [])); return principal
 def require_roles(principal, roles):
     if roles and not any(role in principal.get("roles",[]) for role in roles): raise AuthError(403,"Insufficient permissions")

package/src/core/scaffold/native-schema-generator.ts

@@ -939,6 +939,21 @@ function ensurePythonCodegenProjectFiles(
   return requirementsPath;
 }
 
+/** Generated backend_models import pydantic v2 at runtime, so the deployed Functions app must install it. */
+export const PYTHON_SCHEMA_RUNTIME_REQUIREMENT = "pydantic>=2.6,<3";
+
+function ensurePythonRuntimeRequirement(functionsRoot: string, session: FileOperationSession): void {
+  const requirementsPath = path.join(functionsRoot, "requirements.txt");
+  const current = session.fileExists(requirementsPath) ? session.readFile(requirementsPath) : "";
+  const declared = current.split(/\r?\n/).some((line) => line.trim().split(/[<>=!~;[ ]/)[0].toLowerCase() === "pydantic");
+  if (declared) return;
+  const prefix = current && !current.endsWith("\n") ? `${current}\n` : current;
+  session.writeFile(requirementsPath, `${prefix}${PYTHON_SCHEMA_RUNTIME_REQUIREMENT}\n`, {
+    ownership: "extension-point",
+    generator: "native-schema",
+  });
+}
+
 async function ensureProjectLocalUvCommand(projectRoot: string): Promise<{ command: string; env: NodeJS.ProcessEnv }> {
   const uvEnv = { ...process.env };
   const { localUvExecutable } = getProjectLocalUvPaths(projectRoot);
@@ -1082,6 +1097,7 @@ async function generatePythonSchemaArtifacts(
   sourceModel: string
 ): Promise<void> {
   ensurePythonCodegenProjectFiles(functionsRoot, session, sourceModel);
+  ensurePythonRuntimeRequirement(functionsRoot, session);
 
   const packageRoot = path.join(outputDir, "backend_models");
   const modelsRoot = path.join(packageRoot, "models");

package/src/core/verify/index.ts

@@ -5,16 +5,17 @@
  * - structure:  プロジェクト構造規約 (validateProject)
  * - drift:      生成物と現在状態の乖離 (detectDrift)
  * - typecheck:  TypeScript 型チェック (tsc --noEmit / typecheck script)
+ * - backend-build: standalone Functions のコンパイル (C#/TypeScript) または構文検証 (Python)
  * - build/lint/test: package.json scripts に同名 script がある場合のみ実行 (なければ skip)
  * - custom:     swallowkit.config の verify.checks で定義されたプロジェクト固有チェック
  *
- * 既定実行セットは structure/drift/typecheck + custom。build/lint/test は --checks で明示指定。
+ * 既定実行セットは structure/drift/typecheck/backend-build + custom。build/lint/test は --checks で明示指定。
  */
 
 import * as fs from "fs";
 import * as path from "path";
 import { spawnSync } from "child_process";
-import { loadConfig } from "../config";
+import { loadConfig, loadConfigFromEnv } from "../config";
 import { detectDrift, DriftFinding } from "../project/drift";
 import { saveLastVerifyState } from "../project/state";
 import { ProjectViolation, validateProject } from "../project/validation";
@@ -60,11 +61,11 @@ export interface VerifyResult {
   verifiedAt: string;
 }
 
-export const AVAILABLE_VERIFY_CHECKS = ["structure", "drift", "typecheck", "build", "lint", "test"] as const;
+export const AVAILABLE_VERIFY_CHECKS = ["structure", "drift", "typecheck", "backend-build", "build", "lint", "test"] as const;
 export type VerifyCheckId = (typeof AVAILABLE_VERIFY_CHECKS)[number];
 
 /** 既定で実行される built-in チェック。build/lint/test は明示指定時のみ。 */
-export const DEFAULT_VERIFY_CHECKS = ["structure", "drift", "typecheck"] as const;
+export const DEFAULT_VERIFY_CHECKS = ["structure", "drift", "typecheck", "backend-build"] as const;
 
 async function runStructureCheck(projectRoot: string): Promise<VerifyCheckResult> {
   const startedAt = Date.now();
@@ -137,6 +138,7 @@ interface CommandCheckSpec {
   args: string[];
   timeoutMs?: number;
   failAction: string;
+  shell?: boolean;
 }
 
 function runCommandCheck(projectRoot: string, spec: CommandCheckSpec): VerifyCheckResult {
@@ -145,9 +147,10 @@ function runCommandCheck(projectRoot: string, spec: CommandCheckSpec): VerifyChe
   try {
     const result = spawnSync(spec.command, spec.args, {
       cwd: projectRoot,
-      shell: true,
+      shell: spec.shell ?? true,
       encoding: "utf-8",
       timeout: spec.timeoutMs ?? 5 * 60 * 1000,
+      maxBuffer: 10 * 1024 * 1024,
     });
 
     const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
@@ -180,6 +183,11 @@ function runCommandCheck(projectRoot: string, spec: CommandCheckSpec): VerifyChe
         command: commandLabel,
         exitCode,
         logTail: tailLines(output, 50),
+        ...(spec.id === "backend-build" ? {
+          diagnostics: [...new Set(output.split(/\r?\n/).filter((line) =>
+            /\(\d+,\d+\):\s*error\s+\w+/.test(line) ||
+            /^\s*(File ".+", line \d+|(?:Sorry: )?(?:Syntax|Indentation|Tab)Error:|\*\*\* Error compiling)/.test(line)))],
+        } : {}),
       },
       suggestedActions: exitCode === 0 ? [] : [spec.failAction],
     };
@@ -201,6 +209,86 @@ function runCommandCheck(projectRoot: string, spec: CommandCheckSpec): VerifyChe
   }
 }
 
+function backendUnavailable(reason: string): VerifyCheckResult {
+  return {
+    id: "backend-build",
+    title: "Standalone Functions compilation",
+    status: "skip",
+    durationMs: 0,
+    fixable: false,
+    evidence: { logTail: [reason], diagnostics: [reason] },
+    suggestedActions: ["Install or restore the backend toolchain, then re-run verify with --checks \"backend-build\". A skipped check is not backend validation."],
+  };
+}
+
+function runBackendBuildCheck(projectRoot: string): VerifyCheckResult {
+  const functionsRoot = path.join(projectRoot, "functions");
+  if (!fs.existsSync(functionsRoot)) return backendUnavailable("functions/ not found; no standalone backend was checked.");
+  const configPath = ["swallowkit.config.json", "swallowkit.config.js", ".swallowkitrc.json"]
+    .map((name) => path.join(projectRoot, name)).find((file) => fs.existsSync(file));
+  if (!configPath) return backendUnavailable("SwallowKit configuration not found; backend language is unknown.");
+  // Same effective language as generation (getBackendLanguage): env override, then file, invalid -> typescript.
+  const configured = loadConfigFromEnv().backend?.language ?? loadConfig(configPath, true, true).backend?.language;
+  const language = configured && ["typescript", "csharp", "python"].includes(configured) ? configured : "typescript";
+  let command: string;
+  let args: string[];
+  if (language === "csharp") {
+    command = "dotnet";
+    args = ["build", "--nologo"];
+    const probe = spawnSync(command, ["--version"], { cwd: functionsRoot, encoding: "utf-8", timeout: 30_000 });
+    if (probe.error && "code" in probe.error && probe.error.code === "ENOENT") return backendUnavailable("dotnet SDK is not installed or is not on PATH; C# compilation was skipped.");
+  } else if (language === "python") {
+    const venvPython = process.platform === "win32"
+      ? path.join(functionsRoot, ".venv", "Scripts", "python.exe")
+      : path.join(functionsRoot, ".venv", "bin", "python");
+    const candidates = fs.existsSync(venvPython)
+      ? [{ command: venvPython, args: [] as string[] }]
+      : process.platform === "win32"
+        ? [{ command: "python", args: [] }, { command: "python3", args: [] }, { command: "py", args: ["-3"] }]
+        : [{ command: "python3", args: [] }, { command: "python", args: [] }];
+    const python = candidates.find((candidate) => {
+      const probe = spawnSync(candidate.command, [...candidate.args, "-c", "import sys; sys.exit(0 if sys.version_info.major == 3 else 1)"], {
+        cwd: functionsRoot, encoding: "utf-8", timeout: 30_000,
+      });
+      // Preserve execution errors for an installed interpreter instead of silently falling back.
+      return probe.status === 0 || (probe.error && (!("code" in probe.error) || probe.error.code !== "ENOENT"));
+    });
+    if (!python) return backendUnavailable("Python 3 is not available in functions/.venv or on PATH; Python syntax compilation was skipped.");
+    command = python.command;
+    // -f: never trust cached bytecode, which can survive same-size edits within one mtime second.
+    args = [...python.args, "-m", "compileall", "-q", "-f", "-x", "[/\\\\](?:\\.venv|\\.codegen-venv|node_modules|__pycache__)(?:[/\\\\]|$)", "."];
+  } else {
+    let tscPath: string;
+    try {
+      tscPath = require.resolve("typescript/bin/tsc", { paths: [functionsRoot] });
+    } catch (error) {
+      if (error instanceof Error && "code" in error && error.code === "MODULE_NOT_FOUND") {
+        return backendUnavailable("The project's TypeScript compiler is not installed; restore dependencies before verifying functions/.");
+      }
+      throw error;
+    }
+    const sharedBuild = runSharedBuildIfPresent(projectRoot);
+    if (sharedBuild.ran && !sharedBuild.ok) {
+      return {
+        id: "backend-build", title: "Standalone Functions compilation", status: sharedBuild.unavailable ? "error" : "fail",
+        durationMs: 0, fixable: !sharedBuild.unavailable,
+        evidence: { command: sharedBuild.command, logTail: sharedBuild.logTail,
+          ...(sharedBuild.unavailable ? { errorCode: "verification-command-unavailable" as const } : {}) },
+        suggestedActions: ["Fix the shared package build before compiling the TypeScript backend."],
+      };
+    }
+    command = process.execPath;
+    args = [tscPath, "--project", "tsconfig.json", "--noEmit"];
+  }
+  const result = runCommandCheck(functionsRoot, {
+    id: "backend-build", title: "Standalone Functions compilation", command, args, shell: false,
+    timeoutMs: 10 * 60 * 1000,
+    failAction: "Fix the backend compilation errors in evidence.diagnostics / evidence.logTail, then re-run verify.",
+  });
+  result.evidence.command = `${result.evidence.command} (in functions/)`;
+  return result;
+}
+
 function readPackageScripts(projectRoot: string): Record<string, string> {
   const packageJsonPath = path.join(projectRoot, "package.json");
   if (!fs.existsSync(packageJsonPath)) return {};
@@ -430,6 +518,8 @@ export async function runVerify(
       checks.push(await runDriftCheck(projectRoot));
     } else if (id === "typecheck") {
       checks.push(runTypecheckCheck(projectRoot));
+    } else if (id === "backend-build") {
+      checks.push(runBackendBuildCheck(projectRoot));
     } else if (id === "build" || id === "lint" || id === "test") {
       checks.push(runScriptCheck(projectRoot, id));
     } else {

package/src/machine/contracts.ts

@@ -23,6 +23,7 @@ export interface MachineErrorResponse {
   ok: false;
   command: string;
   status?: MachineOperationStatus;
+  nextActions?: MachineNextAction[];
   error: {
     code: string;
     message: string;

package/src/machine/errors.ts

@@ -1,16 +1,18 @@
-import type { MachineOperationStatus } from "./contracts";
+import type { MachineNextAction, MachineOperationStatus } from "./contracts";
 
 export class MachineCommandError extends Error {
   readonly code: string;
   readonly details?: unknown;
   readonly status?: MachineOperationStatus;
+  readonly nextActions?: MachineNextAction[];
 
-  constructor(code: string, message: string, details?: unknown, status?: MachineOperationStatus) {
+  constructor(code: string, message: string, details?: unknown, status?: MachineOperationStatus, nextActions?: MachineNextAction[]) {
     super(message);
     this.name = "MachineCommandError";
     this.code = code;
     this.details = details;
     this.status = status;
+    this.nextActions = nextActions;
   }
 }
 

package/src/machine/index.ts

@@ -58,6 +58,7 @@ function writeMachineError(command: string, error: unknown): void {
     ok: false,
     command,
     status: resolveMachineErrorStatus(error),
+    ...(error instanceof MachineCommandError && error.nextActions?.length ? { nextActions: error.nextActions } : {}),
     error: toMachineError(error),
   };
   writeMachineResponse(response);
@@ -567,10 +568,10 @@ function createMachineProgram(): Command {
   const verify = new Command("verify");
   verify
     .command("project")
-    .description("Run verification checks (structure, drift, typecheck) with machine-readable evidence")
+    .description("Run verification checks (structure, drift, typecheck, backend-build) with machine-readable evidence")
     .option(
       "--checks <ids>",
-      "Comma-separated check ids to run (structure,drift,typecheck,build,lint,test, plus custom ids from swallowkit.config verify.checks)"
+      "Comma-separated check ids to run (structure,drift,typecheck,backend-build,build,lint,test, plus custom ids from swallowkit.config verify.checks); quote CSV values in PowerShell"
     )
     .option("--compact", "Suppress info-severity findings/violations from evidence to keep agent-facing output small", false)
     .action(async (options: { checks?: string; compact?: boolean }) => {

package/src/mcp/index.ts

@@ -5,7 +5,7 @@ import * as path from "path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import * as z from "zod/v4";
-import type { MachineNextAction, MachineOperationStatus, MachineResponse } from "../machine/contracts";
+import type { MachineErrorResponse, MachineNextAction, MachineOperationStatus, MachineResponse } from "../machine/contracts";
 import { getSwallowKitVersion } from "../version";
 import { detectFromProject, getCommands } from "../utils/package-manager";
 import {
@@ -25,7 +25,12 @@ interface MachineSuccessPayload<TData> {
 }
 
 type MachineCliRunner = (args: string[]) => Promise<{ stdout: string; stderr: string; exitCode: number }>;
-type ToolContentResult = { content: Array<{ type: "text"; text: string }> };
+type ToolContentResult = { content: Array<{ type: "text"; text: string }>; isError?: boolean };
+class MachineCliError extends Error {
+  constructor(message: string, readonly response: MachineErrorResponse) {
+    super(message);
+  }
+}
 type ToolDefinition = {
   name: string;
   description: string;
@@ -73,7 +78,7 @@ async function executeMachineCommand<TData>(
     const detailsSuffix =
       parsed.error.details !== undefined ? `\ndetails: ${JSON.stringify(parsed.error.details)}` : "";
     const statusSuffix = parsed.status ? ` (status: ${parsed.status})` : "";
-    throw new Error(`[${parsed.error.code}] ${parsed.error.message}${statusSuffix}${detailsSuffix}`);
+    throw new MachineCliError(`[${parsed.error.code}] ${parsed.error.message}${statusSuffix}${detailsSuffix}`, parsed);
   }
 
   return parsed;
@@ -308,7 +313,7 @@ export function buildSwallowKitToolDefinitions(
     },
     {
       name: "swallowkit_verify_project",
-      description: "Run verification checks (structure, drift, typecheck by default; build, lint, test and custom checks from swallowkit.config verify.checks are also available) and return machine-readable evidence. summary.done=true means the project passed all checks. Set compact=true to suppress info-severity findings and keep the output small.",
+      description: "Run verification checks (structure, drift, typecheck, backend-build by default; build, lint, test and custom checks from swallowkit.config verify.checks are also available) and return machine-readable evidence. backend-build compiles standalone C#/TypeScript Functions or checks Python syntax; unavailable toolchains are skipped with a reason. summary.done=true means no checks failed, not that skipped checks were validated or runtime/auth flows work. Set compact=true to suppress info-severity findings and keep the output small.",
       inputSchema: z.object({
         checks: z.array(z.string()).optional(),
         compact: z.boolean().optional(),
@@ -452,8 +457,16 @@ export function buildSwallowKitToolDefinitions(
   return definitions.map((definition) => ({
     ...definition,
     handler: async (input: unknown) => {
-      const result = await definition.handler(input);
-      return jsonTextContent(withSwallowKitMetadata(JSON.parse(result.content[0].text)));
+      try {
+        const result = await definition.handler(input);
+        return jsonTextContent(withSwallowKitMetadata(JSON.parse(result.content[0].text)));
+      } catch (error) {
+        // Prerequisite failures carry nextActions; keep them structured so agents can follow them.
+        if (error instanceof MachineCliError && error.response.nextActions?.length) {
+          return { ...jsonTextContent(withSwallowKitMetadata(error.response)), isError: true };
+        }
+        throw error;
+      }
     },
   }));
 }