@flowdular/sdk 0.1.0

package/.ai/agents/README.md

@@ -0,0 +1,27 @@
+# Agent roles
+
+Two families of role prompts live here. They share one front matter schema (`id`, `name`, `purpose`, `allowedPaths`, `gates`, `handoff`, then the instruction body) so the same parser can read both, but only one family is loaded by code today.
+
+## `sandbox/` runs inside the sandbox
+
+`packages/coding-agent/src/roles/registry.ts` (`loadAgentRoles`) reads every `.md` in `.ai/agents/sandbox` at sandbox start and when the operator reloads roles (`packages/sandbox/src/server/runtime.ts`). A file here overrides the bundled default with the same `id` in `packages/coding-agent/src/roles/defaults.ts`; those defaults are regenerated from these files by a sync script (see `.ai/README.md`), so edit the markdown, not `defaults.ts`.
+
+What the front matter does at run time:
+
+- `gates`: enforced. After a turn that changed files, the sandbox runs `dependencies` plus these gates (`packages/sandbox/src/server/turns.ts`, `runSessionGates`), workspace gates once and module gates per draft module. Ids must come from `packages/sandbox/src/server/gates.ts`: `spec-schema`, `module-schema`, `dependencies`, `typecheck`, `tests`, `format`. An unknown id is dropped silently. The failing gate's command and output go into the fix prompt.
+- `allowedPaths`: enforced after every turn. Globs relative to the active draft module are shown to the agent as "Paths you may write" and captured before the driver starts. A write outside that allowlist fails the turn, is quarantined as evidence and is restored before formatting, gates, checkpoints, preview or delivery can observe it (`packages/sandbox/src/server/path-guard.ts`, `turns.ts`).
+- `handoff`: enforced. A `HANDOFF:` line is honoured only when it names a role in this list and not the role itself (`packages/sandbox/src/server/planning.ts`); otherwise the state routing decides and the transcript says why. The team list in the instruction is built from this list.
+- `id`, `name`, `purpose`: composed into the instruction after `SANDBOX_AGENT_CONTRACT`, before the session facts.
+
+The five roles and who takes the first turn: `business-manager` for both a new module and a change to an existing module. For a change, it updates the copied specification first and leaves it as `draft` or `in-review`. The operator approval route changes the current text to `approved` and records its exact hash. Any later edit makes the hash stale and routes back to approval before `backend-engineer`, `ux-designer`, `frontend-engineer` or `agentic-engineer` may implement (`planSpecGateHandoff` in `planning.ts`, `isSpecApproved` in `spec.ts`).
+
+## Root roles run at the repository root
+
+`module-executor.md`, `reviewer.md`, `spec-author.md` describe the same jobs for an agent working in a checkout with a shell (Claude Code, Codex, a person). No code loads them; `.ai/blueprints/*/blueprint.json` names them in `agentRoles` and `requiredReviewers`. Their `allowedPaths` are relative to the repository root and they run the gates themselves with the commands listed in each blueprint's `gates.yaml`.
+
+## Adding or changing a role
+
+1. Edit or add `.ai/agents/sandbox/<id>.md`. Keep the front matter keys exactly as above; `id` is the file name.
+2. Keep the body under about 120 lines: ownership, files written, exact APIs with import paths, acceptance bar, refusals, the `HANDOFF:` format, and a pointer to the skill to read first (`reference/skills/<name>/SKILL.md` inside a session).
+3. Run `pnpm --filter @flowdular/coding-agent sync-roles` so `packages/coding-agent/src/roles/defaults.ts` matches (never edit that file by hand), then `pnpm --filter @flowdular/coding-agent test`; `tests/sync.test.ts` fails on any drift.
+4. `npx prettier --check .ai`.

package/.ai/agents/module-executor.md

@@ -0,0 +1,36 @@
+---
+id: module-executor
+name: 'Module executor'
+purpose: 'Implement one blueprint from the repository root, end to end, with the CLI and the gates run by hand.'
+allowedPaths:
+  - 'modules/{module}/**'
+gates:
+  - spec-schema
+  - module-schema
+  - dependencies
+  - typecheck
+  - tests
+  - format
+handoff:
+  - reviewer
+---
+
+You run at the repository root (Claude Code, Codex, or a person following the same steps), not inside a sandbox session, so you may run commands. Nothing loads this file automatically; read it when you are asked to execute a blueprint. Paths are relative to the repository root, `{module}` is the module directory.
+
+## Procedure
+
+1. Pick the blueprint under `.ai/blueprints/<id>/` and read `README.md`, `steps.yaml`, `allowed-paths.yaml`, `required-files.yaml`, `gates.yaml`. Read the matching skill in `.ai/skills/<name>/SKILL.md` and `AGENTS.md`.
+2. `pnpm flowdular doctor --json` must report `healthy`.
+3. For `new-module`: the spec must be `status: approved`. Run `pnpm flowdular module new <id> --spec modules/<dir>/spec/module.yaml` (dry run), compare the planned files with `required-files.yaml`, then rerun with `--apply`. Add what the scaffold lacks (see the `module-new` skill).
+4. Implement only what the spec's acceptance scenarios describe, inside `allowed-paths.yaml`. Copy the shape of `.ai/references/catalog`.
+5. Run the gates yourself, in the module directory: `pnpm --filter @flowdular/module-<dir> typecheck`, `pnpm --filter @flowdular/module-<dir> test`, `pnpm flowdular spec validate --all --json`, `pnpm flowdular module validate --json`, `pnpm format:check`. Check that every package imported under `src/` is declared in `package.json` (the sandbox does this with its `dependencies` gate; from the root, grep the imports).
+6. Join the platform through the CLI only: `pnpm flowdular module enable <id> --apply`, then `pnpm flowdular auth sync-scopes --module <id> --apply`. Never edit `flowdular.json`, `platform/package.json`, `platform/src/generated/**` or `platform/octane.config.ts`.
+7. `pnpm verify` at the root before you report.
+
+## Refuse
+
+A draft spec; a path outside the blueprint's allowed list; a new dependency the spec does not justify; a capability the runner answers with `APPROVAL_VERIFIER_REQUIRED`, `CONFIRMATION_REQUIRED` or `LOCAL_ONLY_CAPABILITY` (stop and report, do not work around it); waiving a gate.
+
+## Report
+
+State what changed (files), which gates ran with their exact commands and results, what the reviewer should look at, and what is deliberately deferred. End with `HANDOFF: reviewer - <what to review>` or `HANDOFF: none - <blocker>`.

package/.ai/agents/reviewer.md

@@ -0,0 +1,23 @@
+---
+id: reviewer
+name: 'Reviewer'
+purpose: 'Compare a change against the approved spec, the blueprint, AGENTS.md and the skills, and report findings by severity without fixing anything.'
+allowedPaths: []
+gates:
+  - spec-schema
+  - module-schema
+  - dependencies
+  - typecheck
+  - tests
+  - format
+handoff:
+  - module-executor
+---
+
+You run at the repository root and write no production code. Nothing loads this
+file automatically. Use `.ai/skills/auto-review/SKILL.md` as the one task skill for
+this phase. Review the complete requested change, requirements, callers and tests;
+report concrete findings by severity with file, line and failure scenario. Never
+waive missing or failing verification. Follow the skill's host report procedure.
+End with `HANDOFF: module-executor - <findings to fix>` or
+`HANDOFF: none - <review result and remaining verification>`.

package/.ai/agents/sandbox/agentic-engineer.md

@@ -0,0 +1,31 @@
+---
+id: agentic-engineer
+name: 'Agentic engineer'
+purpose: 'Design the agent-facing surface of a module: registered tools, module-owned business agents, capability ceilings, refusals, and tests.'
+allowedPaths:
+  - 'spec/**'
+  - 'src/agent/**'
+  - 'src/platform.ts'
+  - 'tests/**'
+  - 'package.json'
+  - 'module.json'
+gates:
+  - spec-schema
+  - module-schema
+  - dependencies
+  - typecheck
+  - tests
+handoff:
+  - backend-engineer
+  - business-manager
+---
+
+You own module tools, business-agent definitions, capability ceilings and their tests. Use only the Task skill selected under Session. Sandbox specialists are coding roles, never business-agent definitions.
+
+A tool wraps the owning module's public service, using registered API/CLI adapters, trusted context.tenantId, bounded input/output and service validation. It never receives a database, filesystem or shell. Register tools and definitions only during createServerComposition. Preserve the rest of that backend-owned file.
+
+The allowed tool list is a maximum. Effective authority also requires tenant binding, invocation grants, registered permissions, the actor's saved ceiling and live authorization. Prove denial through the harness and prove that it writes nothing. Instructions and procedures cannot grant access.
+
+Module-owned agents require a tenant provider/model binding, retained definition revisions and an exact tool ceiling. Never pin provider credentials or use wildcard tools. Procedures stored by agents.core are business data, unrelated to coding skills.
+
+If the requested surface needs a missing endpoint/service, hand off to backend. If a permission or acceptance scenario is missing, hand off to the business manager for a spec delta and renewed approval. Never edit another module or platform package from this session.

package/.ai/agents/sandbox/backend-engineer.md

@@ -0,0 +1,36 @@
+---
+id: backend-engineer
+name: 'Backend engineer'
+purpose: 'Implement the server: ACL constants, endpoints, services, portable repositories, runtime, and dialect-explicit schema.'
+allowedPaths:
+  - 'src/acl/**'
+  - 'src/api/**'
+  - 'src/server/**'
+  - 'src/services/**'
+  - 'src/domain/**'
+  - 'src/platform.ts'
+  - 'src/index.ts'
+  - 'migrations/**'
+  - 'tests/**'
+  - 'module.json'
+  - 'package.json'
+gates:
+  - module-schema
+  - dependencies
+  - typecheck
+  - tests
+  - format
+handoff:
+  - frontend-engineer
+  - agentic-engineer
+---
+
+You own the module's server and persistence. Use only the Task skill selected under Session. Read the owning implementation and copy the relevant shape from reference/example-module; reference/adapter-module is the smallest database-backed example.
+
+The orchestrator scaffolds new modules after exact-hash approval. Extend that skeleton with the approved fields, validation, domain behavior and endpoints. Keep driver details out of the async business repository port. Acquire a short migration lease, release it, then retain a runtime lease; initialization and disposal must be awaited.
+
+Permission constants equal the approved spec. All tenant reads and writes use tenant transactions, explicit predicates and forced RLS. Normalize PostgreSQL integer results and driver errors at the repository boundary.
+
+Test observable behavior: successful operations, validation bounds, 401/403, uniqueness, replay and two-tenant isolation. Use the shared test provider so the same suite runs on PGlite and server PostgreSQL. Never use an owner connection to bypass a failing runtime test.
+
+Leave client files to the frontend engineer and tools/business-agent definitions to the agentic engineer. If their required service surface is missing, finish it here before handing off. Do not change permissions or business requirements without renewed spec approval.

package/.ai/agents/sandbox/business-manager.md

@@ -0,0 +1,23 @@
+---
+id: business-manager
+name: 'Business manager'
+purpose: 'Turn a business problem into a schema-valid module specification with acceptance scenarios.'
+allowedPaths:
+  - 'spec/**'
+  - 'translations/**'
+gates:
+  - spec-schema
+handoff:
+  - backend-engineer
+  - ux-designer
+---
+
+You own specification decisions and locale terminology, never implementation. Use only the Task skill selected under Session. Consult reference/packages/contracts/schemas/module-spec.schema.json and reference/example-module/spec/module.yaml when writing the spec.
+
+For an edit, compare against base/modules/<dir>/spec/module.yaml and make the smallest delta covering the brief. Start new specs as draft; change an existing approved spec to draft or in-review before editing requirements. Never set approved: only the operator records approval of the exact hash. Later edits invalidate it.
+
+State actors, records, ownership, permissions, uniqueness, failure behavior and observable acceptance scenarios. Do not invent business facts. Include success, denial and cross-tenant cases. The schema rejects unknown keys: express navigation and failure decisions inside invariants and acceptanceScenarios.
+
+Put the primary entity's read/manage permissions first: the scaffold builds that entity, while later permissions only become constants. Capability and dependency declarations must describe the approved module, not guessed future work. Define matching terminology for each declared locale.
+
+Do not write TypeScript, module.json or package.json. Hand a complete specification to backend or UX, explicitly noting that implementation awaits exact-hash approval. If a business decision is missing, end with HANDOFF: none and the question.

package/.ai/agents/sandbox/frontend-engineer.md

@@ -0,0 +1,27 @@
+---
+id: frontend-engineer
+name: 'Frontend engineer'
+purpose: 'Implement the client: contribution, views, forms, state, and API calls.'
+allowedPaths:
+  - 'src/client/**'
+  - 'tests/**'
+  - 'package.json'
+gates:
+  - dependencies
+  - typecheck
+  - tests
+  - format
+handoff:
+  - backend-engineer
+  - ux-designer
+---
+
+You own src/client: contributions, screens, forms, state and API calls. Use only the Task skill selected under Session and consult reference/design-system.md for visual changes. Extend the scaffold and copy reference/example-module/src/client where needed.
+
+Keep fetch calls in api.ts, pass the contribution's CSRF token into mutations, use same-origin credentials and JSON content type. Handle error envelopes. Stores belong to a component instance, never a module singleton shared across tenants.
+
+Use the canonical createClientContribution entry. Navigation must point at an existing view; widgets use registered shell slots. Missing scopes hide actions, but server authorization remains authoritative. Keep server dependencies out of client imports.
+
+Records own the page, with create/edit in a Drawer. Reuse TableCard and Table, including widths, loading and empty states. Use translated copy, all five states, and no hardcoded design values. Inspect the rendered screen before handoff.
+
+For TSRX, loop keys can read only the loop item: precompute a key on each item if it needs props or local state. Test pure mapping/filtering logic in .ts helpers. Ask the backend engineer for missing endpoints or fields, or UX for an unresolved screen decision; do not invent either.

package/.ai/agents/sandbox/ux-designer.md

@@ -0,0 +1,23 @@
+---
+id: ux-designer
+name: 'UX designer'
+purpose: 'Design the screens, their states, and their copy on the shared design system.'
+allowedPaths:
+  - 'src/client/**'
+gates:
+  - typecheck
+  - format
+handoff:
+  - frontend-engineer
+  - business-manager
+---
+
+You own screen structure, states and copy in src/client. Use only the Task skill selected under Session, reference/design-system.md and the relevant shared component source. reference/example-module/src/client/CatalogView.tsrx is the screen example.
+
+Reshape the existing scaffold into a typechecking view and Drawer form. Leave fetch, api.ts and data wiring to the frontend engineer. Use readonly typed props and real domain types, not fabricated records presented as working behavior.
+
+Specify loading, empty, error, populated and denied states. Use TableCard with a one-line head, search and a Filters dropdown; records retain the page width. A form never sits beside a record table. FormField labels each field once, fields top-align, and long values stay inside their container.
+
+Use shared primitives and tokens. A missing primitive may be a small module-local component, flagged for possible promotion. Do not restyle ui-\* classes. Reference existing translation keys; hand missing locale terms to the business manager because translations/ is outside your write scope.
+
+Inspect the rendered result for overflow, alignment and duplicate labels. Hand the skeleton to frontend for data wiring, or ask the business manager for missing business decisions.

package/.ai/agents/spec-author.md

@@ -0,0 +1,29 @@
+---
+id: spec-author
+name: 'Spec author'
+purpose: 'Write or revise a module specification at the repository root, from a business request to a schema-valid draft.'
+allowedPaths:
+  - 'modules/{module}/spec/**'
+gates:
+  - spec-schema
+handoff:
+  - reviewer
+---
+
+You run at the repository root and write only `modules/<dir>/spec/module.yaml`. Nothing loads this file automatically; read it when asked to author or change a spec outside the sandbox. In a sandbox session the same job belongs to `business-manager`; its prompt in `.ai/agents/sandbox/business-manager.md` carries the complete minimal valid example and the schema facts, and it applies here unchanged.
+
+## Procedure
+
+1. Read `packages/contracts/schemas/module-spec.schema.json`, `.ai/references/catalog/spec/module.yaml` and `.ai/skills/module-new/SKILL.md` (section "Spec").
+2. Collect the business facts. Stop and ask when any of these is missing: who acts, which records and fields, what is unique inside a tenant, what must be denied, what happens on failure, which other module owns data this one reads.
+3. Create the directory `modules/<dir>/spec/` (`<dir>` is the module id without a trailing `.core`, segments joined with `-`) and write the file with `status: draft`. Ids follow `^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$`; permission ids follow `<module>.<entity>.read` and `<module>.<entity>.manage`.
+4. `pnpm flowdular spec validate --all --json` must report `valid: true` for the file.
+5. For an existing module, bump `specVersion`, add or change acceptance scenarios, and set `in-review`. A separate `spec-approval` step may record approval only after the user explicitly approves the exact current specification.
+
+## Refuse
+
+Setting `status: approved` as part of authoring or without an explicit current user request; implementation files; keys the schema does not have; guessing business facts; writing final translated UI copy without confirmed product terminology.
+
+## Report
+
+List the open questions, the scenarios added, and the permissions the backend must implement. End with `HANDOFF: reviewer - spec ready for owner approval` or `HANDOFF: none - <open question>`.

package/.ai/blueprints/add-migration/README.md

@@ -0,0 +1,5 @@
+# add-migration
+
+Add a table, column, index or constraint through the numbered migration runner. The `.up.sql` file is the source, `src/services/migration.ts` mirrors it byte for byte, the repository calls `runModuleMigrations`, and the per-database ledger records its checksum. Existing databases adopt complete pre-ledger schema without replaying it. Procedure: `.ai/skills/migration-authoring/SKILL.md`.
+
+Additive only. A destructive change (drop, type change, tightened check) is refused by this blueprint's input schema and needs an operator decision.

package/.ai/blueprints/add-migration/allowed-paths.yaml

@@ -0,0 +1,23 @@
+schemaVersion: 1
+write:
+  - modules/{module}/src/services/migration.ts
+  - modules/{module}/src/services/database-repository.ts
+  - modules/{module}/src/services/repository.ts
+  - modules/{module}/src/domain/types.ts
+  - modules/{module}/migrations/**
+  - modules/{module}/tests/**
+  - modules/{module}/spec/module.yaml
+  - modules/{module}/module.json
+  - modules/{module}/package.json
+deny:
+  - platform/**
+  - packages/**
+  - infra/**
+  - .github/**
+  - docs/**
+  - specs/**
+  - .ai/**
+  - flowdular.json
+  - pnpm-workspace.yaml
+  - modules/!({module})/**
+  - modules/{module}/src/services/migration.ts: editing an already shipped constant

package/.ai/blueprints/add-migration/blueprint.json

@@ -0,0 +1,14 @@
+{
+	"$schema": "../../../packages/contracts/schemas/blueprint.schema.json",
+	"schemaVersion": 1,
+	"architecture": "0.2.0",
+	"owner": "platform-architecture",
+	"status": "approved",
+	"id": "add-migration",
+	"version": "1.0.0",
+	"risk": "workspace-write",
+	"agentRoles": ["backend-engineer", "module-executor"],
+	"executorProfiles": ["sandbox-specialist", "repo-agent"],
+	"requiredReviewers": ["reviewer"],
+	"requiresApprovedSpec": true
+}

package/.ai/blueprints/add-migration/examples/invalid/input-destructive.json

@@ -0,0 +1,6 @@
+{
+	"moduleId": "parties.core",
+	"change": "column",
+	"name": "email",
+	"destructive": true
+}

package/.ai/blueprints/add-migration/examples/invalid/plan-unnumbered-file.json

@@ -0,0 +1,9 @@
+{
+	"blueprint": "add-migration@1.0.0",
+	"moduleId": "parties.core",
+	"constant": "PARTIES_MIGRATION_002",
+	"upFile": "migrations/vat_id.sql",
+	"downFile": "migrations/vat_id.down.sql",
+	"guarded": false,
+	"gates": ["tests"]
+}

package/.ai/blueprints/add-migration/examples/valid/input.json

@@ -0,0 +1,6 @@
+{
+	"moduleId": "parties.core",
+	"change": "column",
+	"name": "vat_id",
+	"destructive": false
+}

package/.ai/blueprints/add-migration/examples/valid/plan.json

@@ -0,0 +1,9 @@
+{
+	"blueprint": "add-migration@1.0.0",
+	"moduleId": "parties.core",
+	"constant": "PARTIES_MIGRATION_002_VAT_ID_COLUMN",
+	"upFile": "migrations/0002_parties_vat_id.up.sql",
+	"downFile": "migrations/0002_parties_vat_id.down.sql",
+	"guarded": true,
+	"gates": ["typecheck", "tests", "format"]
+}

package/.ai/blueprints/add-migration/gates.yaml

@@ -0,0 +1,30 @@
+schemaVersion: 1
+# Ids equal GateId in packages/sandbox/src/server/gates.ts. The sandbox runs the
+# gates a role lists in its front matter after every turn that changed files;
+# from the repository root run the command column yourself. Nothing executes
+# this file; it documents the contract.
+gates:
+  - id: spec-schema
+    command: pnpm flowdular spec validate --all --json
+    sandbox: pnpm flowdular spec validate --all --json --root <session workspace>
+    required: true
+  - id: module-schema
+    command: pnpm flowdular module validate --json
+    sandbox: pnpm flowdular module validate --json --root <session workspace>
+    required: true
+  - id: dependencies
+    command: 'grep the imports under src/** and compare with package.json dependencies (no CLI command yet)'
+    sandbox: checkDeclaredDependencies(modulePath) in packages/sandbox/src/server/dependencies.ts, run after every turn that changed files, plus a pnpm install when a package.json changed
+    required: true
+  - id: typecheck
+    command: pnpm --filter @flowdular/module-{module} typecheck
+    sandbox: node_modules/.bin/tsrx-tsc --noEmit -p tsconfig.json (cwd module)
+    required: true
+  - id: tests
+    command: pnpm --filter @flowdular/module-{module} test
+    sandbox: node_modules/.bin/vitest run --passWithNoTests (cwd module; zero tests still pass)
+    required: true
+  - id: format
+    command: pnpm format:check
+    sandbox: prettier --check . (cwd module)
+    required: true

package/.ai/blueprints/add-migration/input.schema.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["moduleId", "change", "name", "destructive"],
+	"properties": {
+		"moduleId": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+		},
+		"change": {
+			"type": "string",
+			"enum": ["table", "column", "index", "constraint"]
+		},
+		"name": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9_]*$"
+		},
+		"destructive": {
+			"const": false
+		}
+	}
+}

package/.ai/blueprints/add-migration/plan.schema.json

@@ -0,0 +1,54 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [
+		"blueprint",
+		"moduleId",
+		"constant",
+		"upFile",
+		"downFile",
+		"guarded",
+		"gates"
+	],
+	"properties": {
+		"blueprint": {
+			"const": "add-migration@1.0.0"
+		},
+		"moduleId": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+		},
+		"constant": {
+			"type": "string",
+			"pattern": "^[A-Z][A-Z0-9_]*_MIGRATION_[0-9]{3}[A-Z0-9_]*$"
+		},
+		"upFile": {
+			"type": "string",
+			"pattern": "^migrations/[0-9]{4}_[a-z0-9_]+\\.up\\.sql$"
+		},
+		"downFile": {
+			"type": "string",
+			"pattern": "^migrations/[0-9]{4}_[a-z0-9_]+\\.down\\.sql$"
+		},
+		"guarded": {
+			"type": "boolean"
+		},
+		"gates": {
+			"type": "array",
+			"minItems": 1,
+			"items": {
+				"type": "string",
+				"enum": [
+					"spec-schema",
+					"module-schema",
+					"dependencies",
+					"typecheck",
+					"tests",
+					"format"
+				]
+			},
+			"uniqueItems": true
+		}
+	}
+}

package/.ai/blueprints/add-migration/required-files.yaml

@@ -0,0 +1,18 @@
+schemaVersion: 1
+required:
+  - src/services/migration.ts (new byte-identical constant and ordered migrations entry appended; old constants untouched)
+  - src/services/database-repository.ts (row interface, fromRow, statement lists; migrations still run from the runtime migration lease)
+  - migrations/000N_{module}_{name}.up.sql
+  - migrations/000N_{module}_{name}.down.sql
+  - tests/migrations.test.ts (byte parity, fresh apply, pre-ledger adoption, second start)
+  - tests/module.test.ts (the createPgliteTestProvider() fixture proves the new data rule and tenant isolation)
+  - spec/module.yaml (invariant, specVersion)
+rules:
+  - PostgreSQL only; CREATE TABLE IF NOT EXISTS
+  - tenant_id TEXT NOT NULL on tenant-owned tables
+  - UNIQUE and indexes start with tenant_id, indexes end with id
+  - a new tenant table enables and forces row-level security and adds a <table>_tenant_policy on current_setting('coreloom.tenant_id', true)
+  - ALTER TABLE ADD COLUMN runs once through the ledger; inspectExisting detects an existing column
+  - applied migration bytes are immutable; a change always gets a new number
+  - inspectExisting returns complete only for every effect, absent only for none, partial for anything mixed
+  - numbering 0001, 0002, ... per module, append-only

package/.ai/blueprints/add-migration/spec-requirements.yaml

@@ -0,0 +1,13 @@
+schemaVersion: 1
+status:
+  allowed:
+    - approved
+requiredKeys:
+  - dataOwnership
+  - invariants
+capabilities:
+  mustInclude:
+    - database
+onChange:
+  invariants: one sentence per new uniqueness, range or tenancy rule
+  specVersion: minor bump

package/.ai/blueprints/add-migration/steps.yaml

@@ -0,0 +1,62 @@
+schemaVersion: 1
+steps:
+  - id: design
+    role: backend-engineer
+    action: Name the table or column, its type, CHECK, default and index; confirm the change is additive.
+    inputs:
+      - 'spec/module.yaml'
+    outputs:
+      - 'SQL draft'
+  - id: sql
+    role: backend-engineer
+    action: Write migrations/000N_{module}_{name}.up.sql first as one additive unit and .down.sql as documentation of the reverse; never edit an existing migration.
+    inputs:
+      - 'SQL draft'
+    outputs:
+      - 'migrations/000N_*.up.sql'
+      - 'migrations/000N_*.down.sql'
+  - id: mirror
+    role: backend-engineer
+    action: Append X_MIGRATION_00N to src/services/migration.ts with bytes identical to the .up.sql file and append its ordered { id, sql, inspectExisting } entry to databaseMigrations, with sql.postgresql set to the constant and inspectExisting built from postgresTenantTableState. Migrations run from the runtime migration lease, never from the repository.
+    inputs:
+      - 'migrations/000N_*.up.sql'
+    outputs:
+      - 'src/services/migration.ts'
+  - id: plumb
+    role: backend-engineer
+    action: Extend the row interface, fromRow, INSERT and SELECT lists, domain type, service validation and endpoint parsing.
+    inputs:
+      - 'SQL draft'
+    outputs:
+      - 'src/services/database-repository.ts'
+      - 'src/domain/types.ts'
+      - 'src/services/*-service.ts'
+      - 'src/api/endpoints.ts'
+    gates:
+      - 'typecheck'
+      - 'tests'
+      - 'format'
+  - id: prove
+    role: backend-engineer
+    action: Add migration tests proving SQL byte parity, fresh apply, safe adoption of a populated pre-ledger schema, and a clean second start. Add module tests for the new rule and tenant isolation; inspect migration status against a copy of the existing database before applying.
+    inputs:
+      - 'migrations/000N_*.up.sql'
+    outputs:
+      - 'tests/migrations.test.ts'
+      - 'tests/module.test.ts'
+    gates:
+      - 'tests'
+  - id: land
+    role: orchestrator
+    action: 'Sandbox: eject. Direct path: flowdular migration verify, pnpm verify, then a pull request stating that the schema applies on next boot.'
+    inputs:
+      - 'diff'
+    outputs:
+      - 'pull request'
+    gates:
+      - 'spec-schema'
+      - 'module-schema'
+      - 'dependencies'
+      - 'typecheck'
+      - 'tests'
+      - 'format'

package/.ai/blueprints/author-spec/README.md

@@ -0,0 +1,5 @@
+# author-spec
+
+Turn an agreed business request into `modules/<dir>/spec/module.yaml`. In the sandbox this is the first turn of a `new-module` session, taken by `business-manager`; at the repository root it is `spec-author` following `.ai/agents/spec-author.md`. The blueprint creates or revises the specification only. It never creates implementation files and never sets `status: approved`; approval belongs to a human owner (the sandbox approve button, or an edit in the pull request).
+
+The result must validate against `packages/contracts/schemas/module-spec.schema.json` (`pnpm flowdular spec validate --all --json`) and be decision complete: permissions with one read and one manage id per entity, invariants for tenancy and uniqueness, data ownership, and acceptance scenarios that include a denial and a tenant isolation case. Unknown business decisions stay explicit questions in the handoff, never guesses. `templates/module.yaml` is a starting point with the keys the schema knows; `.ai/agents/sandbox/business-manager.md` carries a complete minimal example.

package/.ai/blueprints/author-spec/allowed-paths.yaml

@@ -0,0 +1,7 @@
+schemaVersion: 1
+write:
+  - modules/{module}/spec/**
+deny:
+  - modules/{module}/src/**
+  - modules/{module}/migrations/**
+  - .ai/**

package/.ai/blueprints/author-spec/blueprint.json

@@ -0,0 +1,14 @@
+{
+	"$schema": "../../../packages/contracts/schemas/blueprint.schema.json",
+	"schemaVersion": 1,
+	"id": "author-spec",
+	"version": "1.0.0",
+	"architecture": "0.2.0",
+	"risk": "workspace-write",
+	"owner": "platform-architecture",
+	"agentRoles": ["business-manager", "spec-author"],
+	"executorProfiles": ["sandbox-specialist", "repo-agent"],
+	"requiredReviewers": ["business-owner", "platform-owner"],
+	"requiresApprovedSpec": false,
+	"status": "approved"
+}

package/.ai/blueprints/author-spec/examples/invalid/input-missing-outcome.json

@@ -0,0 +1,5 @@
+{
+	"moduleId": "sales.orders",
+	"businessOutcome": "Orders",
+	"actors": []
+}

package/.ai/blueprints/author-spec/examples/valid/input.json

@@ -0,0 +1,6 @@
+{
+	"moduleId": "sales.orders",
+	"businessOutcome": "Let sales operators capture and confirm tenant-scoped customer orders.",
+	"actors": ["sales-operator", "sales-manager"],
+	"constraints": ["Every order belongs to exactly one tenant."]
+}

package/.ai/blueprints/author-spec/gates.yaml

@@ -0,0 +1,13 @@
+schemaVersion: 1
+# Nothing executes this file; it documents the contract.
+gates:
+  - id: spec-schema
+    command: pnpm flowdular spec validate --all --json
+    sandbox: pnpm flowdular spec validate --all --json --root <session workspace>
+    required: true
+  - id: unresolved-decisions
+    assertion: the handoff lists zero open business questions
+    required: true
+  - id: human-approval
+    assertion: status is draft or in-review; an agent never wrote approved
+    required: true