@dforge-core/dforge-mcp 0.1.13 → 0.2.0

package/skills/dforge-mcp-author/SKILL.md

@@ -1,488 +1,164 @@
 ---
 name: dforge-mcp-author
-description: Co-pilot for authoring dForge modules via the dforge-mcp tool surface. Use when @dforge-core/dforge-mcp is connected and the user asks to scaffold, extend, pack, or install a dForge module. Drafts and proposes; the user approves at named gates. Walks the user through Phase 0 through Phase 6 with explicit gates for confirmation, a deterministic backtrack protocol, a tool-failure protocol, and resume-from-partial-state support. Phase 0 (identity → intake → design → validation) is owned by the dforge_module_plan tool — always call it first.
+description: Entry point for authoring dForge modules with the dforge-mcp tool surface. Use when @dforge-core/dforge-mcp is connected and the user asks to create, extend, fix, pack, or install a dForge module. Determines where the module currently stands and hands off to the right stage skill — dforge-module-design (Phase 0), dforge-module-build (Phases 1-5), or dforge-module-ship (Phase 6). Start here when you don't already know which stage you're in.
 ---
 
-# dForge Module Author — Co-pilot
+# dForge Module Author — router
 
-You are a co-pilot: you **draft**, **propose**, and **call tools**; the **user approves** at named gates. Tools return file maps — the user (via their client) writes files only after you've shown a preview they approved. Never write without confirmation.
+This skill routes. It does **not** contain the phase instructions — those live in
+three stage skills, each loaded only when its stage is active:
 
-## Mandatory session start — read this before anything else
-
-**Your first action in every new or resumed module session is to call `dforge_module_plan({ action: "check", moduleDir })`.** The tool reads Phase 0 progress from disk and returns: the current phase, exact questions to ask the user, and the next step. Follow its instructions.
-
-- **If the user hasn't specified `moduleDir` yet**, ask for it before calling the tool: "Where should the module directory live? (absolute path)"
-- **If the user asks to skip Phase 0** ("just scaffold it", "skip the docs", "I don't need requirements", or any equivalent): respond with — _"Phase 0 documents are required before scaffolding. They take 15–30 minutes and prevent hours of backtracking. Let me check where we are."_ — then call `dforge_module_plan({ action: "check", moduleDir })` immediately.
-- **`dforge_module_create` is gated at the tool level.** It throws if `docs/VALIDATION.md` is missing or doesn't show a clean pass. Do not attempt to bypass the gate.
-
-## Tool reference
-
-The phase column below indicates the **typical** use. During a backtrack, the backtrack protocol's "smallest tool" rule overrides this column (see "Backtrack protocol").
-
-| Tool | Typical phase | What it does |
-|---|---|---|
-| `dforge_module_plan` | 0 | **Phase 0 orchestrator — call first.** Drives Phase 0a–0d: `check` returns current state + next steps; `write_identity` (0a) writes CLAUDE.md; `write_requirements` (0b) confirms REQUIREMENTS.md (which you write to disk yourself) after user YES and ticks CLAUDE.md; `write_design` (0c) confirms DESIGN.md (which you write to disk yourself) after user YES and ticks CLAUDE.md; `validate` (0d) runs checks + writes VALIDATION.md. `readyToScaffold: true` unlocks `dforge_module_create`. |
-| `dforge_module_inspect` | any | Read current module state. **Read-only** — output does NOT require user confirmation. The one-line `summary` is for the user; the full structured state lives in `files["_inspect.json"]` (entities + their fields, views + their data sources, roles + rights matrix, actions, reports, settings, folders tree). Parse `_inspect.json` before planning patches — don't rely on summary text alone. |
-| `dforge_module_validate` | 6 (or any) | **Read-only** offline cross-reference check. Catches dangling FK/reference targets, a missing hidden-FK column, view/menu/role references to things that don't exist, and uncovered entities — errors that otherwise only surface at install. Read `files["_validate.json"]`; fix every `error` before packing. Run it as the first Phase 6 step, and after any backtrack that touched references. |
-| `dforge_module_create` | 1 | Scaffold a new module — **blocked until Phase 0d passes** (all four Phase 0 docs written + validated) |
-| `dforge_module_import` | 1 | Import a normalized **table-spec** (tables → columns → relationships) into an existing module as entities. Infers each column's `fieldTypeCd` (from explicit code / SQL type / sample values / name) and builds the FK+Reference pair per relationship. Front-end is DBML/SQL, Excel/CSV, or hand-authored. ADDS entities; review inferred types + refine views, then validate. |
-| `dforge_entity_add` | 1 | Add a whole entity to an existing module |
-| `dforge_entity_rename` | backtrack | **Refactor-safe entity rename.** Moves the file (apply the response `deletes`), cascades the identity PK `{old}_id → {new}_id`, and repoints link.entity / references / view entityCode / role keys / action entity / folder bindings / seed. Reports/translations/menus/DSL warned, not rewritten. |
-| `dforge_entity_delete` | backtrack | **Refactor-safe entity delete.** Drops the file + seed (in `deletes`), manifest entry, role key, folder binding, and view sources (deletes a view left empty). Cross-entity FKs / actions / menus warned. |
-| `dforge_entity_field_add` | 1 | Patch one field onto an existing entity |
-| `dforge_entity_field_modify` | 1 | Replace one field's spec (same name) |
-| `dforge_entity_field_rename` | 1 / backtrack | **Refactor-safe rename.** Propagates the new name to the paired Reference (`link.thisKey` + `references`), same-entity formulas, view columns + `order`, seed-data records, and other entities' FKs targeting it. Use this to rename a field — never remove+add. |
-| `dforge_entity_field_remove` | 1 / backtrack | **Refactor-safe remove.** Drops the field and cascade-cleans the paired Reference (when removing its FK), references entry, view columns + `order`, and seed keys. Formula/cross-entity dependents are warned, not auto-deleted. |
-| `dforge_action_add` | 2 | DSL action + ui/actions.json entry |
-| `dforge_trigger_add` | 2 | DB-event trigger in logic/triggers.json |
-| `dforge_job_add` | 2 | Scheduled job in logic/jobs.json |
-| `dforge_webhook_add` | 2 | Outbound webhook in logic/webhooks.json |
-| `dforge_view_add` | 3 | Data view in ui/data_views.json |
-| `dforge_view_modify` | 3 | Replace a view's spec |
-| `dforge_report_add` | 3 | Report in ui/reports.json |
-| `dforge_setting_add` | 4 | Configurable module setting |
-| `dforge_role_add` | 5 | Role with rights matrix |
-| `dforge_role_right_set` | 5 | Grant / revoke one right on one object |
-| `dforge_folder_add` | 5 | Security folder (optional) |
-| `dforge_dependency_add` | any | Add a dep on another module |
-| `dforge_module_pack` | 6 | Produce .dforge tarball via bundled dforge-cli, PATH fallback, or `DFORGE_CLI_BINARY` |
-| `dforge_module_install` | 6 | Install to tenant — the real validator; returns raw CLI output for the install-fix loop |
-
-**Phase 0 (0a–0d) is owned by `dforge_module_plan`.** Call `dforge_module_plan({ action: "check", moduleDir })` to start or resume Phase 0. The tool returns the current state and exact next steps. Do not call `dforge_module_create` until the tool reports `readyToScaffold: true` — the tool enforces this gate programmatically.
-
-## Loading policy — lazy, reference-first
-
-**Load nothing up front beyond this skill.** There is no session-start resource load. Pull material only at the step that needs it, and only what that step requires — this is what keeps a full scaffold inside one context window.
-
-- **References and examples are MCP resources — load them by URI, not by filesystem path.** Each per-element reference is `dforge://reference/<name>` and each example file is `dforge://example/<path>` (e.g. `dforge://reference/flags`, `dforge://example/entities/todo_item.json`). These resolve from the server regardless of your working directory — do NOT try to `Read` a `references/*.md` path off disk; your CWD is the module dir, not the skill dir, so that path won't exist. Use the resource.
-- **One reference per step.** The `dforge://reference/<name>` in the table below is your primary source — it carries the schema shape, a worked example, and the common-mistakes list. Load it (plus the `dforge://example/...` file in the same row) before authoring that element type, and re-load it on every backtrack into that type. The example files are mandatory structure validators; never work from memory for schema shapes, flags, or column-type patterns.
-- **Schemas are fallback, not default.** Load a `dforge://schema/*` (or `dforge://docs/dsl`) resource only when the **Also load** column names one, or when a reference explicitly points you to its schema for a shape it doesn't fully specify.
-- **`dforge://docs/conventions` is not loaded by default** — per-element references cover the same ground. Load it only for cross-module **extension / bridge** work (its §1b is the one topic with no dedicated reference).
-- **Halt per load.** If a reference or schema you actually need fails to load, stop and notify the user — do not invent conventions or schemas from memory.
-
-| When you need to… | Load (primary reference + example) | Also load (schema / doc) |
+| Stage skill | Phases | What it owns |
 |---|---|---|
-| Add any field | `dforge://reference/field-types`, `dforge://reference/flags`, `dforge://example/entities/todo_item.json` | — |
-| Add a Reference or Set column | `dforge://reference/column-types` (FK+Reference pattern), `dforge://example/entities/todo_item.json` | — |
-| Reuse a field 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 data view (grid / list) | `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 a specialized view (kanban / calendar / tree-grid / master-detail) | `dforge://reference/data-views` | `dforge://schema/data-views` (viewConfig shape) |
-| Add a menu | `dforge://reference/menus`, `dforge://example/ui/menus.json` | — |
-| Add an action (DSL body + `ui/actions.json` registration) | `dforge://reference/action-dsl` (grammar + §"Registering the action"), `dforge://example/logic/actions/mark_done.dsl`, `dforge://example/ui/actions.json` | `dforge://docs/dsl` (full grammar + built-ins) |
-| Add a trigger (DB-event → action) | — (no dedicated reference) | `dforge://schema/triggers`; trigger-condition syntax in `dforge://docs/dsl` |
-| Add a scheduled job | `dforge://reference/jobs` | `dforge://schema/jobs` |
-| Add a webhook (outbound HTTP) | — (no dedicated reference) | `dforge://schema/webhooks` |
-| Add filters (views, folders, reports) | `dforge://reference/filters` | — |
-| Add security roles or 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 (`ocrExtract` / `detectDocument`) | `dforge://reference/document-extraction` | `dforge://docs/dsl` (built-ins) |
-| Localize dropdown options / a column domain | `dforge://reference/translations` (§Dropdown option labels / §Column domain labels) | — |
-| Add translations | `dforge://reference/translations` | — |
-| Add a number sequence | `dforge://reference/number-sequences` | — |
-| Add module settings | `dforge://reference/settings` | — |
-| Add pre-built saved queries | `dforge://reference/queries` | — |
-| Import from DBML/SQL | `dforge://reference/schema-import` | — |
-| Migrate from a legacy database | `dforge://reference/data-migration` | — |
-| Final pre-pack validation | `dforge://reference/validation-checklist` | — |
-
-## Hard rules
-
-These are absolute. When a phase instruction appears to conflict, the hard rule wins unless the phase explicitly names itself as an exception.
-
-1. **Co-pilot stance.** Draft → propose → user approves → write-tool call → file write. Never write without confirmation. Read-only tools do not need a confirmation gate.
-2. **Inspect before patching.** Run `dforge_module_inspect` at session start and after every backtrack. Inspect output is read-only; show a summary and continue without asking confirmation for the inspect itself.
-3. **One thing at a time when interacting with the user.** Applies to:
-   - **Questions.** Ask ONE question per turn, never batch multiple questions in one message. Each subsequent question is informed by prior answers. The only exception is when the user has explicitly said "give me defaults" or "pick reasonable defaults" — then you can announce a set of defaults in one block and ask "any to override?".
-   - **Entities / views / roles / actions / reports.** Propose ONE per turn. Never batch these. The only exception is the Phase 1 field-batching rule, and it applies only to multiple fields inside one already-approved entity. It never justifies batching multiple entities, views, roles, actions, or reports.
-4. **Validate-and-reflect every step.** After every user answer, BEFORE moving to the next question or tool call: restate what you understood in your own words and ask "Right?" or "Does that capture it?". Only proceed once the user confirms. If they correct, repeat the restate-and-confirm loop until aligned. **Goal: zero ambiguity going into the next step.** If you have questions, ask and wait for answers — never proceed with unanswered ones in your head.
-5. **Tabs in JSON, trailing newline** — tools already emit this; don't reformat.
-6. **Don't invent fields, codes, roles, or relationships** — they come from the user's domain. If the user said "we have submitters and admins", roles are derived from that; do NOT default to a fixed "admin/contributor/viewer" taxonomy or any other generic set the user didn't ask for.
-7. **A step is "done" only when its file is written AND reviewed.** Never mark a phase or step complete — in your todo list, a status update, or your own narration — until (a) its document has actually been written to disk, and (b) for the Phase 0 documents, the user has seen and approved it. Deciding what you *would* write is not "done". Do not advance to the next phase on the strength of an intention; advance only after the file is written and the gate (review/approval) cleared.
-8. **Load before authoring.** Load the matching `dforge://reference/<name>` + `dforge://example/<path>` resources (per the Loading policy table) before scaffolding or modifying any element — fields, views, menus, actions, roles, jobs, etc. — including inside backtracks. They're MCP resources (load by URI, not by disk path). The example files are mandatory structure validators; never work from memory for schema shapes, flags, or column-type patterns.
-
-## Core rules (violations produce invalid modules)
-
-Always-on cheat-sheet — enough to author inline; load the linked `references/*.md` for full detail:
-
-- **Naming.** `code`, entity `dbObject` keys, column keys all `snake_case`, case-sensitive, entities singular (`opportunity_line`). `code` = DB schema name.
-- **FK + Reference = two columns** (the #1 source of broken modules): hidden FK (`flags: "EM"`, `dbDatatype` = target PK type, no `fieldTypeCd`) **plus** visible Reference (`columnType: "R"`, `fieldTypeCd: "lookup"`, `flags: "VEM"`, `link: {entity, thisKey, otherKey}`), plus the FK in `references`. Never one column that is both. → `column-types.md`
-- **Flags** = letters from `V I E M H` only (no `U`/`S`/`P`): `VEM` required+visible, `VE` optional+visible, `V` read-only, `EM` hidden FK, `I` trait-provided. → `flags.md`
-- **Field types:** `fieldTypeCd` = UI control, `dbDatatype` = SQL type. **Omit `dbDatatype` on plain data columns — it's derived from `fieldTypeCd`** (`currency` → `numeric(18,2)`, `text` → `varchar`). Only set it for a **hidden FK** (no `fieldTypeCd`, so use the target PK type `cuid`) or to override size/precision. When you do set it: never the same as `fieldTypeCd`, and never `"number"` (use `int`/`bigint`/`numeric`). Common `fieldTypeCd` fixes: `number` not `integer`/`float`, `phone` not `phoneNumber`, `date` not `datePicker`. Common `dbDatatype` fixes: `timestamptz` not `datetime`/`timestamp`, `bool` not `boolean`, `varchar`/`text` not `string`. (Invalid `fieldTypeCd`/`columnType` are now rejected at authoring time.) → `field-types.md`
-- **Formula columns** (`columnType: "F"`): `baseDatatypeCd` required, no `dbDatatype`, `flags: "V"`. → `formulas.md`
-- **Roll-up totals** over a child set → Generated `G` column with `SUM([set].[field])` (`dbDatatype` + `formula`, no `link`/`baseDatatypeCd`); the installer maintains it with a DB trigger. **Not** a Formula `F` — an `F` set-aggregate is unsupported and silently renders empty. Aggregate only a **physical** child column (`D` or same-row `G`); a virtual `F`/`R`/`S` child fails install (`column old.<field> does not exist`). → `column-types.md`
-- **Column defaults:** entity *data* columns have **no** `defaultValue`/`default` key. Set a default via a formula (`"formula": "TODAY()"`, `"formula": "'draft'"`) or in action/trigger logic. `defaultValue` is **settings-only**. → `field-types.md`
-- **Traits:** default `["identity", "audit"]`; `audit-full` (when the user needs *who*-tracking) adds required `created_by`/`last_updated_by` with no default — if such an entity is **seeded**, set both to the System user `0` in every record, or don't seed it. → `traits.md`
-- **`toString`:** every entity needs one, `{column}` braces, e.g. `"{first_name} {last_name}"`.
-- **Data views:** `dataSources` array at root — never root-level `entityCode` + `columns`. → `data-views.md`
-- **Menus:** leaf items use `dataViewCode` (not `viewCode`); section nodes omit `itemType`; icons are Bootstrap names sans `bi-`. → `menus.md`
-- **Security roles:** `rights` (not `entityRights`); entities `SIUDC`, actions/reports/folders `E`. Rights keys: same-module entity bare (`product`), cross-module entity dotted (`fin.invoice`), and actions/reports/folders use a **colon** prefix — `action:approve`, `report:summary`, `folder:east` (never a dot). Omit a key to deny; never map to `""`. `roles.json` carries `description` (English fallback) + `rights` only — **no `label`**; the localized role display name lives in the translation files as `roles.<code>.label` and is completeness-enforced. → `security.md`, `translations.md`
-- **Action script** in `ui/actions.json` = bare filename (no path, no `.dsl`).
-- **Action DSL dates:** inside `execute:` use lowercase `now()`; `TODAY()`/`NOW()` are formula-only (`canExecute:`/formula columns) and are **undefined in `execute:`**. → `action-dsl.md`
-- **SQL placeholders** = `@paramName` (not `:paramName`).
-- **Manifest:** non-English locales go in `supportedLocales` (array of `ll-CC` tags; never `en`/`en-US`) — there is no `translations` manifest key; files are auto-discovered at `translations/<locale>.json`. `security` has both `roles` and `folders`. → `manifest.md`
-- **Seed data:** explicit numeric PKs (`cuid` is `int8`, not a UUID); parents before children via numeric prefix (`01-`, `02-`).
-
-## Tool failure protocol
-
-If any MCP tool returns an error at any time:
-
-1. **Surface the raw error verbatim** to the user. Do not paraphrase.
-2. **Classify the error before asking the user for help.** If the raw output names a module/package defect, fix the module yourself using the smallest appropriate tool or direct file edit allowed by the host agent, then re-run the required validation loop. Do not ask the user to paste the error back to you — it is already in the tool result.
-3. **Ask the user to resolve only environment/tooling issues** you cannot fix from module files: missing CLI, missing/expired credentials, unreachable tenant/API, permissions, or a bad module path outside the workspace.
-4. **Do not advance the phase** until the failing tool succeeds.
-
-Two specific tool errors have known causes worth distinguishing:
-
-- **`dforge_module_pack` / `_install` reports "command not found" or PATH error**: dforge-cli isn't installed. Tell the user: "dforge-cli is not on your PATH. Install with `npm install -g @dforge-core/dforge-cli`, then re-run. Do not continue Phase 6 until resolved."
-- **`dforge_module_install` reports HTTP 401/403 or connection refused**: this is auth/connectivity, NOT a module defect. Tell the user: "This appears to be a credentials or connectivity issue, not a module defect. Verify `DFORGE_URL` and `DFORGE_TOKEN` before re-running install." Do not backtrack to earlier phases.
-- **`dforge_module_install` returns `ok: false` with validation/import/compile/schema output**: this is a module defect. Treat `output` as the source of truth, fix the referenced files, and run Phase 6 again from automated validation. Keep repeating until install succeeds or the remaining error is clearly environment/tooling.
-
-## Resume-from-partial-state
-
-At every session start, **inspect** the module: call `dforge_module_inspect` on the module dir (if the user has specified one). Loading is otherwise lazy (see Loading policy) — do **not** bulk-load resources or schemas up front.
-
-Phase 0 progress is tracked by **which artifact files exist on disk**. Call `dforge_module_plan({ action: "check", moduleDir })` — it reads the state and returns exactly what to do next.
-
-- If the dir doesn't exist or has no `manifest.json`: `dforge_module_plan check` returns the current Phase 0 state and next step.
-- If the dir does exist (manifest found):
-  1. Read `_brief/changelog.md` if present.
-  2. Call `dforge_module_inspect` to get entity/view/role inventory.
-  3. Cross-reference entities/views/roles to infer last completed phase.
-  4. Summarize: "Found module `<code>` v`<version>`. Looks like Phase N was the last completed phase. Resume from Phase N+1, or revisit an earlier phase?"
-  5. Wait for the user's answer before proceeding.
-
-## Phase 0 — owned by `dforge_module_plan`
-
-Phase 0 (0a identity → 0b intake → 0c design → 0d validation) is driven entirely by the tool. **Call `dforge_module_plan({ action: "check", moduleDir })` and follow the fields it returns** — `questions` (ask ONE at a time), `designItems`, `designTemplate`, `gapDetection`, `semanticChecks`, and `nextStep`/`writeAction`. The tool is the source of truth for those lists; don't re-derive or re-enumerate them here. After every user answer, apply the validate-and-reflect rule (hard rule #4).
-
-The loop the tool walks you through:
-
-| 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 (free-form prose — see guardrails below); write `docs/REQUIREMENTS.md` to disk; get explicit YES | `write_requirements { userConfirmed: true }` |
-| 0c Design | draft `docs/DESIGN.md` from the returned `designTemplate`, covering the 8 `designItems`; run the gap detection the tool lists; write to disk; get explicit YES | `write_design { userConfirmed: true }` |
-| 0d Validate | `validate` (structural) → evaluate the returned `semanticChecks` against the docs (read them from disk) → `validate` again with `checkResults` | unlocks `readyToScaffold: true` |
-
-**Document-write ordering (exception to hard rule #1):** for REQUIREMENTS.md and DESIGN.md you write the file to disk *first*, then ask the user to review it and reply YES — do not paste the full document into chat. On change requests, edit the file directly (targeted edits) and re-ask until confirmed. `dforge_module_create` stays gated at the tool level until `readyToScaffold: true`.
-
-> **What Phase 0d validates — and what it doesn't.** `docs/VALIDATION.md` / `readyToScaffold: true` certifies only that the **design documents** are internally consistent. It runs *before* scaffolding and does **not** inspect any generated entity / UI / security / DSL file. Artifact correctness is enforced by the **platform at install (Phase 6)** — a green VALIDATION.md is not a signal that the module will install. The Phase 6 automated validation + pre-pack self-review (Steps 1–2) are your real safeguard.
-
-### 0b intake — guardrails the tool can't enforce
-
-**Free-form prose only — no pickers.** 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 lose the verbs Phase 5 needs. 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 bias Phase 5 toward 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 + verbs in Phase 5, and entities don't exist yet.
-
-**Requirements gap scan** (run before writing REQUIREMENTS.md; surface inline as "**Gap:** … **Proposal:** … Confirm or change?"): approval recovery (is reject terminal or re-submittable?); audit depth (does the user need to record *who* changed each row, not just when? only then `audit-full`; if that entity is also seeded, each seed record must set `created_by`/`last_updated_by: 0`, the System user — otherwise `audit`); exact `module.entity` codes for any integration; implied-but-unnamed entities; reference-number scale → sequence pattern.
-
-## Phase 1 — Domain (required)
-
-> **Fast on-ramp — importing from an existing schema or spreadsheet.** When the user already has the data model in a **DBML** diagram or a **spreadsheet** (Excel/CSV), use the import core instead of authoring entities one field at a time:
-> - **DBML/SQL** → `dforge_dbml_import` (deterministic parser). Pass the DBML text and, for a brand-new module, `module: { code, displayName }`.
-> - **Spreadsheet (.xlsx/.csv)** → load `dforge://reference/excel-import` and follow it: a binary `.xlsx` can't be read directly, so first **decode it** with the bundled stdlib Python extractor (`dforge://script/xlsx-to-model` → write to a temp file → `python3 tmp.py file.xlsx`), which prints `{sheets:[{name,headers,rows}]}`. Then turn that model into a table-spec — each sheet → one table, headers → columns, rows → `sampleValues`, `<thing>_id` columns → `references` — and call `dforge_module_import({ moduleDir, tables, module? })`. (A `.csv` is plain text: read it directly, no extractor.)
-> Both infer `fieldTypeCd` from the metadata registry and build the FK+Reference pair. **Always show the proposed table-spec / entity inventory to the user for sign-off first** (same gate as below), then **run `dforge_module_validate`** and refine the generated default grids. Import ADDS entities into an existing or greenfield module; it does not replace Phase 0 for a from-scratch design the user wants to think through.
-
-**Preconditions:** Phases 0a through 0d complete — `CLAUDE.md` written; `docs/REQUIREMENTS.md` confirmed; `docs/DESIGN.md` confirmed; `docs/VALIDATION.md` shows a clean pass with no open findings.
-
-> ⛔ **GATE — `dforge_module_create` is blocked at the tool level.** It throws if any of the four Phase 0 docs are missing or if `docs/VALIDATION.md` doesn't contain `readyToScaffold: true`. If you hit the gate error, call `dforge_module_plan({ action: "check", moduleDir })` to see what's needed.
-
-**This phase's FIRST deliverable — before any tool call — is the proposed entity inventory.** Show it. Get explicit sign-off. Then scaffold. The user needs to see "the module will have these N things in it" before files exist, because entities are the spine the rest of the module hangs from (views, actions, roles all reference entity codes).
-
-**Pre-scaffold validation** — before calling `dforge_module_create`, run these five consistency checks against `docs/DESIGN.md`. If any fail, surface the issue to the user and return to Phase 0c to fix it — do not silently adjust the design:
-
-1. Every FK in the relationship map has a corresponding field listed for the child entity.
-2. Every action's `canExecute` guard references a status value that exists in that entity's options list.
-3. Every seed record's FK references a parent entity that also has seed data (referential integrity in load order).
-4. Every formula column uses only fields that exist on the same entity or a directly referenced entity (exactly 1 FK hop). Transitive references (2+ hops) are async and must have been flagged in the Phase 0c gap scan.
-5. Any set aggregate (`SUM`/`COUNT`/`AVG`/`MIN`/`MAX` over `[set].[field]`) is a Generated (`G`) column — never a Formula (`F`) column (an `F` set-aggregate silently renders empty) — and aggregates only a **physical** child column (`D` or same-row `G`), never a virtual `F`/`R`/`S` child.
-6. Every seeded entity handles audit traits: if it uses `audit-full`, every seed record sets `created_by`/`last_updated_by` to the System user `0` (else use `audit` / don't seed it) — `audit-full`'s required user columns otherwise fail seed install.
-
-Once all checks pass, present a brief summary (entity count, action count) and ask for final confirmation before calling `dforge_module_create`.
-
-**Sub-steps:**
-
-1. **Propose the entity inventory.** Re-read `_brief/00-intake.md`'s purpose and user-verbs sections. Derive an entity list: each meaningful "thing the user verbs against" tends to become an entity. Present as:
-   ```
-   Proposed entities (N):
-   - <entity_code> — <one-line description, ties to a verb / use case from intake>
-   - ...
-   ```
-   Apply the validate-and-reflect rule: "Here's what I think the module needs. Right shape and scope? Add / remove / merge?" Loop with the user until they explicitly approve the list.
-
-   Write the approved inventory to `_brief/01-domain.md`.
-
-2. **Scaffold the module** via `dforge_module_create` using the approved inventory. Preview the file map, get approval, then user writes.
-
-3. **Per-entity loop.** For each entity in order, propose fields + traits + references. **Then call `dforge_entity_field_add` with the field batching rule below**, one entity at a time, requesting user approval per entity before moving on.
-
-4. **Extension entities last.** If extending another module's entity, use `extends: "module.entity"`, `toString: null` (inherits base), and a dotted manifest key. **Snapshot the base entity's current fields via `dforge_module_inspect` on the dependency dir** (when available) so you know what's inherited; if the dependency dir is not locally available, document the known base fields from `docs/DESIGN.md` and note in `_brief/changelog.md` that base-entity field drift is the user's responsibility to track.
-
-**Before the first field of each entity** (and again whenever the element type changes), load the matching rows from the Loading policy table — fields, reference/set columns, formula columns, traits, number sequences. Do not call `dforge_entity_field_add` for a type without having read its reference + example first.
-
-**Field batching rule** (the only Phase-1 exception to the hard rule):
-
-A field is **batchable** only if ALL of these are true: scalar primitive (string / integer / decimal / boolean / date), no FK or Reference, no `formula`, and the nullability is unambiguous (e.g. required-not-null per intake context). Anything else — refs, formulas, nullable ambiguity, file/lookup/JSON types — is non-batchable and goes one at a time.
-
-**Exit criteria:** every entity has at least PK + audit traits + 1 user-visible field; FK references resolve; manifest's `entities` map reflects reality.
-
-## Phase 2 — Behavior (optional sub-steps)
-
-**Preconditions:** Phase 1 complete.
-
-Phase 2 covers four kinds of behavior — all optional, all individually skip-able. Each fires action logic, but the **trigger** differs:
-
-| Sub-step | Fires when | File | Tool | Use when |
-|---|---|---|---|---|
-| 2a Actions | user clicks a button | `ui/actions.json` + `logic/actions/*.dsl` | `dforge_action_add` | bulk operations, business workflows, anything that needs user input via params |
-| 2b Triggers | DB event happens (insert/update/delete/status_change) | `logic/triggers.json` | `dforge_trigger_add` | reactive automation: "when X happens, do Y" without user action |
-| 2c Scheduled jobs | cron timer | `logic/jobs.json` | `dforge_job_add` | periodic work: nightly cleanup, daily summary, hourly poll |
-| 2d Webhooks | DB event happens → POSTs to external URL | `logic/webhooks.json` | `dforge_webhook_add` | integrations: Slack notifications, Zapier, external dashboards, audit log shipping |
-
-Skip a sub-step entirely if the user has no need for it. Do NOT fabricate behavior to fill a sub-step. Phase 2 can be completely skipped for pure CRUD modules.
-
-### 2a. Actions — user-triggered
-
-**Before authoring any action, load the full "action" row from the Loading policy table** — `dforge://reference/action-dsl`, `dforge://example/logic/actions/mark_done.dsl`, `dforge://example/ui/actions.json`, AND `dforge://docs/dsl`. All four are required: the wrong-field-access / wrong-batch-flag / wrong-or-missing `ui/actions.json`-property mistakes only surface when you cross-check them. (`dforge://docs/conventions` does not cover the DSL grammar.)
-
-Call `dforge_action_add` per action — one at a time — with the full DSL body. Confirm with the user before each call.
-
-### 2b. Triggers — DB-event-driven
-
-Load the "trigger" row from the Loading policy table (`dforge://schema/triggers`). Trigger conditions use the same single-line `[field] op value` syntax as `canExecute:` — see `dforge://docs/dsl`.
-
-For each trigger, propose: entity + event + (optional) condition formula + target action + async flag. Use `dforge_trigger_add`. Triggers reference EXISTING actions — make sure the target action was added in Phase 2a before creating any trigger that references it.
-
-**Async vs sync:** `async: true` runs the action in the background after the triggering transaction commits — recommended for slow actions (emails, external API calls). `async: false` runs in the same transaction; action failure rolls back the original DB change.
-
-### 2c. Scheduled jobs — cron-driven
-
-Load the "scheduled job" row from the Loading policy table (`dforge://reference/jobs` + `dforge://schema/jobs`).
-
-Constraints baked into the tool:
-- Action MUST NOT use record-context (`[field]`) syntax — jobs run as system user with NO current record. Wrap any record-context action in a thin job-friendly action that uses `select()` (or `query()`) to fetch the records it needs.
-- `timeout` is required, ≤ 3600s.
-- If `timeout > 300`, you MUST set `jobClass: 'long_running'`.
-
-Use `dforge_job_add` per job.
-
-### 2d. Webhooks — outbound HTTP
-
-Load the "webhook" row from the Loading policy table (`dforge://schema/webhooks`).
-
-For each webhook: entity + event + endpoint URL + (optional) condition + (optional) payload shape (include/exclude/includeOld). Use `dforge_webhook_add`.
-
-For authenticated endpoints: put bearer tokens / API keys behind `getSecret()` (configure secret in module's secrets), reference in headers as `"Authorization": "$secret:<secret_cd>"` — the platform resolves at fire time.
-
-**Exit criteria for Phase 2:** every action / trigger / job / webhook you added is intended (user-requested, not fabricated to fill space) and references existing entities + actions. Compilation is validated at install in Phase 6.
-
-## Phase 3 — Views (required) + Reports (optional)
-
-**Preconditions:** Phase 1 complete.
-
-**Before the first element of each type**, load the matching rows from the Loading policy table — data views, menus, filters, reports. Do not call `dforge_view_add`, `dforge_view_modify`, or `dforge_report_add` without having read its reference + example first.
-
-### 3a. Default grids (required, do FIRST)
-
-For every entity in the manifest, call `dforge_view_add` with `viewType: "grid"` and `dataSources: [{ entityCode: <entity>, columns: [...] }]`.
-
-**View naming.** View codes in `ui/data_views.json` are semantic — convention is the entity name (`feedback_item`), the plural (`invoices`), or descriptive (`invoices_kanban`, `feedback_by_status`). Do NOT use the literal code `default`. When `ui/folders.json` entities reference `viewName: "default"`, the platform resolves that to the entity's first view declared in `data_views.json` — it's a fallback alias, not a required view code. (The scaffolder already wrote a default grid keyed by entity code in Phase 1, so often you'll `view_modify` it rather than `view_add`.)
-
-**Do not propose any specialized view until every entity has its default grid.**
-
-### 3b. Specialized views (optional, only after 3a complete)
-
-Propose a specialized view (kanban / calendar / list-with-levels / tree-grid / master-detail) **only when one of these objective triggers fires**:
-
-- The user explicitly mentioned the visualization ("show leads as a kanban", "we need a calendar for tasks").
-- The entity has a status / stage / kind field with **3 or more discrete values** in a dropdown — kanban candidate.
-- The entity has a required date/time field intended for scheduling — calendar candidate.
-- The entity self-references (parent FK to itself) — tree-grid candidate.
-- The entity has a 1:N detail child with `parentSetField` declared — list-with-levels or master-detail candidate.
-
-If none of these fire, skip specialized views for that entity. Load the specialized-view row from the Loading policy table (`dforge://schema/data-views` for the `viewConfig` shape) before calling `dforge_view_add`.
-
-### 3c. Reports (optional)
-
-Add reports only when management aggregation/grouping isn't covered by views. `dforge_report_add` with layout + datasets (Query type with entityCd + filter + sort, or Stored Procedure). Load the report row from the Loading policy table (`dforge://schema/reports`) first.
-
-**Exit criteria:** every entity has a default grid; every specialized view has a stated trigger; reports cover the stated reporting use cases.
-
-## Phase 4 — Polish: settings, translations, seed (mostly optional)
-
-**Preconditions:** Phase 3 complete.
-
-**Before the first element of each type**, load the matching rows from the Loading policy table — settings, translations, number sequences (seed data), print templates, saved queries.
-
-- **Settings**: `dforge_setting_add` per configurable value the user requested.
-- **Translations** (required if intake declared non-English locales): files under `translations/<locale>.json`. **If the user defers translation authoring, append to `_brief/changelog.md`: "Translation files for [locales] are incomplete. Phase 6 install will fail translation completeness validation until added." Remind the user before calling `dforge_module_pack`.**
-- **Seed data**: only when the module needs reference data on install.
-
-**Exit criteria:** any configurable value the user requested is exposed as a setting; if non-English locales were declared, translations exist OR the deferral warning is logged.
-
-## Phase 5 — Security
-
-**Preconditions:** Phases 1 and 3a complete (you need entity codes and default grid views to grant rights on; actions and reports added in Phases 2 and 3b/3c can be granted as they are added).
-
-### 5a. Roles + rights matrix (required)
-
-**Before any role or folder work**, load the "security roles or folders" row from the Loading policy table (`dforge://reference/security` + `dforge://example/security/roles.json`; `dforge://reference/filters` for folder row filters). Do not call `dforge_role_add`, `dforge_role_right_set`, or `dforge_folder_add` without having read it.
-
-1. **Inspect first.** Run `dforge_module_inspect` and read the `roles` array. The scaffolder pre-creates `<code>.admin` with `SIUDC` on every entity declared at scaffold time. That role exists already — don't try to re-create it.
-2. **Derive role inventory FROM the intake's user types and verbs — never default to a fixed taxonomy.** Re-read `_brief/00-intake.md`'s `User types` section. For each distinct user type, propose ONE role named `<code>.<user-type>` (e.g. intake said "any signed-in user submits + admins triage" → `<code>.user` (covers the "submits" verb) + the existing scaffolded `<code>.admin` (covers triage). If intake mentioned "approvers" or "auditors" or "managers" or any other group, derive roles for those too.) **Forbidden:** spinning up a generic `admin/contributor/viewer` matrix when the user didn't ask for it. The rights set should map to the verbs each user type does, not to a textbook role hierarchy.
-3. Reflect the proposed role list back to the user before computing rights: "Based on intake, I see these user types → these roles: `<list>`. Right?" Get explicit confirmation. If the user clarifies / adds / removes, re-list and re-confirm.
-4. Show the rights matrix as a table (rows = entities/actions/reports, columns = the confirmed roles, cells = rights string). Each cell explained by the verb-to-right mapping you derived. Get user sign-off on the matrix.
-5. **For new roles**: call `dforge_role_add`. **For amending existing roles** (the scaffolded admin, or grants on actions/reports added in Phases 2-3 that aren't yet in any role): call `dforge_role_right_set` per grant — it's the smallest tool and doesn't conflict with the scaffolded admin role. Calling `dforge_role_add` against an existing role code fails — use `role_right_set` to amend instead.
-
-**Rights semantics** (additive — multiple roles UNION, never revoke):
-- Entities: any subset of `SIUDC` (Select / Insert / Update / Delete / Clone)
-- Actions / reports: `E` (Execute), or omit to deny
-- **Object key format:** same-module entity bare (`product`); cross-module entity dotted (`fin.invoice`); action/report/folder use a **colon** prefix (`action:approve`, `report:summary`, `folder:east`). A dot before an action/report/folder code is rejected as an unknown object.
-
-### 5b. Security folders (optional)
-
-Only if intake said data must be partitioned per folder (multi-warehouse, multi-region, multi-tenant-like). Default: root only.
-
-If needed: `dforge_folder_add` per sub-folder, passing `entities` with `rowFilter` (SQL string OR canonical `{c,o,v}` / `{g,i:[]}` filter).
-
-**Exit criteria:** run `dforge_module_inspect` and verify every entity code in the manifest appears in at least one role's rights map with at least `S` (Select); list any uncovered entity as a gap before advancing to Phase 6. If folders were declared, every folder has security mapped.
-
-> ⛔ **GATE — `dforge_module_pack` enforces entity coverage.** Pack refuses to build the tarball if any entity has no role granting `S`, and it warns about actions/reports with no `E` grant. The platform installs a security-less module without complaint (it just becomes inaccessible), so this is the only place it's caught. **Don't lean on the gate** — derive real persona roles from the intake user types here (not just the scaffolded `<code>.admin`), and grant `E` on the actions/reports each persona uses.
-
-## Phase 6 — Verify (required, non-skippable)
-
-**Preconditions:** all required phases complete: 0a, 0b, 0c, 0d, 1, 3a, 5a. Optional phases (2, 3b/3c, 4, 5b) are not preconditions — explicitly skipped optional phases do not block Phase 6.
-
-**Steps:**
-
-### Step 1 — Automated validation (blocking gate)
-
-Call **`dforge_module_validate`** on the module dir first. It runs the cross-reference checks offline (dangling FK/reference targets, a missing hidden-FK column, view columns / menu dataViewCodes / role rights pointing at things that don't exist, entities with no Select grant) — the errors that otherwise only surface at install. Read `files["_validate.json"]`: **every `error` must be fixed** (apply the backtrack protocol) before continuing; review `warning`s with the user. Re-run until `ok: true`. This is faster and more reliable than eyeballing — but it is structural only; it does not judge intent, so still do Step 2.
-
-### Step 2 — Pre-pack self-review (blocking gate)
-
-Load `dforge://reference/validation-checklist`. Run through **every section** in order. Surface each failure to the user and apply the backtrack protocol before proceeding. Do not advance to packing until all checks pass.
-
-**Top install-blockers — scan these first** (each is a documented real install failure the platform validator rejects):
-
-1. **DSL dates:** `execute:` blocks use lowercase `now()`; never `TODAY()`/`NOW()` (formula-only → `'TODAY' is not defined`).
-2. **Roll-ups:** a total over a child set is a Generated (`G`) column with `SUM([set].[field])` (`dbDatatype` + `formula`) — never a Formula (`F`) column (an `F` set-aggregate silently renders empty). Aggregate only a **physical** child column (`D` or same-row `G`); a virtual `F`/`R`/`S` child fails install (→ `db_error: column old.<field> does not exist`).
-3. **Rights keys:** actions/reports/folders use a **colon** (`action:x`, `report:x`, `folder:x`); entities are bare or cross-module-dotted; deny by omitting the key, never `""`.
-4. **Manifest:** no `translations` key (translation files auto-discovered; non-English locales → `supportedLocales`).
-5. **Column defaults:** set via `formula` / `numberSequence` / DSL — never a `defaultValue` key on an entity field.
-6. **Seed + traits:** seeded `audit-full` entities set `created_by`/`last_updated_by: 0` (System user) in every record — otherwise use `audit` or don't seed (`required column 'created_by' … is not present in seed records`).
-
-Key areas (full checklist):
-
-- **Manifest**: `moduleId` is a valid UUID; `version` and `dbSchemaVersion` are set; `supportedLocales` lists every non-English locale that has a `translations/<locale>.json` file (and `en`/`en-US` is NOT listed); `security` block has both `roles` and `folders`.
-- **Entities**: every entity has `identity` + `audit` traits, a `toString` template, and the FK+Reference pattern applied wherever a relation exists (hidden FK column `flags: "EM"` + visible Reference column `columnType: "R"` + entry in `references` block).
-- **Formula columns** (`columnType: "F"`): have `baseDatatypeCd`, no `dbDatatype`, `flags: "V"`.
-- **Flags**: only `V`, `I`, `E`, `M`, `H` used — no `U`, `S`, or `P`.
-- **Data views**: every entity has a default grid; `dataSources` array present at root; sort uses `"order": ["-col", "col"]` string-array (never `"sort": [{column_cd, direction}]`).
-- **Menus**: leaf items have `dataViewCode` (not `viewCode`); icons are Bootstrap names without the `bi-` prefix; section nodes omit `itemType`.
-- **Security**: every entity code in the manifest appears in at least one role's rights map; `rights` key used (not `entityRights`); entity rights use `SIUDC` letters; actions/reports use `E`.
-- **Actions**: every `script` value in `ui/actions.json` is a bare filename (no path, no `.dsl` extension); every action referenced by a trigger or job exists in `ui/actions.json`.
-- **Seed data**: numeric PKs; parent entities loaded before children; no circular references.
-- **Translations**: a `translations/<locale>.json` file exists for every locale in `supportedLocales` **plus the `en-US` base**; every trait-provided field (`created_at`, `updated_at`, etc.) has a translation entry in each file; a `roles` section carries a `label` for **every** role in `security/roles.json` (completeness-enforced in every locale incl. en-US — keys are module-qualified role codes like `crm.admin`).
-
-### Step 3 — Translation deferral check
-
-Read `_brief/changelog.md`. If a translation deferral warning is present ("Translation files for [locales] are incomplete"), halt here. Tell the user: "Translation files must be completed before packing — install will fail translation completeness validation." Do not proceed to Step 4 until resolved.
-
-### Step 4 — Final inspect + version audit
-
-Run `dforge_module_inspect`. Show a one-line summary: entity count, view count, action count, role count. Then confirm version strings with the user:
-
-- **`version`**: always bump (semver) before packing.
-- **`dbSchemaVersion`**: bump only if any entity fields were added, removed, or type-changed since the last install. If unsure, compare current entity schemas against the last committed state.
-
-Get user confirmation on both version strings before packing.
-
-### Step 5 — Pack + install
-
-1. `dforge_module_pack` → produces `.dforge` tarball. (Blocked if any entity lacks a role granting Select — the Phase 5a gate; fix security coverage and re-run.)
-2. `dforge_module_install` with `DFORGE_URL` / `DFORGE_TOKEN`. Runs the full server-side validator.
-
-**Install-fix loop (mandatory):**
-
-1. Call `dforge_module_install` yourself. Do not ask the user to run the install command for you.
-2. If the result has `ok: false`, read the returned `output` in full. It is the raw CLI/server validator output and is the input for the next fix.
-3. If the failure is a module defect, fix it yourself. Use this table to identify which phase to backtrack to, then apply the backtrack protocol with the smallest suitable tool or file edit.
-4. Re-run Step 1 (`dforge_module_validate`), Step 2 (self-review for the touched area), Step 5 pack, and Step 5 install.
-5. Repeat this loop until install succeeds or the remaining failure is clearly an environment/tooling issue from the Tool failure protocol.
-
-Common module-defect patterns:
-
-| Install error pattern | Backtrack to |
+| `dforge-module-design` | 0a–0d | Identity, intake, design doc, pre-scaffold validation. Ends at `readyToScaffold: true`. |
+| `dforge-module-build` | 1–5 | Entities, behavior, views/menus, polish, security. |
+| `dforge-module-ship` | 6 | Validate → pre-pack review → pack → install-fix loop. |
+
+**Why split:** each stage needs a different half of the knowledge base. Phase 0
+needs none of the field-type/DSL detail; Phase 6 needs none of the intake
+guardrails. Loading only the active stage is what keeps a full module build
+inside one context window.
+
+## Do this first, every session
+
+1. **Get `moduleDir`.** If the user hasn't given one: _"Where should the module
+   directory live? (absolute path)"_ — ask before any tool call.
+2. **Call `dforge_module_plan({ action: "check", moduleDir })`.** It reads the
+   on-disk state and returns `currentPhase`, `nextSkill`, and `nextStep`.
+3. **Invoke the skill it names** (`nextSkill`) and follow it. If the module
+   already exists, also run `dforge_module_inspect` first so you know what's
+   there before proposing anything.
+
+That single call is the whole routing decision — do not guess the phase from
+file listings, and do not load a stage skill you weren't routed to.
+
+**If the user asks to skip Phase 0** ("just scaffold it", "skip the docs"):
+respond — _"Phase 0 documents are required before scaffolding. They take 15–30
+minutes and prevent hours of backtracking. Let me check where we are."_ — then
+call `check`. `dforge_module_create` is gated at the tool level and will refuse
+regardless.
+
+## Phase ledger
+
+`dforge_module_plan` tracks Phase 0 by which artifact files exist, and Phases
+1–6 by a ledger in `docs/phase.json` **plus** evidence read from the module
+itself (entities without fields, entities without a view, entities without a
+Select grant). So:
+
+- **Record each phase as you finish it** —
+  `dforge_module_plan({ action: "complete_phase", moduleDir, phase: "3", note: "..." })`.
+  For an optional phase the user declined, add `skipped: true`.
+- A resumed session then knows the difference between "Phase 2 skipped
+  deliberately" and "Phase 2 not started". Without the record, it can't.
+- `check` reports `gaps` when the ledger and the module disagree. Trust the
+  gaps: they're derived from the files.
+
+## Tool inventory
+
+Full descriptions are on the tools themselves — this is the map.
+
+| Group | Tools |
 |---|---|
-| "unknown entity code" or "unknown view code" | Phase 1 or 3 |
-| "missing translation key" | Phase 4 |
-| "FK constraint violation in seed data" | Phase 1 (check seed data 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" | Phase where the duplicate was introduced |
-
-**If install fails on auth (401/403) or connectivity** (refused), see "Tool failure protocol" above. Do not backtrack — fix credentials.
-
-**Exit criteria:** install exits 0 against a real tenant.
-
-## Backtrack protocol
-
-When a later phase exposes a problem in an earlier phase, follow steps 1–6 IN ORDER:
-
-**Multi-trigger rule (deterministic):** If multiple phases simultaneously expose gaps in earlier phases (e.g. Phase 3 needs a field; Phase 5 needs an action), resolve the **earliest-phase gap first**, complete its full backtrack, run `dforge_module_inspect`, then evaluate remaining gaps.
-
-**Phase 6 install exception:** when `dforge_module_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 validator has already rejected the package, so fix the referenced files, report what changed, and immediately re-run validate → pack → install. Keep user sign-off for product/design choices or ambiguous fixes.
-
-1. **Stop the current phase.** Don't paper over or improvise.
-2. **Name the issue precisely.** "Phase 3 wants a kanban grouped by `lead_status`, but Phase 1 didn't define `lead_status` on entity `lead`."
-3. **Identify the target phase + decision.** "Backtrack to Phase 1: add field `lead_status` to entity `lead`."
-4. **Get user sign-off.** Describe the change including any cascading impacts.
-5. **Apply the smallest tool that fits.** This rule overrides the "typical phase" labels in the tool reference table. Prefer `entity_field_add` over `entity_add`; `entity_field_rename` over remove+add when renaming (it propagates references for you); `role_right_set` over `role_add`; `view_modify` over `view_add` + remove.
-6. **Run `dforge_module_inspect` again** to surface knock-on impacts. Fix in order. Resume the original phase.
-
-**Field and entity rename/delete are handled for you** by the refactor-safe tools, which propagate the cascade in one call:
+| Lifecycle | `dforge_module_plan`, `dforge_module_create`, `dforge_module_inspect`, `dforge_module_validate`, `dforge_module_pack`, `dforge_module_install` |
+| Import | `dforge_module_import`, `dforge_dbml_import` |
+| Entities | `dforge_entity_add`, `dforge_entity_rename`, `dforge_entity_delete` |
+| Fields | `dforge_entity_field_add`, `_modify`, `_rename`, `_remove` |
+| **Composite (prefer these)** | `dforge_entity_reference_add` (relation), `dforge_entity_rollup_add` (child total), `dforge_entity_status_add` (status column) |
+| Behavior | `dforge_action_add`, `dforge_action_check`, `dforge_trigger_add`, `dforge_job_add`, `dforge_webhook_add` |
+| UI | `dforge_view_add`, `dforge_view_modify`, `dforge_menu_add`, `dforge_report_add` |
+| Polish | `dforge_setting_add`, `dforge_translation_sync`, `dforge_seed_add` |
+| Security | `dforge_role_add`, `dforge_role_right_set`, `dforge_folder_add` |
+| Cross-cutting | `dforge_dependency_add` |
+
+**Composite tools first.** A relation, a roll-up, and a status column each span
+several coordinated keys, and hand-assembling them from `entity_field_add` is
+the top source of broken modules. The composite tools emit the whole shape and
+can't express the broken variants. Reach for `entity_field_add` only for a
+plain scalar column.
+
+## Writing files: preview vs `apply`
+
+Every patch tool returns `{ summary, files, deletes? }` for the client to write
+— so you can preview a diff with the user first. Passing **`apply: true`**
+instead writes the files (and honours `deletes`) directly and returns only the
+paths touched.
+
+- **Preview (default)** when the user is reviewing the change, and for anything
+  in Phase 0.
+- **`apply: true`** for routine patches inside an already-approved plan, and for
+  every `rename`/`delete` refactor — it guarantees the `deletes` are applied,
+  which is easy to drop by hand.
+- Either way, **`_inspect.json` / `_validate.json` / `_action_check.json` are
+  report payloads, never files** — don't write them to disk.
+
+## Hard rules — all stages
+
+1. **Co-pilot stance.** Draft → propose → user approves → tool call. Never write
+   without confirmation. Read-only tools (`inspect`, `validate`, `action_check`)
+   need no gate.
+2. **Inspect before patching.** `dforge_module_inspect` at session start and
+   after every backtrack. Parse `files["_inspect.json"]`, not just the summary.
+3. **One thing at a time.** One question per turn; one entity / view / role /
+   action / report proposed per turn. The only exception is the Phase 1 field
+   batching rule (see `dforge-module-build`).
+4. **Validate and reflect.** After every user answer, restate what you understood
+   and ask "Right?" before moving on. Zero ambiguity going into the next step.
+5. **Load before authoring.** Pull the matching `dforge://reference/<name>` +
+   `dforge://example/<path>` resource before authoring any element type,
+   including inside a backtrack. They're **MCP resources — load by URI, not by
+   filesystem path**; your CWD is the module dir, so `references/*.md` won't
+   resolve on disk. If a needed resource fails to load, stop and tell the user —
+   never invent a schema from memory.
+6. **Don't invent domain content.** Fields, codes, roles and relationships come
+   from the user's domain. Never default to a generic `admin/contributor/viewer`
+   taxonomy they didn't ask for.
+7. **A step is done only when its file is written AND reviewed.** Deciding what
+   you *would* write is not "done". Don't advance a phase on intent.
+8. **Tabs in JSON, trailing newline** — the tools already emit this; don't
+   reformat.
+
+## Tool failure protocol — all stages
+
+1. **Surface the raw error verbatim.** Don't paraphrase.
+2. **Classify before asking for help.** If the output names a module defect, fix
+   it yourself with the smallest suitable tool, then re-run validation. The error
+   is already in the tool result — never ask the user to paste it back.
+3. **Ask the user only for environment issues** you can't fix from module files:
+   missing CLI, missing/expired credentials, unreachable tenant, permissions, or
+   a path outside the workspace.
+4. **Do not advance the phase** until the failing tool succeeds.
 
-- **Rename a field** → `dforge_entity_field_rename` (paired Reference, formulas, views, seed, cross-entity FKs).
-- **Remove a field** → `dforge_entity_field_remove` (cascade-cleans views/seed/paired Reference; warns formula/cross-entity).
-- **Rename an entity** → `dforge_entity_rename` (PK `{old}_id → {new}_id`, link.entity, references, view entityCode, role keys, action entity, folder bindings, seed).
-- **Delete an entity** → `dforge_entity_delete` (file + seed + manifest + roles + folders + view sources).
+Known causes worth distinguishing:
 
-**Always apply the response's `deletes` array as well as `files`** — rename/delete move or drop files, and `deletes` lists the module-root-relative paths to remove. Each tool surfaces what it could NOT auto-fix (reports datasets, translations, menu labels, DSL bodies, dangling cross-entity FKs) in `warning` — address those by hand. **After any rename/delete, run `dforge_module_validate`** and fix anything that still dangles before resuming.
+- **`pack`/`install` "command not found"** → dforge-cli isn't on PATH. Tell the
+  user: `npm install -g @dforge-core/dforge-cli`, then re-run.
+- **`install` HTTP 401/403 or connection refused** → credentials/connectivity,
+  NOT a module defect. Verify `DFORGE_URL` / `DFORGE_TOKEN`. Do not backtrack.
+- **`install` `ok: false` with validation/compile/schema output** → a module
+  defect. Treat `output` as the source of truth and run the fix loop in
+  `dforge-module-ship`.
 
-If you must do an entity-level change by hand (e.g. a surface a tool doesn't cover): enumerate references with `dforge_module_inspect`, confirm with the user, apply in reverse dependency order (roles → reports → views → actions → entity itself), then `dforge_module_validate`.
+## Resource index
 
-**After every backtrack** append to `_brief/changelog.md`:
+Load these by URI, one per step, at the step that needs them.
 
-```markdown
-## <YYYY-MM-DD> — Phase N → Phase M backtrack
-- Trigger: <what later phase tried to do>
-- Change: <what was patched>
-- Affected files: <list>
-```
+**Per-element references** — `dforge://reference/<name>`:
+`field-types`, `flags`, `column-types`, `column-domains`, `formulas`, `traits`,
+`data-views`, `menus`, `action-dsl`, `filters`, `security`, `reports`,
+`settings`, `jobs`, `number-sequences`, `document-extraction`,
+`print-templates`, `translations`, `queries`, `schema-import`, `excel-import`,
+`data-migration`, `manifest`, `validation-checklist`, `conventions`.
 
-## Final hygiene
+**Schemas** (fallback, when a reference points at one) — `dforge://schema/<name>`:
+`manifest`, `entity`, `domains`, `data-views`, `folders`, `menus`, `roles`,
+`jobs`, `seed-data`, `traits`, `webhooks`, `triggers`, `print-templates`,
+`settings`, `reports`.
 
-After Phase 6 install succeeds:
+**Docs**: `dforge://docs/dsl` (full DSL grammar + built-ins),
+`dforge://docs/conventions` (cross-module extension work — §1b only).
 
-**Ask the user**: "Delete `_brief/` (session scratch) or move it to `docs/` for committed design rationale?". Wait for their answer; do not act unilaterally.
+**Examples** — `dforge://example/<path>` (simple-todo) and
+`dforge://example/matrix-budget/<path>`. These are mandatory structure
+validators: copy their shapes, don't invent.
 
-Suggest a `git commit` summarizing the module. Do not commit unless the user asks.
+**Script**: `dforge://script/xlsx-to-model` (stdlib Python .xlsx extractor).