@dforge-core/dforge-mcp 0.1.13 → 0.2.1

package/skills/dforge-mcp-author/references/action-dsl.md

@@ -464,14 +464,49 @@ In `ui/actions.json`:
 | `entityCode` | Yes | Which entity this action applies to |
 | `executionMode` | Yes | `"single"` (default) or `"each"` — runs per record, DSL uses `[field]`; or `"batch"` — runs once, DSL uses `for x in records { ... }` with `__records` |
 | `script` | Yes | DSL script name (without path or extension — matches filename in `logic/actions/`) |
-| `isTransacted` | Recommended | `true` = all changes roll back on error; `false` = partial commits possible |
+| `isTransacted` | Recommended | `true` = the first record that fails aborts the run; `false` = the failure is reported and the loop moves to the next record. It does **not** open a transaction — see *Don't assume your action is atomic* below |
 | `orderNum` | Recommended | Display order in the action menu |
 | `isAsync` | Optional | `true` = runs in background via Hangfire, user gets completion notification |
 
+## Don't assume your action is atomic
+
+An action is **not** reliably one transaction, and `isTransacted: true` does not
+make it one — it only decides whether the first failing record aborts the run.
+Whether the writes made before a failure survive depends on the execution path:
+
+| path | mode | writes before the failure |
+|---|---|---|
+| Sync execute, entity **with** `auditHistory` | `single` | rolled back |
+| Sync execute, entity **with** `auditHistory` | `batch` | **stay committed** |
+| Sync execute, entity without it | either | **stay committed** |
+| Scheduled job | — | rolled back |
+| Background (`isAsync: true`) action | either | **stay committed** |
+
+Both "rolled back" rows are a side effect of the audit machinery opening a
+transaction the action then inherits — and in `batch` mode it opens only after the
+script has finished, so it doesn't cover the script at all. Adding or removing
+`auditHistory`, or switching between `single` and `batch`, changes whether a failed
+action leaves partial writes behind, with no change to the action itself.
+
+**This is a platform defect, not a contract** — actions are intended to be atomic,
+and this table is what happens until that lands. So don't design around either
+outcome, and don't reach for `auditHistory` as an atomicity switch.
+
+**Write actions that don't depend on it:** do all validation up front and call
+`error()` before any `insert()` / `update()`, so there is nothing to unwind either
+way.
+
 ## SQL in query() — important notes
 
 `query()` is the **escape hatch** — reach for it only when the structured built-ins can't express the read/write (aggregates, multi-hop joins, CTEs, `FOR UPDATE`). For row-shaped work prefer `select()` / `insert()` / `update()` / `delete()`: they validate entity codes against metadata, coerce values per column, and (for `insert`/`update`) maintain auto-fill and audit columns.
 
+> **`query()` runs on a pooled, shared connection.** Once your statement — or the
+> surrounding transaction, where there is one — finishes, that connection is
+> handed to another request. So never leave state behind on it: use `SET LOCAL`
+> rather than `SET`, `pg_advisory_xact_lock()` rather than `pg_advisory_lock()`,
+> and `ON COMMIT DROP` on any temp table. Only `query()` can do any of this — the
+> structured built-ins emit plain DML — and nothing checks it statically.
+
 1. **Table names are schema-qualified** within the module: `crm.contact`, `wms.stock_movement`, `fin.invoice`. Use the module code as the schema prefix. (Module codes with a hyphen, e.g. `crm-fin`, cannot be schema-qualified in raw SQL — another reason to use the structured built-ins, which accept the qualified `module.entity` code.)
 2. **Use `@param` placeholders** for values — NEVER concatenate user input into SQL strings. The engine auto-parameterizes.
 3. **SELECT, INSERT, UPDATE, DELETE all work** via `query()`. For reads, it returns row arrays. For writes, it executes the statement.

package/skills/dforge-module-build/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: dforge-module-build
+description: Phases 1-5 of dForge module authoring — scaffold the module, then build entities and fields, relations, roll-ups and status columns, actions/triggers/jobs/webhooks, data views and menus, reports, settings, translations, seed data, and the security roles and rights matrix. Use when dforge_module_plan reports a currentPhase of 1-5, or when adding to / fixing an existing module's entities, views, or security. Not for the design documents (dforge-module-design) or for packing and installing (dforge-module-ship).
+---
+
+# dForge module — Build (Phases 1–5)
+
+Phase 0 is done and `readyToScaffold: true`. You're now producing the actual
+module artifacts.
+
+**Before each phase:** run `dforge_module_inspect` and parse
+`files["_inspect.json"]` — never plan a patch against what you assume is there.
+**After each phase:** record it with
+`dforge_module_plan({ action: "complete_phase", moduleDir, phase: "N", note: "..." })`.
+
+## Loading policy — one reference per step, at the step
+
+**Load nothing up front.** Pull the row you need when you need it, by URI.
+Re-load on every backtrack into that element type. The example files are
+mandatory structure validators — never work from memory for schema shapes,
+flags, or column patterns.
+
+| When you need to… | Load (primary reference + example) | Also load |
+|---|---|---|
+| Add any field | `dforge://reference/field-types`, `dforge://reference/flags`, `dforge://example/entities/todo_item.json` | — |
+| Add a relation / Set column | `dforge://reference/column-types`, `dforge://example/entities/todo_item.json` | — |
+| Reuse a type/enum across columns (a `domain`) | `dforge://reference/column-domains` | `dforge://schema/domains` |
+| Add a formula column | `dforge://reference/formulas` | — |
+| Add a trait | `dforge://reference/traits` | — |
+| Add a number sequence | `dforge://reference/number-sequences` | — |
+| Add a grid / list view | `dforge://reference/data-views`, `dforge://example/ui/data_views.json` | — |
+| Add a matrix (pivot) view | `dforge://reference/data-views` (§Matrix), `dforge://example/matrix-budget/ui/data_views.json`, `dforge://example/matrix-budget/entities/budget_line.json` | — |
+| Add kanban / calendar / tree-grid / master-detail | `dforge://reference/data-views` | `dforge://schema/data-views` |
+| Add a menu | `dforge://reference/menus`, `dforge://example/ui/menus.json` | — |
+| Add an action | `dforge://reference/action-dsl`, `dforge://example/logic/actions/mark_done.dsl`, `dforge://example/ui/actions.json` | `dforge://docs/dsl` |
+| Add a trigger | — | `dforge://schema/triggers`; condition syntax in `dforge://docs/dsl` |
+| Add a scheduled job | `dforge://reference/jobs` | `dforge://schema/jobs` |
+| Add a webhook | — | `dforge://schema/webhooks` |
+| Add filters (views, folders, reports) | `dforge://reference/filters` | — |
+| Add roles or security folders | `dforge://reference/security`, `dforge://reference/filters`, `dforge://example/security/roles.json` | — |
+| Add a report | `dforge://reference/reports` | `dforge://schema/reports` |
+| Add a print template | `dforge://reference/print-templates` | — |
+| Wire OCR / document extraction | `dforge://reference/document-extraction` | `dforge://docs/dsl` |
+| Add / localize translations | `dforge://reference/translations` | — |
+| Add module settings | `dforge://reference/settings` | — |
+| Add saved queries | `dforge://reference/queries` | — |
+| Import from DBML/SQL | `dforge://reference/schema-import` | — |
+| Import from a spreadsheet | `dforge://reference/excel-import` | — |
+| Migrate a legacy database | `dforge://reference/data-migration` | — |
+
+## Core rules — the always-on cheat sheet
+
+Enough to author inline; load the linked reference for the full detail.
+
+- **Naming.** `code`, entity `dbObject`, column keys: all `snake_case`,
+  case-sensitive, entities singular (`opportunity_line`). `code` = DB schema name.
+- **A relation is TWO columns + a references entry.** Use
+  `dforge_entity_reference_add` — it emits all three parts. → `column-types`
+- **Flags** are letters from `V I E M H` only (never `U`/`S`/`P`): `VEM`
+  required+visible, `VE` optional+visible, `V` read-only, `EM` hidden FK, `I`
+  trait-provided. → `flags`
+- **`fieldTypeCd` = UI control; `dbDatatype` = SQL type.** Omit `dbDatatype` on
+  plain data columns — it's derived. Set it only for a hidden FK or to override
+  size/precision. Common fixes: `number` not `integer`/`float`; `phone` not
+  `phoneNumber`; `date` not `datePicker`; `timestamptz` not `datetime`; `bool`
+  not `boolean`; `varchar`/`text` not `string`. → `field-types`
+- **Formula columns** (`columnType: "F"`): `baseDatatypeCd` required, no
+  `dbDatatype`, `flags: "V"`. → `formulas`
+- **Roll-up totals** over a child set are Generated (`G`) columns with
+  `SUM([set].[field])` — **never** Formula (`F`), whose set-aggregates silently
+  render empty — and they aggregate only a **physical** child column. Use
+  `dforge_entity_rollup_add`. → `column-types`
+- **Column defaults** are set via `formula` (`"TODAY()"`, `"'draft'"`), a
+  `numberSequence`, or DSL. Entity fields have **no** `defaultValue` key —
+  that's settings-only. → `field-types`
+- **Traits:** default `["identity", "audit"]`. `audit-full` adds required
+  `created_by`/`last_updated_by` with no default — a seeded `audit-full` entity
+  must set both to `0` in every record, or use plain `audit`. → `traits`
+- **`toString`** on every entity, `{column}` braces: `"{first_name} {last_name}"`.
+- **Data views:** `dataSources` array at root — never a root-level `entityCode` +
+  `columns`. Sort is `"order": ["-col", "col"]`. → `data-views`
+- **Menus:** leaf items use `dataViewCode` (not `viewCode`); section nodes omit
+  `itemType`; icons are Bootstrap names **without** `bi-`. Use
+  `dforge_menu_add`. → `menus`
+- **Rights keys:** same-module entity bare (`product`); cross-module entity
+  dotted (`fin.invoice`); actions/reports/folders take a **colon** —
+  `action:approve`, `report:summary`, `folder:east` (never a dot). Deny by
+  omitting the key, never `""`. `roles.json` carries `description` + `rights`
+  only — no `label`. → `security`
+- **Action `script`** in `ui/actions.json` is a bare filename (no path, no
+  `.dsl`).
+- **Action DSL dates:** inside `execute:` use lowercase `now()`. `TODAY()`/`NOW()`
+  are formula-only and undefined in `execute:`. → `action-dsl`
+- **SQL placeholders** are `@paramName`, not `:paramName`.
+- **Manifest:** non-English locales go in `supportedLocales` (`ll-CC`, never
+  `en`/`en-US`); there is no `translations` manifest key. `security` has both
+  `roles` and `folders`. → `manifest`
+- **Seed data:** explicit numeric PKs under `{entity}_id`; parents before
+  children via the `NN-` prefix. Use `dforge_seed_add`.
+
+## Phase 1 — Domain (required)
+
+> **Fast on-ramp.** If the user already has the model in **DBML** → use
+> `dforge_dbml_import`. In a **spreadsheet** → load
+> `dforge://reference/excel-import`; a binary `.xlsx` must be decoded first with
+> `dforge://script/xlsx-to-model` (`python3 tmp.py file.xlsx` → `{sheets:[…]}`),
+> then turned into a table-spec for `dforge_module_import`. A `.csv` is plain
+> text — read it directly. Both paths ADD entities; show the proposed table-spec
+> for sign-off first, then run `dforge_module_validate` and refine the generated
+> grids.
+
+**This phase's first deliverable, before any tool call, is the proposed entity
+inventory.** The user needs to see "the module will have these N things in it"
+before files exist — entities are the spine everything else references.
+
+```
+Proposed entities (N):
+- <entity_code> — <one-line purpose, tied to a verb from intake>
+```
+
+Loop with the user until they explicitly approve.
+
+**Pre-scaffold consistency checks** against `docs/DESIGN.md` — if any fail,
+surface it and go back to Phase 0c; don't silently adjust the design:
+
+1. Every FK in the relationship map has a corresponding field on the child.
+2. Every action's `canExecute` guard references a status value that exists.
+3. Every seed record's FK points at a parent that is also seeded.
+4. Every formula uses only fields on the same entity or exactly one FK hop away.
+5. Every set aggregate is a Generated column over a physical child column.
+6. Every seeded `audit-full` entity sets `created_by`/`last_updated_by: 0`.
+
+Then: `dforge_module_create` → per-entity loop.
+
+**Per-entity loop.** For each entity, propose fields + traits + relations, get
+approval, then patch. Reach for the **composite tools first**:
+
+- relation → `dforge_entity_reference_add`
+- roll-up total → `dforge_entity_rollup_add`
+- status column → `dforge_entity_status_add`
+- plain scalar → `dforge_entity_field_add`
+
+**Field batching rule** — the only Phase 1 exception to one-at-a-time. A field
+is batchable only if ALL of: scalar primitive (string/integer/decimal/boolean/
+date), no FK or reference, no formula, and unambiguous nullability. Everything
+else goes one at a time. This never justifies batching entities, views, roles,
+actions, or reports.
+
+**Extension entities last.** `extends: "module.entity"`, `toString: null`,
+dotted manifest key. Snapshot the base entity's fields with
+`dforge_module_inspect` on the dependency dir when it's available locally;
+otherwise document the known base fields and note that drift tracking is the
+user's responsibility.
+
+**Exit:** every entity has PK + audit traits + at least one user-visible field;
+FK references resolve; the manifest's `entities` map reflects reality.
+
+## Phase 2 — Behavior (all optional)
+
+Four kinds of behavior, all individually skippable. **Do not fabricate behavior
+to fill a sub-step** — a pure CRUD module skips Phase 2 entirely (record it with
+`skipped: true`).
+
+| Sub-step | Fires when | Tool |
+|---|---|---|
+| 2a Actions | user clicks a button | `dforge_action_add` |
+| 2b Triggers | a DB event happens | `dforge_trigger_add` |
+| 2c Jobs | a cron timer fires | `dforge_job_add` |
+| 2d Webhooks | a DB event → outbound POST | `dforge_webhook_add` |
+
+**2a Actions.** Load all four resources in the action row — the wrong-field-
+access / wrong-batch-flag / wrong-`ui/actions.json`-property mistakes only
+surface when you cross-check them. Draft the DSL, run
+**`dforge_action_check({ dslBody, executionMode })`** to catch install failures
+before committing, then `dforge_action_add`. One action per turn.
+
+**2b Triggers** reference actions that must already exist. `async: true` runs
+after the transaction commits (use for anything slow); `async: false` runs
+in-transaction, so a failure rolls back the original change.
+
+**2c Jobs** run as the system user with **no current record** — the action must
+not use `[field]` syntax. Wrap a record-context action in a thin job action that
+uses `select()`/`query()` first. `timeout` is required (≤ 3600s); over 300s you
+must set `jobClass: 'long_running'`. `dforge_module_validate` flags violations.
+
+**2d Webhooks.** For authenticated endpoints, put credentials behind
+`getSecret()` and reference them as `"Authorization": "$secret:<secret_cd>"`.
+
+## Phase 3 — Views + menus (3a required), reports (optional)
+
+**3a. Default grids first.** Every entity gets a `viewType: "grid"` view with
+`dataSources: [{ entityCode, columns: [...] }]`. The scaffolder already wrote one
+per entity, so you'll often `view_modify` rather than `view_add`.
+
+View codes are semantic — the entity name (`feedback_item`), a plural
+(`invoices`), or descriptive (`invoices_kanban`). **Never use the literal code
+`default`**; `ui/folders.json`'s `viewName: "default"` is a fallback alias the
+platform resolves to the entity's first declared view.
+
+Then wire menus with `dforge_menu_add` — a section node per group, leaves
+pointing at the views.
+
+**Do not propose any specialized view until every entity has its grid.**
+
+**3b. Specialized views** only when an objective trigger fires:
+
+- the user explicitly asked for the visualization;
+- a status/stage/kind field with **3+ discrete values** → kanban;
+- a required date/time field for scheduling → calendar;
+- a self-referencing FK → tree-grid;
+- a 1:N child with `parentSetField` → list-with-levels or master-detail.
+
+If none fire, skip specialized views for that entity.
+
+**3c. Reports** only when aggregation/grouping isn't covered by views.
+
+**Exit:** every entity has a grid and a menu entry; every specialized view has a
+stated trigger.
+
+## Phase 4 — Polish (mostly optional)
+
+- **Settings** — `dforge_setting_add` per configurable value the user asked for.
+- **Translations** — run **`dforge_translation_sync`**. It generates every
+  required key from the module's own contents, never overwrites existing
+  translated text, and fills the **role labels that are completeness-enforced at
+  install**. Run it after any entity/view/role change, and always before Phase 6.
+  For a non-English locale the seeded values are English placeholders — tell the
+  user they still need real translation.
+- **Seed data** — `dforge_seed_add`, only when the module needs reference data on
+  install. Parents get a lower `order` than children.
+
+## Phase 5 — Security (5a required)
+
+1. **Inspect first.** The scaffolder pre-created `<code>.admin` with `SIUDC` on
+   every entity declared at scaffold time. It exists — don't re-create it
+   (`role_add` fails on an existing code; use `role_right_set` to amend).
+2. **Derive roles from the intake's user types and verbs.** Re-read the user-type
+   sentences in `docs/REQUIREMENTS.md`. One role per distinct user type, named
+   `<code>.<user-type>`. **Forbidden:** a generic admin/contributor/viewer matrix
+   the user didn't ask for.
+3. **Reflect the role list back** before computing rights. Get confirmation.
+4. **Show the rights matrix as a table** (rows = entities/actions/reports,
+   columns = roles, cells = rights strings), each cell explained by the verb it
+   maps to. Get sign-off.
+5. `dforge_role_add` for new roles; `dforge_role_right_set` per grant when
+   amending an existing one.
+
+Rights are **additive** — multiple roles UNION, never revoke. Entities take any
+subset of `SIUDC`; actions/reports/folders take `E`.
+
+**5b. Security folders** only if intake said data must be partitioned
+(multi-warehouse, multi-region). Default: root only.
+
+**Folder codes must be unique across the whole tree**, not just among siblings.
+A folder is addressed flat and path-less everywhere outside `ui/folders.json` —
+role rights say `folder:<code>`, translations key on `folders.<code>.label` — so
+two folders both coded `admin` under different parents are ambiguous in the
+rights matrix and collide in the translation files. `dforge_folder_add` refuses
+a duplicate and `dforge_module_validate` errors on one; name them distinctly
+(`north_admin`, `south_admin`).
+
+> ⛔ **`dforge_module_pack` refuses to build** if any entity has no role granting
+> `S`. Don't lean on the gate — derive real persona roles here, and grant `E` on
+> the actions/reports each persona uses.
+
+**Exit:** every entity appears in at least one role's rights with at least `S`;
+every folder declared has security mapped.
+
+## Backtrack protocol
+
+When a later phase exposes a problem in an earlier one, in order:
+
+1. **Stop.** Don't paper over it.
+2. **Name it precisely.** "Phase 3 wants a kanban grouped by `lead_status`, but
+   Phase 1 didn't define `lead_status` on `lead`."
+3. **Identify the target phase + decision.**
+4. **Get user sign-off**, including cascading impacts.
+5. **Apply the smallest tool that fits** — this overrides the phase labels:
+   `entity_field_add` over `entity_add`; `entity_field_rename` over remove+add;
+   `role_right_set` over `role_add`; `view_modify` over remove+add.
+6. **Re-run `dforge_module_inspect`**, fix knock-on impacts, resume.
+
+**Multi-trigger rule:** if several phases expose gaps at once, resolve the
+**earliest-phase** gap first, complete its backtrack, re-inspect, then
+re-evaluate.
+
+**Rename and delete are handled for you** — `entity_field_rename`,
+`entity_field_remove`, `entity_rename`, `entity_delete` each propagate the
+cascade in one call. **Always apply the response's `deletes` as well as
+`files`** (or just pass `apply: true`, which guarantees it). Each tool surfaces
+what it could NOT auto-fix — reports, translations, menu labels, DSL bodies,
+dangling cross-entity FKs — in `warning`. **Run `dforge_module_validate` after
+any rename/delete.**
+
+After every backtrack, append to `_brief/changelog.md`:
+
+```markdown
+## <YYYY-MM-DD> — Phase N → Phase M backtrack
+- Trigger: <what the later phase tried to do>
+- Change: <what was patched>
+- Affected files: <list>
+```
+
+## Exit
+
+When Phases 1, 3a and 5a are done (and 2/4 done or recorded as skipped):
+
+1. Record each with `dforge_module_plan({ action: "complete_phase", ... })`.
+2. **Hand off:** invoke the **`dforge-module-ship`** skill for Phase 6.

package/skills/dforge-module-design/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: dforge-module-design
+description: Phase 0 of dForge module authoring — module identity, requirements intake, the design document, and pre-scaffold validation. Use when starting a NEW dForge module, or when dforge_module_plan reports a currentPhase of 0a/0b/0c/0d. Produces CLAUDE.md, docs/REQUIREMENTS.md, docs/DESIGN.md and docs/VALIDATION.md, and ends by unlocking dforge_module_create. Do not use for building entities or views — that is dforge-module-build.
+---
+
+# dForge module — Design (Phase 0)
+
+You are designing a module **before any code exists**. The output is four
+documents. Nothing here creates entities, views, or JSON artifacts.
+
+Phase 0 is driven by the **`dforge_module_plan`** tool: call it, ask what it
+returns, write what it tells you to write. It is the source of truth for the
+question lists, the design template, the gap checks, and the gate — don't
+re-derive them from memory.
+
+> **Prerequisite:** you should have arrived here from `dforge-mcp-author` after
+> `dforge_module_plan({ action: "check", moduleDir })` reported a Phase 0
+> `currentPhase`. If you haven't made that call yet, make it now.
+
+## The loop
+
+| Sub-phase | You do | Then call |
+|---|---|---|
+| **0a** Identity | Ask the 5 returned questions, ONE at a time | `write_identity` → write the returned `CLAUDE.md` to disk |
+| **0b** Intake | Ask the returned questions in free-form prose; write `docs/REQUIREMENTS.md` to disk; get an explicit YES | `write_requirements { userConfirmed: true }` |
+| **0c** Design | Draft `docs/DESIGN.md` from the returned `designTemplate` covering all 8 `designItems`; run the gap scan; write to disk; get an explicit YES | `write_design { userConfirmed: true }` |
+| **0d** Validate | `validate` (structural) → evaluate the returned `semanticChecks` against the docs → `validate` again with `checkResults` | unlocks `readyToScaffold: true` |
+
+After every user answer: **restate what you understood and confirm** before
+moving on.
+
+## Document-write ordering (the one exception to preview-first)
+
+For `REQUIREMENTS.md` and `DESIGN.md` you **write the file to disk first**, then
+ask the user to review the file and reply YES — do not paste the full document
+into chat. Give them a short orientation instead: section headings, counts, and
+gap status ("No gaps" or a one-line list).
+
+On a change request, **edit the file directly** with targeted edits, summarize
+the change in one line, and ask again. Loop until they confirm.
+
+`userConfirmed: true` means the user actually said yes to the written file. The
+tool has no way to check that — it is on you.
+
+## 0b intake — guardrails the tool can't enforce
+
+**Free-form prose only.** Ask every 0b question as a plain sentence. Do **NOT**
+use `AskUserQuestion`, picker UIs, multiple-choice tabs, or any predefined-option
+tool. Predefined buckets bias the answer into your taxonomy and destroy the verbs
+Phase 5 needs to derive roles. Resume normal tool use in Phase 1.
+
+Forbidden picker variants that have leaked before: _"Single role / Two roles /
+Three+ roles"_; _"admin / manager / user / viewer"_.
+
+**Capture user types as verb-form sentences, never role labels.** Write each as
+`<descriptor of the person> <verb phrase>`:
+
+✅ Good:
+```
+- Anyone in the company submits purchase requests and tracks their own.
+- Department managers approve or reject pending requests for their team.
+- Buyers in procurement manage suppliers, collect quotes, and issue purchase orders.
+```
+
+❌ Bad (role-noun headings pre-commit Phase 5 to exactly those roles):
+```
+- **Requester** — submits purchase requests
+- **Approver** — approves pending requests
+```
+
+Push back on verb-less answers: "admins and users" → _"What does an admin do
+that a user can't?"_
+
+**Hard forbidden in 0b:** role codes (`<code>.admin`), role-noun bullet heads, a
+rights matrix, or a "Target user roles" section. Roles are derived from entities
+plus verbs in Phase 5 — and entities don't exist yet.
+
+### Requirements gap scan
+
+Run before writing `REQUIREMENTS.md`. Surface each finding inline as
+**"Gap:** … **Proposal:** … Confirm or change?"**
+
+- **Approval recovery** — is a reject terminal, or can it be re-submitted?
+- **Audit depth** — does the user need to record *who* changed each row, not just
+  when? Only then `audit-full`. And if such an entity is also seeded, every seed
+  record must set `created_by`/`last_updated_by: 0` (the System user) — otherwise
+  use plain `audit`.
+- **Integration codes** — the exact `module.entity` codes for anything external.
+- **Implied-but-unnamed entities.**
+- **Reference-number scale** → does it need a number sequence?
+
+## 0c design — the gap detection pass
+
+After drafting, run the gap detection the tool lists, and add a **Gaps &
+Proposals** section for each finding. **All gaps must be resolved before 0d.**
+The scan covers: FK optionality, status recovery paths, boolean-that-should-be-a-
+status, set aggregation risk, deep navigation (2+ FK hops), self-referential FKs,
+security coverage, and seed-data circular references.
+
+Two design decisions to get right here, because fixing them in Phase 1 is a
+backtrack:
+
+- **A total over child rows is a Generated column**, not a Formula. Note it as
+  such in the design. (`dforge_entity_rollup_add` enforces it later.)
+- **A field with 3+ discrete states is a status**, not a boolean — and a 3+ value
+  status is the objective trigger for a kanban view in Phase 3.
+
+## 0d validation — what it does and doesn't certify
+
+`docs/VALIDATION.md` / `readyToScaffold: true` certifies only that the **design
+documents are internally consistent**. It runs *before* scaffolding and inspects
+no entity / UI / security / DSL file.
+
+Artifact correctness is enforced by `dforge_module_validate` and by the platform
+at install. **A green VALIDATION.md is not a signal that the module will
+install.** Say so if the user reads it that way.
+
+## Exit
+
+When `validate` returns `readyToScaffold: true`:
+
+1. Write the returned `CLAUDE.md`, `docs/VALIDATION.md` and `docs/phase.json`.
+2. Tell the user Phase 0 is complete and summarize the design in two lines.
+3. **Hand off:** invoke the **`dforge-module-build`** skill to scaffold and build
+   Phases 1–5. Do not call `dforge_module_create` from this skill.

package/skills/dforge-module-ship/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: dforge-module-ship
+description: Phase 6 of dForge module authoring — the verify-and-release stage. Runs dforge_module_validate, the pre-pack self-review checklist, the version audit, then dforge_module_pack and dforge_module_install, and drives the install-fix loop until the module installs against a real tenant. Use when dforge_module_plan reports currentPhase 6, or when the user asks to validate, pack, install, deploy, or fix a failing install of an existing dForge module.
+---
+
+# dForge module — Ship (Phase 6)
+
+Phase 6 is **required and non-skippable**. Its job is to find every defect
+offline, then get a clean install against a real tenant.
+
+**Preconditions:** Phases 0a–0d, 1, 3a and 5a complete. Optional phases (2, 4,
+3b/3c, 5b) don't block — explicitly skipped ones are fine.
+
+> **The platform validator at install is the only complete validator.** Every
+> step before it exists to make that round trip succeed on the first or second
+> try, because it is slow and tenant-bound.
+
+## Step 1 — Automated validation (blocking gate)
+
+Call **`dforge_module_validate`** on the module dir. It runs offline what
+otherwise only surfaces at install:
+
+- dangling FK / reference targets; a missing hidden-FK column
+- view `dataSources`/columns pointing at unknown entities/fields; a grid over an
+  entity with no visible column
+- menu `dataViewCode` → missing view; role rights on unknown objects
+- entities with no Select grant
+- **field-spec rules re-run across every field** — catching anything that entered
+  via `module_import` / `dbml_import` / a hand edit and never passed the
+  authoring schema
+- `toString` templates whose braces don't resolve
+- **Formula-vs-Generated set aggregates**, and Generated aggregates over a
+  virtual child column
+- action `script` files missing from disk; triggers/jobs firing actions that
+  don't exist; `[field]` record-context in a job-invoked action
+- **DSL static checks** on every action body
+- **translation completeness** — a missing `roles.<code>.label` fails install
+
+Read `files["_validate.json"]`. **Every `error` must be fixed** (apply the
+backtrack protocol in `dforge-module-build`) before continuing. Review the
+`warning`s with the user. Re-run `dforge_module_validate` until `ok: true`.
+
+If `dforge_module_validate` returns a tool error or is unavailable, halt and
+tell the user: the automated gate cannot be bypassed; resolve the tooling issue
+before continuing.
+
+Structural only — it doesn't judge intent, so still do Step 2.
+
+## Step 2 — Pre-pack self-review (blocking gate)
+
+Load `dforge://reference/validation-checklist` and work every section.
+
+**Top install-blockers — scan these first.** Each is a documented real failure
+the platform validator rejects:
+
+1. **DSL dates** — `execute:` uses lowercase `now()`; never `TODAY()`/`NOW()`
+   (formula-only → `'TODAY' is not defined`). Verify with
+   `dforge_action_check({ moduleDir, actionCode })` per action.
+2. **Roll-ups** — a total over a child set is a Generated (`G`) column with
+   `SUM([set].[field])`, never a Formula (`F`), and it aggregates a **physical**
+   child column (`D` or same-row `G`). A virtual `F`/`R`/`S` child fails with
+   `column old.<field> does not exist`.
+3. **Rights keys** — actions/reports/folders take a **colon** (`action:x`);
+   entities are bare or cross-module-dotted; deny by omitting, never `""`.
+4. **Manifest** — no `translations` key; non-English locales in
+   `supportedLocales` (never `en`/`en-US`); `moduleId` a valid UUID; `version`
+   and `dbSchemaVersion` set; `security` has both `roles` and `folders`.
+5. **Column defaults** — via `formula` / `numberSequence` / DSL, never a
+   `defaultValue` key on an entity field.
+6. **Seed + traits** — a seeded `audit-full` entity sets
+   `created_by`/`last_updated_by: 0` on every record, or uses plain `audit`.
+
+Remaining checklist areas: entity traits + `toString` + the FK+Reference pattern;
+formula column shape; flags letters (`V I E M H` only); every entity has a
+default grid and `dataSources` at root with `"order"` as a string array; menu
+leaves use `dataViewCode` and bare icon names; every entity in at least one
+role's rights; action `script` values are bare filenames; seed PKs numeric with
+parents first; a `translations/<locale>.json` for every `supportedLocales` entry
+**plus** the `en-US` base, each carrying a label for every trait-provided field
+and every role.
+
+If translations are thin, run **`dforge_translation_sync`** now rather than
+hand-patching — it fills exactly the keys install requires.
+
+## Step 3 — Translation deferral check
+
+Read `_brief/changelog.md`. If a translation deferral warning is present
+("Translation files for [locales] are incomplete"), **halt**: install will fail
+completeness validation. Run `dforge_translation_sync`, confirm the non-English
+values are really translated (the tool seeds English placeholders), and clear the
+warning before proceeding.
+
+## Step 4 — Final inspect + version audit
+
+Run `dforge_module_inspect`. Show a one-line summary — entity / view / action /
+role / trigger / job counts. Then confirm both version strings with the user:
+
+- **`version`** — always bump (semver) before packing.
+- **`dbSchemaVersion`** — bump only if entity fields were added, removed, or
+  type-changed since the last install.
+
+Get explicit confirmation on both before packing. This version confirmation
+applies only to the initial pack. During the install-fix loop, re-pack without
+re-asking unless the fix changes the version strings.
+
+## Step 5 — Pack + install
+
+1. `dforge_module_pack` → the `.dforge` tarball. Blocked if any entity lacks a
+   role granting Select; fix security coverage and re-run.
+2. `dforge_module_install` with `DFORGE_URL` / `DFORGE_TOKEN`.
+
+### Install-fix loop (mandatory)
+
+1. **Call `dforge_module_install` yourself.** Never ask the user to run the
+   install command for you.
+2. If `ok: false`, read the returned `output` **in full** — it's the raw
+   CLI/server validator output and it is the input to the next fix.
+3. If it's a module defect, **fix it yourself.** Use the table below to pick the
+   phase, then apply the backtrack protocol with the smallest suitable tool.
+4. Re-run Step 1 (`validate`) until `ok: true`, then re-run only the Step 2
+   checks for the area you touched, then pack and install again.
+5. Repeat until install succeeds, or the remaining failure is clearly
+   environment/tooling.
+
+Environment/tooling failures include: 401/403 auth errors, network connectivity
+refused, server-side feature not enabled for the tenant, and CLI version
+incompatibility. All other errors are module defects.
+
+After 4 failed install attempts without progress, pause the loop, summarize all
+outstanding errors to the user, and ask how to proceed rather than continuing
+autonomously.
+
+| Install error pattern | Backtrack to |
+|---|---|
+| "unknown entity code" / "unknown view code" | Phase 1 or 3 |
+| "missing translation key" | Phase 4 (`dforge_translation_sync`) |
+| "FK constraint violation in seed data" | Phase 1 (seed load order) |
+| "role right granted on unknown object" | Phase 5 |
+| "action script not found" | Phase 2a |
+| "formula compile error" | Phase 1 (field def) or Phase 2a (DSL) |
+| "duplicate code" | wherever the duplicate was introduced |
+
+**Phase 6 sign-off exception:** when install fails with a clear module defect
+(schema validation, missing file/key, translation completeness, DSL compile
+error, dependency contract, FK/seed/import error), do **not** ask the user for
+sign-off before the corrective patch. The server has already rejected the
+package — fix the referenced files, report what changed, and immediately re-run
+validate → pack → install. Keep sign-off for product/design choices or genuinely
+ambiguous fixes.
+
+**If install fails on auth (401/403) or connectivity (refused):** that is
+credentials/connectivity, NOT a module defect. Tell the user to verify
+`DFORGE_URL` and `DFORGE_TOKEN`. **Do not backtrack** to earlier phases.
+
+**Exit criterion:** install exits 0 against a real tenant.
+
+## Step 6 — Record and close out
+
+1. `dforge_module_plan({ action: "complete_phase", moduleDir, phase: "6", note: "installed v<x.y.z>" })`.
+2. **Ask the user**: "Delete `_brief/` (session scratch), or move it to `docs/`
+   as committed design rationale?" Wait for the answer — don't act unilaterally.
+3. Suggest a `git commit` summarizing the module. **Do not commit unless the user
+   asks.**