swallowkit 1.1.2 → 2.0.0-alpha.10

package/src/core/operations/scaffold-apply.ts

@@ -19,6 +19,7 @@ export interface ApplyScaffoldOptions {
   functionsDir?: string;
   apiDir?: string;
   apiOnly?: boolean;
+  skipInfra?: boolean;
 }
 
 export interface ApplyScaffoldResult extends MachineScaffoldOperationResult {
@@ -70,6 +71,7 @@ export async function applyScaffoldOperation(options: ApplyScaffoldOptions): Pro
     functionsDir: options.functionsDir ?? basePlan?.options.functionsDir,
     apiDir: options.apiDir ?? basePlan?.options.apiDir,
     apiOnly: options.apiOnly ?? basePlan?.options.apiOnly,
+    skipInfra: options.skipInfra ?? basePlan?.options.skipInfra,
   };
 
   // 常に最新状態で collect し、競合を検出する(plan 指定時も現況を再確認)

package/src/core/operations/scaffold-machine.ts

@@ -13,6 +13,7 @@ export interface MachineScaffoldOperationOptions {
   functionsDir?: string;
   apiDir?: string;
   apiOnly?: boolean;
+  skipInfra?: boolean;
   expectedSchemaAnalysis?: SchemaAnalysisSnapshot;
 }
 

package/src/core/operations/scaffold-plan.ts

@@ -29,6 +29,7 @@ export interface PlanScaffoldOptions {
   functionsDir?: string;
   apiDir?: string;
   apiOnly?: boolean;
+  skipInfra?: boolean;
 }
 
 export type ScaffoldPlanAction = "create" | "update" | "overwrite" | "append" | "delete" | "skip";
@@ -59,6 +60,7 @@ export interface ScaffoldPlanData {
     functionsDir?: string;
     apiDir?: string;
     apiOnly?: boolean;
+    skipInfra?: boolean;
   };
   createdAt: string;
   swallowkitVersion: string;
@@ -93,6 +95,7 @@ async function collectScaffoldOperations(options: PlanScaffoldOptions): Promise<
             functionsDir: options.functionsDir,
             apiDir: options.apiDir,
             apiOnly: options.apiOnly,
+            skipInfra: options.skipInfra,
           });
         });
       });
@@ -193,7 +196,7 @@ export async function planScaffoldOperation(options: PlanScaffoldOptions): Promi
     .update(
       JSON.stringify({
         model: options.model,
-        options: { functionsDir: options.functionsDir, apiDir: options.apiDir, apiOnly: options.apiOnly },
+        options: { functionsDir: options.functionsDir, apiDir: options.apiDir, apiOnly: options.apiOnly, skipInfra: options.skipInfra },
         operations: operations.map((op) => ({ path: op.path, action: op.action })),
         fingerprints,
         schemaAnalysis,
@@ -210,6 +213,7 @@ export async function planScaffoldOperation(options: PlanScaffoldOptions): Promi
       ...(options.functionsDir ? { functionsDir: options.functionsDir } : {}),
       ...(options.apiDir ? { apiDir: options.apiDir } : {}),
       ...(options.apiOnly !== undefined ? { apiOnly: options.apiOnly } : {}),
+      ...(options.skipInfra ? { skipInfra: true } : {}),
     },
     createdAt: new Date().toISOString(),
     swallowkitVersion: getSwallowKitVersion(),

package/src/core/project/agent-instructions.ts

@@ -1,12 +1,13 @@
 import * as fs from "fs";
 import * as path from "path";
-import { BackendLanguage } from "../../types";
+import { BackendLanguage, FrontendFramework } from "../../types";
 import { PackageManager, getCommands } from "../../utils/package-manager";
 
 export interface AgentInstructionContext {
   projectName: string;
   backendLanguage: BackendLanguage;
   packageManager: PackageManager;
+  frontend?: FrontendFramework;
 }
 
 export interface AgentInstructionDocuments {
@@ -70,16 +71,31 @@ function getBackendRules(backendLanguage: BackendLanguage): string {
     "- All backend business logic and data access live in `functions/`.",
     `- SwallowKit derives OpenAPI and native ${BACKEND_LANGUAGE_LABELS[backendLanguage]} schema assets from the Zod source of truth.`,
     "- Keep custom business logic in ai-authored locations identified by the current boundary contract.",
+    backendLanguage === "python"
+      ? "- Use uv with the user's interpreter/version settings. Local Python is not pinned to the Azure deployment runtime. Preserve functions/.venv and functions/.codegen-venv; do not clear them or weaken OS application-control policy to fix interpreter errors."
+      : "- Start the isolated Functions backend with dotnet run, not func start from the source directory, so the SDK loads extensions from the build output.",
   ].join("\n");
 }
 
 function interpolateTemplate(template: string, context: AgentInstructionContext): string {
   const runCmd = getCommands(context.packageManager).exec;
+  const react = context.frontend === "react";
   const replacements: Record<string, string> = {
     projectName: context.projectName,
     backendLanguageLabel: BACKEND_LANGUAGE_LABELS[context.backendLanguage],
     functionsStructureLine: getFunctionsStructureLine(context.backendLanguage),
     backendRules: getBackendRules(context.backendLanguage),
+    frontendLabel: react ? "React + Vite SPA" : "Next.js App Router",
+    bffLabel: react ? "SWA managed Functions" : "Next.js API routes",
+    bffPath: react ? "bff/src" : "app/api",
+    bffGlob: react ? "bff/**" : "app/api/**",
+    helperImport: react ? "../lib/call-function" : "@/lib/api/call-function",
+    frontendStructure: react
+      ? "├── src/                    # React SPA (Vite + React Router)\n│   └── pages/              # generated/custom UI and route registrations\n├── bff/                    # SWA managed HTTP-only Functions\n│   ├── src/                # BFF handlers and request-local helpers\n│   └── {function}/         # function.json registrations"
+      : "├── app/                    # Next.js App Router\n│   ├── api/                # BFF routes\n│   └── {model}/            # generated/custom UI",
+    devGuidance: react
+      ? "Use http://localhost:4280 for the app. `swallowkit dev` runs Vite (3000), the managed BFF (7073), standalone Functions (7071), and SWA CLI (4280). SWA forwards /api only to the managed BFF, never directly to standalone Functions. `--no-functions` leaves the BFF running; `--no-swa` removes same-origin routing/auth emulation. BFF local settings belong in bff/local.settings.json. Build bundles BFF dependencies and copies staticwebapp.config.json into dist/. Deploy dist/ + bff/ together, and functions/ separately. Generated home, CRUD, and login pages share the Next.js presentation templates. Preserve their Tailwind styles and the light/dark defaults in src/style.css when editing them."
+      : "Use http://localhost:3000 for the app, or the SWA emulator port (4280) when testing SWA authentication. `swallowkit dev` runs Next.js and standalone Functions (7071). The BFF remains Next.js API routes.",
     pm: context.packageManager,
     runCmd,
   };

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

@@ -41,7 +41,14 @@ When a SwallowKit capability, project structure, or ownership boundary affects
 a design decision, inspect the current project and the currently available
 SwallowKit interfaces before deciding.
 
-Prefer the `swallowkit_*` MCP tools when available.
+Prefer the `swallowkit_*` MCP tools when available, with one exception: every
+MCP response reports the SwallowKit version that answered in
+`metadata.swallowkitVersion` and `metadata.mcp`. If that version is older than
+the project's installed SwallowKit (`{{runCmd}} swallowkit --version`), or
+`metadata.warnings` contains `mcp-older-than-project`, its capabilities,
+boundaries, and plan/apply contracts may be outdated for this project. Use
+`{{runCmd}} swallowkit machine ...` instead and follow the response's
+`nextActions` (for example `{{runCmd}} swallowkit configure-mcp`).
 
 If MCP is unavailable, use the machine interface:
 
@@ -217,6 +224,10 @@ required.
 
 Never invent or implicitly grant human approval.
 
+Humans normally invoke `swallowkit provision` directly. Its invocation requests
+execution without an additional confirmation. Agents must still use the
+machine/MCP approval flow and must not switch to normal CLI to bypass it.
+
 ## Model Changes
 
 For an existing model change, the normal pattern is:
@@ -263,6 +274,18 @@ SwallowKit should generate framework-owned CRUD artifacts.
 
 Do not manually recreate boilerplate that SwallowKit owns.
 
+When the task must not change Bicep or other infrastructure, still scaffold the
+model: pass `--skip-infra` to `plan scaffold` / `apply scaffold` (MCP
+`skipInfra: true`, or `swallowkit scaffold --skip-infra`). Nothing under
+`infra/` changes, the plan reports `infra-skipped`, and `verify project` still
+passes. Generate only the pending container migration later with
+`{{runCmd}} swallowkit migrations add-model <model>`.
+
+Treat plan `warnings` as decisions to make, not noise. In particular,
+`user-scoped-data-without-auth` means the model looks per-user (for example a
+`/userId` partition key) while authentication is not configured, so generated
+CRUD would let any caller read and write every document.
+
 ## Authentication
 
 Authentication is a **plan/apply operation**, not a free-form config edit.
@@ -300,6 +323,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
@@ -311,8 +348,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:
 
@@ -359,6 +405,24 @@ Use the `swallowkit-provision` Agent Skill or runbook and never bypass its
 approval gate. A broad request to deploy does not itself grant the explicit
 approval required by that workflow.
 
+Provision applies Bicep once and tracks the original Azure deployment with a
+bounded wait. A local timeout/error, output truncation, or Ctrl+C is not proof
+that Azure failed. `in-progress` means Azure is Running/Accepted; `unknown`
+means its result could not be read; `partial` means Azure succeeded but
+tag/ledger completion is pending. Never re-submit Bicep, reconcile, adopt,
+cancel, or delete just to repair waiting or migration bookkeeping.
+
+Retain `.swallowkit/state/provision/` execution checkpoints. Use
+`{{runCmd}} swallowkit machine inspect provision --plan <runId> --wait-seconds 300`
+for read-only status/wait, and after explicit human approval use
+`{{runCmd}} swallowkit machine apply provision --plan <runId> --approve`
+to resume. `runId` equals the original `planId`; fingerprints, subscription,
+deployment identity and migration checks remain in force. Only
+`status: "complete"` / `outcome: "succeeded"` means Azure Succeeded plus verified
+tags and local ledger. Do not print deployment output secrets or raw `az --debug`.
+For older untracked baselines use `plan provision --resume-deployment <name>`
+with original target/regions; it blocks unless ARM/parameter evidence matches.
+
 ## SwallowKit Agent Skills and Runbooks
 
 SwallowKit installs task-specific Agent Skills under:
@@ -393,9 +457,9 @@ This is a full-stack application deployed on Azure with a TypeScript
 frontend/BFF and an Azure Functions backend in {{backendLanguageLabel}}.
 
 ```text
-Frontend (React / Next.js App Router)
+Frontend ({{frontendLabel}})
   ↓
-BFF (Next.js API Routes)
+BFF ({{bffLabel}})
   ↓
 Azure Functions
   ↓
@@ -404,7 +468,7 @@ Azure Cosmos DB
 
 ### Core architecture rules
 
-1. Next.js API routes are a BFF/proxy layer. Do not place application business
+1. {{bffLabel}} are a BFF/proxy layer. Do not place application business
    logic or direct database access there.
 2. Zod schemas under `shared/models/` are the application model source of truth.
 3. Do not duplicate model definitions across layers.
@@ -415,6 +479,11 @@ Azure Cosmos DB
    markers and boundaries.
 7. Production access to Azure resources must follow the generated security
    architecture; do not introduce hard-coded credentials or connection strings.
+8. Never link standalone Functions to SWA. The same-origin BFF calls the
+   independent backend with server-side BACKEND_FUNCTIONS_BASE_URL and
+   BACKEND_FUNCTIONS_KEY. Never expose these values in browser bundles or VITE_*.
+   Managed Functions use HTTP triggers only; database access, non-HTTP triggers,
+   managed identity, and private networking belong to the standalone backend.
 
 ### Backend-specific rules
 
@@ -427,16 +496,13 @@ values for these fields.
 
 ```text
 {{projectName}}/
-├── app/                    # Next.js App Router
-│   ├── api/                # BFF routes
-│   └── {model}/            # generated/custom UI
+{{frontendStructure}}
 ├── functions/              # Azure Functions backend
 {{functionsStructureLine}}
 ├── shared/
 │   ├── models/             # Zod source-of-truth models
 │   └── index.ts
-├── lib/
-│   └── api/
+├── lib/                    # auth, navigation, and shared application utilities
 ├── components/
 ├── infra/                  # Bicep infrastructure
 ├── .swallowkit/            # SwallowKit project metadata and runbooks
@@ -453,12 +519,24 @@ 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`, and
-  `connectorConfig` as exported constants. Exact formats:
+- Models may declare `partitionKey`, `authPolicy`, `displayName`,
+  `references`, and `connectorConfig` as exported constants. Exact formats:
   `{{runCmd}} swallowkit machine inspect capabilities` (modelDeclarations).
+- A string field named `<model>Id` is treated as a foreign key only when that
+  model exists in `shared/models`. Declare other references explicitly with
+  `export const references = { authorId: 'User' };` (map a field to `false`
+  to opt out).
+- Native C#/Python schema types come from Zod, not field names: use
+  `z.iso.datetime()` / `z.iso.date()` for date values (`createdAt` stays a
+  string), `z.number().int()` for integers, and inline `z.object` for nested
+  classes. Length/range/regex/item constraints are enforced natively; formats
+  such as email remain Zod (BFF) validation. See `inspect capabilities`
+  (sharedModels.nativeSchemaMapping).
 - Cosmos DB containers use PascalCase plural names and default to `/id` as the
   partition key unless the model declares another key, e.g.
   `export const partitionKey = '/learnerId';` (the field must exist in the
@@ -470,13 +548,26 @@ same generated structure.
 {{pm}} install
 {{runCmd}} swallowkit dev
 {{pm}} run build
-{{pm}} run lint
+{{pm}} run --if-present lint
 {{runCmd}} swallowkit machine verify project
 ```
 
 Always invoke SwallowKit using the package-runner convention generated for this
 project. Do not arbitrarily mix package-manager invocation styles.
 
+{{devGuidance}}
+
+Check for an already-running Cosmos DB Emulator before database tests. If it is
+unavailable, report that prerequisite; do not start/restart it or change global
+tools, TLS trust, or machine settings without explicit permission. Test against
+an isolated database and ports, never reset user data, and stop only processes
+you started. `dev --seed-env` replaces data, so inspect its target first.
+
+Build and run `verify project`, then exercise UI, CRUD, error/validation paths,
+and configured authentication through the same-origin BFF. A passing typecheck
+or server readiness probe alone is not an end-to-end verification. Report
+unverified cloud deployment or unavailable local prerequisites explicitly.
+
 ## Final Rules
 
 Do not:
@@ -502,3 +593,10 @@ Do:
 - verify before final semantic review
 
 Use `{{pm}}`, the package manager selected for this project. Do not introduce another package manager or lockfile. Use `{{runCmd}} swallowkit` for the project-local CLI. The MCP launcher intentionally resolves `latest` independently.
+Exception for prerelease projects: when the project's SwallowKit is newer than
+the published `latest` (for example `2.0.0-alpha.3` while `latest` is `1.1.2`),
+`.mcp.json` may pin `SWALLOWKIT_MCP_VERSION` to the project version, and a
+`latest` launcher that supports it hands the session to the project-installed
+MCP. Run `{{runCmd}} swallowkit configure-mcp` to re-select the version (it
+returns to `latest` once `latest` is at least the project version). Until MCP
+reports the project version, prefer `{{runCmd}} swallowkit machine ...`.

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

@@ -14,7 +14,9 @@ Always-on rules:
 - Inspect the current project and SwallowKit capabilities before making
   SwallowKit-dependent assumptions or asking questions the repository can answer.
 - Prefer `swallowkit_*` MCP tools.
-- Fall back to `{{runCmd}} swallowkit machine ...` when MCP is unavailable.
+- Fall back to `{{runCmd}} swallowkit machine ...` when MCP is unavailable, or
+  when an MCP response's `metadata.swallowkitVersion` is older than the project's
+  SwallowKit (`metadata.warnings` contains `mcp-older-than-project`).
 - Inspect responsibility boundaries before editing framework-related files.
 - Never hand-edit deterministic SwallowKit-managed artifacts.
 - Add auth schemes only via plan/apply auth; never hand-write `auth.schemes`
@@ -22,7 +24,18 @@ Always-on rules:
   after apply).
 - Use plan/apply for deterministic generation.
 - Respect all `requires-human` states and provisioning approval gates.
+- Normal `swallowkit provision` is for humans. Agents must not use it to bypass
+  the machine/MCP approval flow.
+- Provision timeouts/Ctrl+C do not prove Azure failed. Inspect the original
+  execution checkpoint with `machine inspect provision --plan <runId>`; resume
+  `machine apply provision --plan <runId> --approve` only after explicit human
+  approval. Preserve checkpoints; never re-submit Bicep/reconcile/cancel/delete
+  to repair waiting or tag/ledger failures. Do not print deployment output secrets.
 - 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/bff-routes.instructions.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "app/api/**"
+applyTo: "{{bffGlob}}"
 ---
 
 # BFF API Routes — Rules
@@ -7,10 +7,12 @@ applyTo: "app/api/**"
 The root `AGENTS.md` is the canonical contract. Inspect the current
 responsibility boundary before editing files in this layer.
 
-- `app/api/` is a BFF/proxy layer. Never place business logic, database access,
+- `{{bffPath}}/` is a BFF/proxy layer. Never place business logic, database access,
   or direct Cosmos DB calls here.
-- Use `callFunction()` from `@/lib/api/call-function` to forward requests to
+- Use `callFunction()` from `{{helperImport}}` to forward requests to
   Azure Functions.
+- Keep credentials request-local. Never put the backend URL/key in client
+  code or VITE_* variables. Do not link standalone Functions to SWA.
 - Input/output validation may use schemas imported from `@{{projectName}}/shared`.
 - Never directly edit a route reported as deterministic. Change its source of
   truth and use MCP-first plan/apply, with the machine interface as fallback.

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

@@ -13,7 +13,9 @@ Key rules:
 - Inspect current SwallowKit capabilities instead of assuming them.
 - Answer repository- and SwallowKit-inspectable questions before asking the human.
 - Prefer `swallowkit_*` MCP tools when available.
-- Otherwise use `{{runCmd}} swallowkit machine ...`.
+- Otherwise use `{{runCmd}} swallowkit machine ...`. Also use it when an MCP
+  response's `metadata.swallowkitVersion` is older than the project's SwallowKit
+  or `metadata.warnings` contains `mcp-older-than-project`.
 - Inspect responsibility boundaries before editing framework-related files.
 - Never hand-edit deterministic SwallowKit-managed artifacts.
 - Add auth schemes only via plan/apply auth; never hand-write `auth.schemes`
@@ -21,7 +23,19 @@ Key rules:
   after apply).
 - Use plan/apply for deterministic generation.
 - Respect `requires-human` states and other human approval gates.
+- Normal `swallowkit provision` is a human-facing deployment command. Agents must
+  use the machine/MCP approval flow, not normal CLI as an approval bypass.
+- Provision timeouts/Ctrl+C do not prove Azure failed. Read `status`, `outcome`,
+  and `nextActions`; inspect the original run with `machine inspect provision
+  --plan <runId>`, then resume `machine apply provision --plan <runId> --approve`
+  only after explicit human approval. Preserve execution checkpoints; never
+  re-submit Bicep or use reconcile/cancel/delete to repair waiting or tag/ledger
+  failures. Do not print deployment output secrets.
 - 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

@@ -10,7 +10,9 @@
  * - shared:        マーカー区切りの共有領域。マーカー内は SwallowKit、外は自由。
  */
 
+import { getBackendLanguage } from "../config";
 import { ArtifactOwnership } from "../operations/file-session";
+import { BackendLanguage } from "../../types";
 import { inspectArtifacts } from "./artifacts";
 
 export type BoundaryZone = "deterministic" | "ai-authored" | "shared";
@@ -48,6 +50,8 @@ export interface BoundaryArtifact {
 export interface BoundariesContract {
   contractVersion: number;
   summary: string;
+  /** backend.language the convention rules were resolved for */
+  backendLanguage: BackendLanguage;
   ownershipPolicies: OwnershipPolicy[];
   /** 台帳に載っていないパスの既定規約 */
   conventionRules: BoundaryPathRule[];
@@ -82,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",
@@ -92,7 +96,7 @@ export const OWNERSHIP_POLICIES: OwnershipPolicy[] = [
   },
 ];
 
-export const CONVENTION_RULES: BoundaryPathRule[] = [
+const COMMON_LEADING_RULES: BoundaryPathRule[] = [
   {
     pattern: ".swallowkit/",
     zone: "deterministic",
@@ -107,32 +111,66 @@ export const CONVENTION_RULES: BoundaryPathRule[] = [
       "Zod model schemas — the single source of truth. AI/developers author these freely; deterministic generation derives everything else from them.",
   },
   {
-    pattern: "infra/main.bicep",
-    zone: "shared",
-    editPolicy: "edit-outside-markers",
-    description: "SwallowKit inserts container modules; other infrastructure edits are free.",
+    pattern: "infra/migrations/manifest.json",
+    zone: "deterministic",
+    editPolicy: "never-hand-edit",
+    description:
+      "Infrastructure migration ledger with baseline checksums. Updated by scaffold, `swallowkit migrations add-model`, and `swallowkit create-migration`.",
   },
   {
-    pattern: "functions/function_app.py",
-    zone: "shared",
-    editPolicy: "edit-outside-markers",
-    description: "SwallowKit appends blueprint registrations under its marker; other edits are free.",
+    pattern: "infra/migrations/",
+    zone: "ai-authored",
+    editPolicy: "free-edit",
+    description:
+      "Versioned Bicep migrations. Edit a migration only before it is provisioned; never change an applied migration — add a new one with `swallowkit create-migration <slug>`.",
   },
   {
-    pattern: "shared/index.ts",
-    zone: "shared",
-    editPolicy: "edit-outside-markers",
-    description: "SwallowKit appends model exports; other exports may be added freely.",
+    pattern: "infra/",
+    zone: "deterministic",
+    editPolicy: "never-hand-edit",
+    description:
+      "Baseline infrastructure (main.bicep and modules) whose checksums are recorded in infra/migrations/manifest.json. Hand edits block scaffold with baseline-drift; add resources through a new migration instead.",
   },
   {
-    pattern: "*",
-    zone: "ai-authored",
+    pattern: "shared/index.ts",
+    zone: "shared",
     editPolicy: "free-edit",
-    description:
-      "Any path not recorded in the artifact ledger is AI/developer-authored. Business logic, custom pages, custom Functions, and tests belong here.",
+    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.",
   },
 ];
 
+/** Backend files that SwallowKit appends to; C# and TypeScript discover functions without a registration file. */
+const BACKEND_EXTENSION_RULES: Record<BackendLanguage, BoundaryPathRule[]> = {
+  python: [
+    {
+      pattern: "functions/function_app.py",
+      zone: "shared",
+      editPolicy: "edit-outside-markers",
+      description: "SwallowKit appends blueprint registrations under its marker; other edits are free.",
+    },
+    {
+      pattern: "functions/requirements.txt",
+      zone: "shared",
+      editPolicy: "free-edit",
+      description: "SwallowKit appends connector driver requirements when connector models are scaffolded; keep those lines and edit other requirements freely.",
+    },
+  ],
+  csharp: [],
+  typescript: [],
+};
+
+const FALLBACK_RULE: BoundaryPathRule = {
+  pattern: "*",
+  zone: "ai-authored",
+  editPolicy: "free-edit",
+  description:
+    "Any path not recorded in the artifact ledger is AI/developer-authored. Business logic, custom pages, custom Functions, and tests belong here.",
+};
+
+export function buildConventionRules(backendLanguage: BackendLanguage): BoundaryPathRule[] {
+  return [...COMMON_LEADING_RULES, ...BACKEND_EXTENSION_RULES[backendLanguage], FALLBACK_RULE];
+}
+
 const POLICY_BY_OWNERSHIP = new Map(OWNERSHIP_POLICIES.map((policy) => [policy.ownership, policy] as const));
 
 export const BOUNDARY_GUIDANCE: string[] = [
@@ -143,7 +181,10 @@ export const BOUNDARY_GUIDANCE: string[] = [
   "Run `swallowkit machine verify project` after applying changes; use `explain failure` to get repair evidence.",
 ];
 
-export function inspectBoundaries(projectRoot: string = process.cwd()): BoundariesContract {
+export function inspectBoundaries(
+  projectRoot: string = process.cwd(),
+  backendLanguage: BackendLanguage = getBackendLanguage()
+): BoundariesContract {
   const inspected = inspectArtifacts(projectRoot);
 
   const artifacts: BoundaryArtifact[] = inspected.artifacts.map((artifact) => {
@@ -162,8 +203,9 @@ export function inspectBoundaries(projectRoot: string = process.cwd()): Boundari
     contractVersion: 1,
     summary:
       "SwallowKit separates deterministic generation (models → CRUD/BFF/UI/infra via plan/apply) from AI free-form authoring (models, business logic, custom code). This contract tells agents which files belong to which side.",
+    backendLanguage,
     ownershipPolicies: OWNERSHIP_POLICIES,
-    conventionRules: CONVENTION_RULES,
+    conventionRules: buildConventionRules(backendLanguage),
     artifacts,
     guidance: BOUNDARY_GUIDANCE,
   };