create-flowdular 0.2.4 → 0.2.6

package/agent-template/.ai/examples/client-contribution/CustomerListView.tsrx

@@ -0,0 +1,34 @@
+/* Minimal view and widget so the contribution example resolves. A real screen
+   follows .ai/references/catalog/src/client/CatalogView.tsrx and the record-screen
+   recipe in .ai/skills/ux-design/SKILL.md. */
+import { EmptyState, Kpi, PageHeader } from '@flowdular/sdk/ui';
+
+export interface CustomerListViewProps {
+	readonly csrfToken: string;
+}
+
+export function CustomerListView(props: CustomerListViewProps) @{
+	void props.csrfToken;
+	<div class="ui-view">
+		<PageHeader
+			eyebrow="Master data"
+			title="Customers"
+			description="Customer records of the active tenant."
+		/>
+		<section class="ui-card">
+			<EmptyState icon="parties" title="No customers yet">
+				Create the first customer.
+			</EmptyState>
+		</section>
+	</div>
+}
+
+export function CustomerDashboardWidget() @{
+	<Kpi
+		label="Customers"
+		value="0"
+		note="Customer records in this organization."
+		href="/customers"
+		linkLabel="Open customers"
+	/>
+}

package/agent-template/.ai/examples/client-contribution/README.md

@@ -0,0 +1,11 @@
+# Client contribution example
+
+Mirror of `.ai/references/catalog/src/client/{contribution.tsrx,index.ts}`, flattened into one directory. In a module the files live at `src/client/contribution.tsrx`, `src/client/index.ts`, `src/client/CustomerListView.tsrx`, and the permissions at `src/acl/permissions.ts`.
+
+What it shows:
+
+- `createClientContribution(context: ModuleClientContext)` in `index.ts` is the entry the generated composition imports (`packages/cli/src/module-sync.ts`); it threads `context.csrfToken` into the factory, which passes it to every view that mutates.
+- `glyph: 'parties'` is a key of `ICON_PATHS` (`packages/ui/src/icons/Icon.tsrx`); an unknown key renders the `modules` icon silently.
+- Ids: `customers.navigation`, view `customers` (the URL slug), widget `customers.dashboard.summary`; `slot` is one of `WORKSPACE_SLOTS`; `scope` is the module's read permission.
+
+These files are not part of any `tsconfig.json` and are not compiled; `.ai/references/catalog` is the compiled reference.

package/agent-template/.ai/examples/client-contribution/contribution.tsrx

@@ -0,0 +1,48 @@
+/* Mirror of .ai/references/catalog/src/client/contribution.tsrx. In a module this file
+   is src/client/contribution.tsrx, the permissions come from
+   src/acl/permissions.ts, and the views from sibling .tsrx files. */
+import type { ModuleClientContribution } from '@flowdular/sdk/client';
+import { CUSTOMER_PERMISSIONS } from './permissions.ts';
+import {
+	CustomerDashboardWidget,
+	CustomerListView,
+} from './CustomerListView.tsrx';
+
+export interface CustomerClientContributionOptions {
+	readonly csrfToken: string;
+}
+
+export function createCustomerClientContribution(
+	options: CustomerClientContributionOptions,
+): ModuleClientContribution {
+	return {
+		moduleId: 'customers.core',
+		navigation: [
+			{
+				id: 'customers.navigation',
+				viewId: 'customers',
+				group: 'Operations',
+				label: 'Customers',
+				glyph: 'parties',
+				description: 'Customer master data',
+				scope: CUSTOMER_PERMISSIONS.read,
+				order: 30,
+			},
+		],
+		views: [
+			{
+				id: 'customers',
+				render: () => <CustomerListView csrfToken={options.csrfToken} />,
+			},
+		],
+		widgets: [
+			{
+				id: 'customers.dashboard.summary',
+				slot: 'dashboard.metrics',
+				scope: CUSTOMER_PERMISSIONS.read,
+				order: 30,
+				render: () => <CustomerDashboardWidget />,
+			},
+		],
+	};
+}

package/agent-template/.ai/examples/client-contribution/index.ts

@@ -0,0 +1,20 @@
+/* Mirror of .ai/references/catalog/src/client/index.ts: the canonical entry the
+   generated composition imports as createClientContribution from
+   <package>/client. */
+export { createCustomerClientContribution } from './contribution.tsrx';
+export type { CustomerClientContributionOptions } from './contribution.tsrx';
+export {
+	CustomerDashboardWidget,
+	CustomerListView,
+} from './CustomerListView.tsrx';
+import type {
+	ModuleClientContext,
+	ModuleClientContribution,
+} from '@flowdular/sdk/client';
+import { createCustomerClientContribution as canonicalContribution } from './contribution.tsrx';
+
+export function createClientContribution(
+	context: ModuleClientContext,
+): ModuleClientContribution {
+	return canonicalContribution({ csrfToken: context.csrfToken });
+}

package/agent-template/.ai/examples/client-contribution/permissions.ts

@@ -0,0 +1,8 @@
+/* In a module this is src/acl/permissions.ts. The strings equal
+   spec/module.yaml permissions[].id. */
+export const CUSTOMER_PERMISSIONS = {
+	read: 'customers.records.read',
+	manage: 'customers.records.manage',
+} as const;
+
+export const permissions = Object.freeze(Object.values(CUSTOMER_PERMISSIONS));

package/agent-template/.ai/examples/customer-cli-extension/README.md

@@ -0,0 +1,14 @@
+# Module CLI extension example
+
+`commands.json` is the catalog (`module.json` `cli.catalog`, validated against `packages/contracts/schemas/cli-extension.schema.json` without running code) and `index.ts` is the implementation (`cli.entry`, imported only when the command runs). The module manifest declares both:
+
+```json
+{
+	"capabilities": ["api", "cli"],
+	"cli": { "catalog": "src/cli/commands.json", "entry": "src/cli/index.ts" }
+}
+```
+
+Rules from `packages/cli/src/extensions.ts`: the command path starts with the module namespace (`customer` for `customer.core`), the capability id starts with `customer.`, the module must be enabled in `flowdular.json`, and `path` plus the whole `capability` object must be identical in both files. `requiresApprovedSpec: true` means `pnpm flowdular customer export --spec modules/customer/spec/module.yaml` (and `--apply` to write). Full procedure: `.ai/skills/cli-extension/SKILL.md`. Real modules: `modules/auth/src/cli`, `modules/agents/src/cli`, `modules/sandbox/src/cli`.
+
+Not compiled or tested here; `packages/cli/tests/extensions.test.ts` covers the catalog rules.

package/agent-template/.ai/examples/customer-cli-extension/commands.json

@@ -0,0 +1,17 @@
+{
+	"protocolVersion": 1,
+	"moduleId": "customer.core",
+	"commands": [
+		{
+			"path": ["customer", "export"],
+			"capability": {
+				"id": "customer.export",
+				"version": 1,
+				"summary": "Export tenant-scoped customer records to an approved workspace path.",
+				"risk": "workspace-write",
+				"requiresApprovedSpec": true,
+				"supportsDryRun": true
+			}
+		}
+	]
+}

package/agent-template/.ai/examples/customer-cli-extension/index.ts

@@ -0,0 +1,36 @@
+/* In a module this is src/cli/index.ts. Every field of `capability` and the
+   `path` must equal the entry in commands.json; packages/cli/src/extensions.ts
+   (loadCliCommand) refuses the command otherwise. */
+import { defineCliExtension } from '@flowdular/sdk/cli-protocol';
+
+export const cliExtension = defineCliExtension({
+	protocolVersion: 1,
+	moduleId: 'customer.core',
+	commands: [
+		{
+			path: ['customer', 'export'],
+			capability: {
+				id: 'customer.export',
+				version: 1,
+				summary:
+					'Export tenant-scoped customer records to an approved workspace path.',
+				risk: 'workspace-write' as const,
+				requiresApprovedSpec: true,
+				supportsDryRun: true,
+			},
+			execute: ({ apply, arguments: arguments_, workspaceRoot }) => ({
+				data: {
+					applied: apply,
+					format: arguments_[0] ?? 'json',
+					target: `${workspaceRoot}/.flowdular/data/exports/customers.${arguments_[0] ?? 'json'}`,
+				},
+				evidence: ['modules/customer/spec/module.yaml'],
+				warnings: apply
+					? []
+					: ['Dry run only. Pass --apply after reviewing the target.'],
+			}),
+		},
+	],
+});
+
+export default cliExtension;

package/agent-template/.ai/examples/module-create/task-packet.json

@@ -0,0 +1,11 @@
+{
+	"schemaVersion": 1,
+	"taskId": "example-sales-orders",
+	"capability": "module.create",
+	"blueprint": "new-module@1.0.0",
+	"spec": "modules/sales-orders/spec/module.yaml",
+	"specStatus": "approved",
+	"allowedPaths": ["modules/sales-orders/**"],
+	"steps": ["dry-run", "apply", "implement acceptance scenarios", "run gates"],
+	"gates": ["module-schema", "spec-schema", "typecheck", "tests", "format"]
+}

package/agent-template/.ai/guides/application-development.md

@@ -0,0 +1,97 @@
+# Developing a generated application
+
+Use this map when working in an application created by `create-flowdular`.
+Choose one task skill from `.ai/skills/README.md` for the current phase. Read the
+owning code and the relevant section below; do not preload every skill.
+
+## Establish the actual project layout
+
+1. Read root `package.json`, `flowdular.json` and the target module's
+   `package.json`, `module.json` and `spec/module.yaml`.
+2. Identify existing behavior, requested changes, permissions and affected
+   locales. A new module needs an explicitly approved specification before
+   implementation. Ask for missing business decisions before inventing fields,
+   roles, calculations or workflow transitions.
+3. Work in `modules/<directory>`. The starter is `modules/example`, with package
+   name `@app/module-example`; other modules may use another naming convention.
+   Never derive a pnpm package selector from an SDK import or module id.
+4. `platform/src/App.tsrx`, `platform/src/generated/**`, generated composition and
+   enabled-module dependencies are CLI-owned. Use `pnpm flowdular module sync
+--apply` to regenerate composition after a declared contract change.
+5. Core modules and platform packages are installed under
+   `platform/node_modules/@flowdular/sdk`. Upstream paths in shared skills such
+   as `modules/auth` and `packages/server` refer to that read-only tree. Public
+   exports are listed in its `package.json`. Import them through
+   `@flowdular/sdk/server`, `@flowdular/sdk/client`, `@flowdular/sdk/ui`,
+   `@flowdular/sdk/database` and the relevant exported subpath. Never patch
+   installed source to deliver a feature. CLI and sandbox internals require an
+   upstream Flowdular change, not a new application-local copy.
+
+## Choose the smallest complete change
+
+Paths below are relative to the module directory. Keep the approved spec and
+manifest aligned. An implementation must include observable regression evidence.
+
+| Requested change                   | Task skill              | Owning files and completion evidence                                                                                                                            |
+| ---------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| New module                         | `module-new`            | Approved `spec/module.yaml`; run scaffold preview then apply; implement the remaining business behavior; validate, enable and grant explicitly                  |
+| New entity field or endpoint       | `module-update`         | `src/domain`, `src/services`, `src/api/endpoints.ts`, client consumers and spec; reject invalid inputs and preserve existing behavior                           |
+| New permission or protected action | `auth-security-review`  | `src/acl/permissions.ts`, endpoint identity/permission, spec and UI availability; prove unauthenticated, denied and cross-tenant cases                          |
+| Database table or column           | `migration-authoring`   | New immutable `migrations/*.sql`, matching `databaseMigrations`, repository mapping and spec; test fresh migration and tenant isolation                         |
+| Persistence query                  | `database-adapter`      | `src/services/database-repository.ts` and repository port; bound SQL and transactions using the authenticated tenant; exercise the real test provider           |
+| Screen, table or edit form         | `ux-design`             | `src/client/*View.tsrx`, `state.ts`, `api.ts`, `contribution.tsrx`; use shared UI, inspect loading/empty/error/populated/denied states and keyboard interaction |
+| Navigation or translated copy      | `translations-i18n`     | `src/client/contribution.tsrx`, all configured `translations/*.json` and consumers; validate matching keys and plural forms                                     |
+| Workflow or automation             | `workflow-development`  | Module-owned workflow definition and invocation through public capabilities; test publication, execution, failures and permission boundaries                    |
+| Agent tool                         | `agent-tool-design`     | Tool registration, input/output contract, permission ceiling, idempotency and audit; test actual harness invocation and denial                                  |
+| Business agent                     | `business-agent-design` | Agent declaration, public tools and tenant-bound provider; test allowed and forbidden behavior, revisions and cleanup                                           |
+| Module CLI command                 | `cli-extension`         | `src/cli/commands.json`, handler, module export and manifest; test dry run, authorization and applied effects                                                   |
+| Defect or failed check             | `bug-hunt`              | First reproduce at the owning layer, then fix and rerun the failing test; inspect sibling paths                                                                 |
+| Final delivery                     | `auto-review`           | Review the whole diff against requirements and executable evidence; report unresolved findings and actual check results                                         |
+
+For a multi-part feature, finish each bounded implementation phase, then select
+the next skill. In sandbox sessions, follow the assigned role's write paths and
+handoff list. A backend role must hand a client fix to the frontend role; a failed
+gate does not expand its authority. Direct coding agents still keep module
+boundaries and preserve other contributors' changes.
+
+## Verification in this application
+
+For the example module, run:
+
+```sh
+pnpm --filter @app/module-example typecheck
+pnpm --filter @app/module-example test
+pnpm flowdular module validate
+pnpm verify
+pnpm build
+```
+
+For another module substitute its actual package name. A green command with no
+tests is not evidence. Test public behavior, input bounds, permission denial and
+tenant isolation. Database tests use isolated embedded PostgreSQL or the
+configured test provider, never the application's local demo or hosted database.
+Do not claim a hosted PostgreSQL check ran when only embedded tests ran.
+
+`pnpm build` uses isolated temporary state and ephemeral build keys. `pnpm
+flowdular setup` configures the application. Local demo reset requires stopping
+the application and must never target a deployed database.
+
+Inspect rendered UI after changing a screen. Run the `auto-review` skill as a
+separate phase after implementation. Report changed behavior, checks actually
+run, remaining failures and any required operator action. Commit/push or open a
+PR only within the user's authorization; agent changes do not grant themselves
+spec approval or production access.
+
+## Maintain the agent guidance
+
+Edit `.ai/rules` and `.ai/skills`, then run `pnpm rules:generate` and
+`pnpm rules:check`. Codex reads `AGENTS.md` and `.agents/skills`; Claude Code reads
+`CLAUDE.md` and `.claude/skills`. Keep generated copies synchronized. `.ai/agents`
+contains reusable role instructions; `.ai/blueprints` and `.ai/policies` are
+project-local inputs referenced by `flowdular.json`.
+
+Split a skill when it contains independent procedures with different owning
+files, write scopes or verification commands. Keep shared requirements in the
+rules and concrete recipes in the task skill. Each recipe should state its
+trigger, inputs, touch list, ordered steps, failure cases and completion checks.
+Do not add a skill that only renames an existing procedure.

package/agent-template/.ai/policies/capabilities.yaml

@@ -0,0 +1,164 @@
+schemaVersion: 1
+# What the CLI actually exposes and how the runner gates it. Consumed by nobody:
+# packages/cli/src/doctor.ts only checks that this file exists
+# (policy.capabilities). The real policy is code: core descriptors in
+# packages/cli/src/capabilities.ts, module descriptors in each
+# modules/*/src/cli/commands.json, approval logic in packages/cli/src/runner.ts
+# (runExtensionCommand). Keep this file in step with those three places.
+default: deny
+
+# packages/cli/src/capabilities.ts
+core:
+  module.search:
+    command: pnpm flowdular module search [query]
+    risk: read
+    note: host-only official HTTPS catalog lookup; does not grant sandbox network access
+  module.info:
+    command: pnpm flowdular module info <id>
+    risk: read
+  module.install:
+    command: pnpm flowdular module install <id[@version]> [--apply]
+    risk: workspace-write
+    supportsDryRun: true
+    note: host-only source installation; no scripts, activation, permissions or database changes
+  module.update:
+    command: pnpm flowdular module update <id[@version]> [--apply]
+    risk: workspace-write
+    supportsDryRun: true
+    note: rejects local edits, changed historical migrations and downgrades
+  module.recover:
+    command: pnpm flowdular module recover [--apply]
+    risk: workspace-write
+    supportsDryRun: true
+    note: requires the original installation process to have exited
+  workspace.doctor:
+    command: pnpm flowdular doctor
+    risk: read
+  spec.validate:
+    command: pnpm flowdular spec validate --all
+    risk: read
+  blueprint.validate:
+    command: pnpm flowdular blueprint validate --all
+    risk: read
+    note: validates every .ai/blueprints/*/blueprint.json and checks the companion files exist
+  module.validate:
+    command: pnpm flowdular module validate
+    risk: read
+    note: 'schema plus composition entries (PLATFORM_SERVER_ENTRY_MISSING, PLATFORM_EXPORT_MISSING, PLATFORM_CLIENT_ENTRY_MISSING, PLATFORM_CLIENT_EXPORT_MISSING), PACKAGE_NAME_MISMATCH, SPEC_ID_MISMATCH, TRANSLATION_FILE_MISSING, TRANSLATION_KEYS_MISMATCH; warnings SPEC_VERSION_DRIFT, LOCALE_NOT_IN_PROJECT (packages/cli/src/module-validate.ts)'
+  module.create:
+    command: pnpm flowdular module new <id> --spec <path> [--apply]
+    risk: workspace-write
+    requiresApprovedSpec: true
+    supportsDryRun: true
+  migration.status:
+    command: pnpm flowdular migration status [--module <id>] [--json]
+    risk: read
+    note: 'per module database, each migration is applied, adopted (its objects already exist, so the runner will only record it), pending, or mismatch; fails with MIGRATION_CHECKSUM_MISMATCH when an applied migration was edited (packages/cli/src/migration.ts)'
+  migration.verify:
+    command: pnpm flowdular migration verify
+    risk: read
+    note: 'checks every ledger row against the checksum of the migration in the workspace; failure code MIGRATION_LEDGER_INVALID with mismatched and unknown ids per module'
+  migration.apply.local:
+    command: pnpm flowdular migration apply --module <id> [--apply]
+    risk: process
+    localOnly: true
+    supportsDryRun: true
+    effect: applies or adopts the outstanding migrations of one module against the configured PostgreSQL (embedded PGlite outside production) and writes the _coreloom_migrations_v2 ledger; without --apply it reports the plan and writes nothing
+  workspace.state.migrate:
+    command: pnpm flowdular setup migrate-state [--apply --confirm migrate-legacy-state]
+    risk: destructive
+    localOnly: true
+    confirmation: migrate-legacy-state
+    supportsDryRun: true
+    effect: copies recognized pre-Flowdular databases and vault keys into .flowdular/data, verifies their hashes, and preserves every source file; refuses links, collisions, and database sidecar files
+
+# Commands dispatched by packages/cli/src/runner.ts without a capability descriptor.
+commandsWithoutDescriptor:
+  - pnpm flowdular help
+  - pnpm flowdular capability list|describe <id>|run <id>
+  - pnpm flowdular blueprint list
+  - pnpm flowdular module list
+  - pnpm flowdular module sync [--apply]
+  - pnpm flowdular module enable <id> [--apply] (with --apply also runs auth.scopes.sync; result field scopes, failure code MODULE_SCOPES_SYNC_FAILED)
+  - pnpm flowdular module disable <id> [--apply]
+  - pnpm flowdular setup check
+  - pnpm flowdular setup quick (alias of auth.greenfield.reset)
+
+# modules/*/src/cli/commands.json, loaded only for modules enabled in flowdular.json
+modules:
+  auth.core:
+    auth.scopes.list:
+      command: pnpm flowdular auth scopes
+      risk: read
+    auth.scopes.sync:
+      command: pnpm flowdular auth sync-scopes --module <id> [--apply]
+      risk: process
+      supportsDryRun: true
+      effect: grants the module spec permissions to every tenant owner in the auth database
+    auth.greenfield.reset:
+      command: pnpm flowdular auth greenfield --apply --confirm reset-local-auth
+      risk: destructive
+      localOnly: true
+      confirmation: reset-local-auth
+      supportsDryRun: true
+      effect: resets .flowdular/data/auth.db and seeds demo tenants and accounts
+  agents.core:
+    agents.status:
+      command: pnpm flowdular agents status
+      risk: read
+    agents.audit.verify:
+      command: pnpm flowdular agents audit-verify --tenant <id>
+      risk: read
+      localOnly: true
+  sandbox.core:
+    sandbox.access.list:
+      command: pnpm flowdular sandbox access
+      risk: read
+    sandbox.access.grant:
+      command: pnpm flowdular sandbox grant [--apply]
+      risk: process
+      supportsDryRun: true
+    sandbox.access.revoke:
+      command: pnpm flowdular sandbox revoke [--apply]
+      risk: process
+      supportsDryRun: true
+    sandbox.sessions.list:
+      command: pnpm flowdular sandbox sessions
+      risk: read
+    sandbox.sessions.archive:
+      command: pnpm flowdular sandbox session-archive [--apply]
+      risk: process
+      supportsDryRun: true
+    sandbox.sessions.delete:
+      command: pnpm flowdular sandbox session-delete [--apply]
+      risk: process
+      supportsDryRun: true
+    sandbox.audit.verify:
+      command: pnpm flowdular sandbox audit-verify --tenant <id>
+      risk: read
+      localOnly: true
+
+# packages/cli/src/runner.ts, runExtensionCommand, in evaluation order.
+approvals:
+  external: refused with APPROVAL_VERIFIER_REQUIRED (no signed approval verifier exists)
+  destructive-not-local: refused with APPROVAL_VERIFIER_REQUIRED
+  localOnly: refused with LOCAL_ONLY_CAPABILITY unless FD_ENV or NODE_ENV is development or test (unset counts as development)
+  requiresApprovedSpec: needs --spec <path>; APPROVED_SPEC_REQUIRED, SPEC_VALIDATION_FAILED or SPEC_NOT_APPROVED otherwise
+  destructive-apply: --apply needs --confirm <descriptor.confirmation>; CONFIRMATION_REQUIRED otherwise
+  non-read-without-dry-run: EXPLICIT_APPLY_REQUIRED without --apply
+  dry-run: non-read with supportsDryRun and no --apply runs with apply=false and warns "Dry run only. No writes were authorized."
+
+moduleExtensions:
+  discovery: module.json cli.catalog (src/cli/commands.json), schema-validated without executing code
+  loadImplementation: module.json cli.entry imported only when the command runs (packages/cli/src/extensions.ts loadCliCommand)
+  namespace: first segment of the module id; reserved groups help, doctor, capability, spec, blueprint, module, migration, setup
+  metadataIdentical: path and capability object must equal the catalog entry
+  requireEnabledModule: true
+
+# Planned, no code today. Listed so nobody documents them as available.
+planned:
+  - migration.plan (served by "migration apply" without --apply, which is a read-only dry run)
+  - migration.apply.remote
+  - destructive.execute (signed approval receipts)
+  - redaction of *_TOKEN, *_SECRET, *_PASSWORD, DATABASE_URL in a shared logger (only packages/ai-provider/src/errors.ts redactSecrets exists)
+  - persisted CLI audit (CommandEnvelope carries a random auditId and evidence per invocation; nothing stores it)

package/agent-template/.ai/policies/model-routing.yaml

@@ -0,0 +1,72 @@
+schemaVersion: 1
+# Consumed by nobody: packages/cli/src/doctor.ts checks that the file exists
+# (policy.model-routing). The sandbox decides drivers, models and roles in code:
+# - driver per session, changeable per turn (packages/sandbox/src/server/routes.ts)
+# - model from the session (session.model) or the driver default
+#   (packages/sandbox/src/server/turns.ts, packages/coding-agent/src/drivers/*)
+# - role per turn by deterministic rules (packages/sandbox/src/server/planning.ts
+#   routeRole, planHandoff), overridable for one turn in the composer
+# This file documents that behaviour so nobody expects a policy engine.
+
+drivers:
+  claude-code:
+    binary: claude
+    modes: [loopback]
+    tools: [Read, Write, Edit, Glob, Grep]
+    commands: never (no Bash tool; gates run by the sandbox)
+    source: packages/coding-agent/src/drivers/claude-code.ts
+  codex:
+    binary: codex
+    modes: [loopback]
+    sandbox: workspace-write
+    commands: possible inside the workspace; the role contract forbids it but only the sandbox filesystem boundary enforces it
+    source: packages/coding-agent/src/drivers/codex.ts
+  byok:
+    modes: [loopback, self-hosted]
+    kinds: [anthropic, openai, azure, openai-compatible, vercel]
+    tools: sandbox-owned file tools (list 400 files, read 128 KB per file)
+    commands: never
+    source: packages/coding-agent/src/drivers/byok.ts, packages/ai-provider/src/catalog.ts
+
+# Profiles referenced by .ai/blueprints/*/blueprint.json executorProfiles.
+profiles:
+  sandbox-specialist:
+    runs: one of the five roles in .ai/agents/sandbox on the session driver
+    mayApproveSpecs: false
+    mayChangeArchitecture: false
+    mayRunCommands: false
+    landing: eject
+  repo-agent:
+    runs: .ai/agents/module-executor.md or spec-author.md in a checkout with a shell (RuleSync generates each driver's root instructions from .ai/rules)
+    mayApproveSpecs: false
+    mayChangeArchitecture: only through core-extend with an ADR
+    mayRunCommands: true
+    landing: pnpm verify, pull request
+  reviewer:
+    runs: .ai/agents/reviewer.md
+    mayImplement: false
+    output: findings by severity, verdict
+
+# Who takes the first sandbox turn (planning.ts classifyByRules) and how the
+# next role is chosen (planHandoff): the HANDOFF line when it names a
+# registered role, otherwise routeRole by module state, and a failed gate
+# always returns to the same role.
+routing:
+  new-module: business-manager
+  edit-module: business-manager
+  spec-words: business-manager
+  agent-words: agentic-engineer
+  ui-words: frontend-engineer when src/client/contribution.tsrx exists, else ux-designer
+  no-server: backend-engineer
+  no-client: frontend-engineer
+  default: backend-engineer
+
+enforced:
+  - gates listed in a role's front matter plus dependencies, per draft module (turns.ts runSessionGates)
+  - HANDOFF line parsing (packages/coding-agent/src/roles/handoff.ts) and the role's handoff list (planning.ts; self-handoff and roles outside the list fall back to state routing)
+  - approval stop for every new or edited module until the current specification matches the operator-approved SHA-256 hash
+  - writes outside the active role allowedPaths are quarantined and restored before gates, checkpoints, preview or delivery
+  - message length 1 to 20000 characters, brief at least 8 characters
+  - at most four chained automatic turns per operator message (session chainDepth)
+notEnforced:
+  - model choice per role (one model per session)

package/agent-template/.ai/policies/path-ownership.yaml

@@ -0,0 +1,65 @@
+schemaVersion: 1
+# Consumed by nobody (zero references under packages/). Review guidance: who
+# answers for a path and which role may write it.
+owners:
+  packages/contracts/**: platform-architecture
+  packages/kernel/**: platform-architecture
+  packages/server/**: platform-runtime
+  packages/client/**: platform-ui
+  packages/ui/**: platform-ui
+  packages/dev-console/**: platform-ui
+  packages/cli/**: platform-tooling
+  packages/cli-protocol/**: platform-tooling
+  packages/sandbox/**: sandbox-runtime
+  packages/coding-agent/**: sandbox-runtime
+  packages/ai-provider/**: agent-runtime
+  packages/harness/**: agent-runtime
+  modules/auth/**: platform-runtime
+  modules/system/**: platform-architecture
+  modules/users/**: platform-runtime
+  modules/agents/**: agent-runtime
+  modules/sandbox/**: sandbox-runtime
+  modules/{module}/**: module:{module}
+  platform/**: platform-composition
+  infra/**: platform-operations
+  .github/**: platform-operations
+  docs/**: platform-architecture
+  specs/**: platform-architecture
+  .ai/**: platform-architecture
+  rulesync.jsonc: platform-architecture
+  AGENTS.md: generated
+  CLAUDE.md: generated
+  .agents/skills/**: generated
+  .claude/skills/**: generated
+# Inside a module built or changed in the sandbox, the role front matter in
+# .ai/agents/sandbox/*.md says who writes what. Advisory at run time.
+moduleRoles:
+  modules/{module}/spec/**: [business-manager, agentic-engineer]
+  modules/{module}/translations/**: [business-manager]
+  modules/{module}/src/acl/**: [backend-engineer]
+  modules/{module}/src/api/**: [backend-engineer]
+  modules/{module}/src/server/**: [backend-engineer]
+  modules/{module}/src/services/**: [backend-engineer]
+  modules/{module}/src/domain/**: [backend-engineer]
+  modules/{module}/src/platform.ts: [backend-engineer, agentic-engineer]
+  modules/{module}/src/index.ts: [backend-engineer]
+  modules/{module}/migrations/**: [backend-engineer]
+  modules/{module}/src/client/**: [ux-designer, frontend-engineer]
+  modules/{module}/src/agent/**: [agentic-engineer]
+  modules/{module}/tests/**:
+    [backend-engineer, frontend-engineer, agentic-engineer]
+  modules/{module}/module.json: [backend-engineer, agentic-engineer]
+  modules/{module}/package.json:
+    [backend-engineer, frontend-engineer, agentic-engineer]
+cliOwned:
+  flowdular.json: pnpm flowdular module enable|disable --apply
+  platform/package.json: pnpm flowdular module enable --apply
+  platform/src/generated/**: pnpm flowdular module sync --apply
+  packages/coding-agent/src/roles/defaults.ts: role defaults sync script (.ai/README.md)
+  packages/ui/src/brand/mark.ts: node packages/ui/scripts/gen-mark.mjs
+  AGENTS.md: pnpm rules:generate
+  CLAUDE.md: pnpm rules:generate
+  .agents/skills/**: pnpm rules:generate
+  .claude/skills/**: pnpm rules:generate
+crossOwnerChanges:
+  requireReviewer: true

package/agent-template/.ai/policies/task-budgets.yaml

@@ -0,0 +1,37 @@
+schemaVersion: 1
+# Consumed by nobody (zero references under packages/). The values are the
+# review expectation for a change; the sandbox enforces only the limits marked
+# as code.
+defaults:
+  maxChangedFiles: 18
+  maxRepairLoops: 2
+  maxNewDependencies: 0
+  requireTests: true
+  requireTypecheck: true
+overrides:
+  new-module:
+    maxChangedFiles: 30
+    maxNewDependencies: 0
+    note: a full module is about 25 files (.ai/references/catalog has 28 including migrations and translations)
+  edit-module:
+    maxChangedFiles: 12
+  add-migration:
+    maxChangedFiles: 8
+  bug-fix:
+    maxChangedFiles: 4
+    requireTests: true
+  author-spec:
+    maxChangedFiles: 1
+    requireTests: false
+  core-extend:
+    maxChangedFiles: 40
+    note: consumers migrate in the same change; count them
+sandbox:
+  code:
+    messageLength: 1 to 20000 characters (packages/sandbox/src/server/turns.ts)
+    briefLength: at least 8 characters (planning.ts assertBrief)
+    gateTimeout: 5 minutes per gate, output capped at 12000 characters (gates.ts)
+    gateFailure: the same role repairs; no automatic limit on repair turns
+    byokReads: 400 listed files, 128 KB per read (packages/coding-agent/src/drivers/byok.ts)
+  review:
+    chainedTurns: stop and read the transcript after four automatic handoffs on one brief