@dforge-core/dforge-mcp 0.1.0-rc.1 → 0.1.0-rc.10

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

@@ -1,107 +1,301 @@
 ---
 name: dforge-mcp-author
-description: Author dForge modules using the dforge-mcp tool surface. Use when the user has the @dforge-core/dforge-mcp MCP server connected and asks to scaffold, extend, pack, or install a dForge module. Replaces hand-writing JSON files with structured tool calls that produce schema-valid output on the first try.
+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 six phases with explicit gates for confirmation, a deterministic backtrack protocol, a tool-failure protocol, and resume-from-partial-state support.
 ---
 
-# dForge Module Author (MCP-driven)
+# dForge Module Author — Co-pilot
 
-You're authoring a dForge module via the `dforge-mcp` MCP server. dForge is a metadata-driven, multi-tenant business platform — modules are JSON metadata + DSL scripts.
+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.
 
-**Your edge here** is that you have *tools*, not just text generation. Always prefer a tool call over writing a file by hand. Every tool either returns a file map (so the user can preview before commit) or shells out to the validated native CLI.
+## Tool reference
 
----
-
-## Tool surface
+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 | What it does | Returns |
+| Tool | Typical phase | What it does |
 |---|---|---|
-| `dforge_module_create` | Build a brand-new module's file map | `{ files: {...} }` — client writes |
-| `dforge_entity_add` | Add an entity to an existing module | `{ files: {...}, warning?: ... }` — client writes |
-| `dforge_module_pack` | Pack a module dir into a `.dforge` tarball | `{ tarballPath, sizeBytes }` (writes the tarball) |
-| `dforge_module_install` | Install a module to a tenant | `{ ok, output }` (live action) |
-| `dforge_dbml_import` | Generate from DBML (stub) | not yet implemented |
+| `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_create` | 1 | Scaffold a new module (returns file map; user writes) |
+| `dforge_entity_add` | 1 | Add a whole entity to an existing module |
+| `dforge_entity_field_add` | 1 | Patch one field onto an existing entity |
+| `dforge_entity_field_modify` | 1 | Replace one field's spec |
+| `dforge_entity_field_remove` | 1 | Drop one field (warns about dependents) |
+| `dforge_action_add` | 2 | DSL action + ui/actions.json entry |
+| `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 (needs dforge-cli on PATH) |
+| `dforge_module_install` | 6 | Install to tenant — the real validator |
+
+## Resources to load once per session
 
-## Resources
+- `dforge://docs/conventions` — naming, FK+Reference pattern, traits, security model
+- `dforge://schema/manifest`, `entity`, `data-views`, `folders`, `menus`, `roles`, `reports`, `settings`, `jobs`, `seed-data` — consult before emitting each file kind
 
-Read these *before* generating any module content so your output matches the canonical schema:
+**If a resource fails to load, halt and notify the user.** Do not invent conventions or schemas from memory.
 
-- `dforge://schema/manifest` — manifest.json shape (required fields, patterns)
-- `dforge://schema/entity` — entity JSON shape (fields, traits, refs)
-- `dforge://schema/data-view` — data view shape (viewType, dataSources)
-- `dforge://docs/conventions` — naming, FK+Reference pattern, traits, security model
+## Hard rules
 
-Load them when you start a session, not after a wrong guess.
+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 → tool call → file write. Never write without confirmation.
+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 — confirmation applies only to **write** tools.
+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. (Field batching inside an entity has a narrow exception in Phase 1.)
+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.
 
-## Standard workflow
+## Tool failure protocol
 
-### 1. Gather requirements (one short turn)
+If any MCP tool returns an error at any time:
 
-Ask the user, in order:
-1. **What's the module for?** One sentence is enough.
-2. **What's the module code?** Lowercase, hyphen-or-underscore, e.g. `crm`, `pm`, `hr-admin`.
-3. **What entities does it own?** Rough list with one-line descriptions each.
-4. **Greenfield or extending an existing module?** If extending, ask which.
+1. **Surface the raw error verbatim** to the user. Do not paraphrase.
+2. **Do not attempt a workaround** with a different tool or hand-crafted JSON.
+3. **Ask the user to resolve the tool-level issue** (missing dep, bad path, schema validation, etc.) before continuing.
+4. **Do not advance the phase** until the failing tool succeeds.
 
-Don't ask about field types, view layouts, or DSL actions yet — those come *after* a working skeleton.
+Two specific tool errors have known causes worth distinguishing:
 
-### 2. Read the schemas + conventions
+- **`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.
 
-Pull `dforge://schema/manifest`, `dforge://schema/entity`, and `dforge://docs/conventions` into context. Skim, don't memorise.
+## Resume-from-partial-state
 
-### 3. Call `dforge_module_create`
+At every session start, call `dforge_module_inspect` on the module dir (if it exists).
 
-Pass:
-- `code`, `displayName`, `description` from the user's answers
-- `entities`: array of `{ name, label, traits }` — default traits to `"identity+audit"`
-- `preset`: `"minimal"` unless the user wants full template (settings/translations/seed)
-- `dependencies`: usually `["admin", "metadata"]` — both are required for typical modules
+- If the dir doesn't exist or has no `manifest.json` → start fresh from Phase 0.
+- If it does exist:
+  1. Read `_brief/00-intake.md` and `_brief/changelog.md` if present.
+  2. Cross-reference the inspect output against the brief to infer the last completed phase (e.g. entities exist + views exist + roles missing → last completed = Phase 3).
+  3. 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?"
+  4. Wait for the user's answer before proceeding.
 
-You'll get back `{ summary, files: { "<relPath>": "<contents>", ... } }`.
+## Phase 0 — Intake (required)
 
-### 4. Preview the file map with the user
+**Preconditions:** none.
 
-Show the file list (paths only) + the manifest contents. Ask "write these to `./<code>`?". Don't write without confirmation.
+**Action:** Walk through the questions below **one at a time, in sequence**. After each answer, apply the validate-and-reflect rule (hard rule #4): restate what you understood, confirm, then proceed to the next question. Each subsequent question is informed by prior answers — don't ask Q2 in a way that contradicts what Q1 established. Don't batch.
 
-### 5. Write the files
+**Interaction style — free-form prose only.** Every question in Phase 0 is asked as a plain-language sentence in your conversation message. Do **NOT** use `AskUserQuestion`, picker UIs, multiple-choice tabs, structured forms, or any tool that presents the user with predefined options to choose from. The whole point of Phase 0 is to elicit the user's own words about purpose, user types, and verbs — predefined buckets bias the answer into your taxonomy and lose the verbs we need for Phase 5. If your client offers a picker tool, suppress it for Phase 0; resume normal tool use in Phase 1+.
 
-Use your filesystem tool (Write / bash heredoc / fs.writeFileSync, whatever your client offers). Each value in `files` is the literal file contents — including JSON indentation. Don't re-format.
+**Forbidden picker examples that have leaked in past sessions** (do not present any variant of these):
+- "Single role / Two roles / Three+ roles" — predetermines security shape before entities exist
+- "admin / manager / user / viewer" or "admin / contributor / viewer" — imposes a generic taxonomy
+- "English only / Multilingual" — answer in plain text instead
 
-### 6. Iterate
+**Exception:** if the user explicitly says "give me defaults" / "pick reasonable defaults" / similar, you may propose a default brief in one block, restate it, and ask "any to override?". Otherwise, sequential free-form text only.
 
-Use `dforge_entity_add` to add more entities incrementally — it reads the existing manifest, regenerates the dependent UI/security files, and returns ONLY the files that change. Re-preview each time before writing.
+**Question order** (use the wording in your own voice):
 
-For fields, ref columns, actions, formulas, settings, reports — write those directly into the entity JSON / new files under `logic/`, `ui/`, etc. The schemas are your guide; the tools don't (yet) cover field-level changes.
+1. **Purpose.** "In one sentence, what does this module do?"
+   Reflect: "OK — so it's a `<paraphrase>`. Right?" → wait.
 
-### 7. Pack + install
+2. **User types and verbs** — capture in plain language. "Who'll use this, and what does each type DO with it?" Listen for verbs that imply actions on data: submits, approves, reviews, issues, receives, matches, closes, etc.
 
-Once the module is shaped right:
-1. `dforge_module_pack` with `moduleDir: "./<code>"` → returns the tarball path.
-2. (Optional) `dforge_module_install` with `pathOrTarball: <tarballPath or moduleDir>` and a `tenantUrl` + `token` (or rely on `DFORGE_URL`/`DFORGE_TOKEN` env). This runs the *full* server-side validator — the only validator available. Surface its output verbatim; if it fails, fix and re-pack.
+   **Capture format — full verb-form sentences, not role labels.** Write each as `<descriptor of the person> <verb phrase>`. Never use role-noun labels (Requester, Manager, Buyer, Admin, Approver, Viewer, Contributor, AP Clerk, etc.) as the bullet head — those are role NAMES which prematurely commit to a security taxonomy.
 
----
+   ✅ Good:
+   ```
+   - Anyone in the company submits purchase requests and tracks their own.
+   - Department managers approve or reject pending requests for their team.
+   - Buyers in the procurement team manage suppliers, collect quotes, and issue purchase orders.
+   - Warehouse staff confirm what physically arrived against the PO.
+   - Accounts payable staff match supplier bills against the PO and receipt, then approve for payment.
+   ```
 
-## Hard rules
+   ❌ Bad (role labels as headings):
+   ```
+   - **Requester** — submits purchase requests
+   - **Approver** — approves pending requests
+   - **Buyer** — manages suppliers
+   - **AP Clerk** — matches bills
+   ```
+   The bad form trades situational verbs for fixed nouns and biases Phase 5 toward exactly those roles. Phase 5 might consolidate (e.g. one role covers both warehouse and AP) or split — that's Phase 5's job.
 
-- **Always preview file maps before writing.** Tools return — the user decides.
-- **Use `dforge_entity_add`, not regenerate-from-scratch.** It preserves the existing manifest's UUID, version, dependencies, etc.
-- **Tabs in JSON.** All emitted files use `\t` indentation. Don't re-pretty-print with spaces.
-- **Don't invent `code` or `moduleId`.** `code` comes from the user; `moduleId` is auto-generated by the tool (UUID). Never hand-write a UUID.
-- **Refer to the conventions doc for FK+Reference, traits, flags.** The MCP server doesn't enforce these — your output does. The first install will catch violations, but a clean first install is the goal.
+   Example missing verbs: "admins and users" — push back: "What does an admin do that a user can't?"
+   Reflect: "So users are: `<bullets>`. Right?" → wait.
 
----
+   **Hard forbidden in Phase 0:** do NOT emit role codes (`<code>.admin`, `<code>.requester`, etc.), do NOT use role-noun labels as bullet heads, do NOT propose a rights matrix, do NOT add a "Target user roles" section to the brief. Roles are derived from entities + verbs in Phase 5, and **entities don't exist yet**.
 
-## When NOT to use the tools
+3. **Existing dForge modules to depend on.** "Are you building this on top of other dForge modules — e.g. needing entities from `crm` or `parties`?" (`admin` and `metadata` are platform-implicit. Don't ask about them. Don't even MENTION them in the brief — every module depends on them, so listing them in a per-module brief is pure noise.) If the user names actual deps, capture those; if not, the brief's Dependencies section should read literally `None.` or be omitted.
+   Reflect → wait.
 
-- **Modifying a single existing field in an entity JSON.** Just edit the file.
-- **Writing an action DSL script.** No tool for that — write to `logic/actions/<name>.dsl` directly. Reference the `dforge://docs/conventions` doc for DSL syntax.
-- **Querying live tenant state.** No tool for that either — shell out to `dforge-cli` via your bash tool if the user has it installed.
+4. **Language scope.** "English only, or any other locales the module needs to ship with translations for?"
+   Reflect → wait.
 
----
+5. **Optional follow-up — domain ambiguities.** If anything in answers 1-4 left an open question (e.g. "what counts as a 'closed' feedback item?", "is the submitter always a logged-in user or also anonymous?"), ask that question now, one at a time. Continue until you can describe how the module should work without any open questions in your head. **Goal of Phase 0: you understand the module well enough to design entities in Phase 1 without further clarification.**
+
+**Write:** `_brief/00-intake.md` after the final reflection. **Allowed sections (exhaustive):**
+- `# <module-name> — intake`
+- `## Purpose` (one paragraph)
+- `## Module identity` (code, display name, target path)
+- `## User types` (bullet list — `<type> — <verbs>`. NO role codes, NO rights, NO "Target user roles" table.)
+- `## Dependencies` (which dForge modules)
+- `## Languages`
+- `## Scope / success criteria` (only if mentioned by user)
+- `## Open assumptions` (anything you flagged + need to revisit in Phase 1)
+
+**Forbidden sections in the brief:** any roles table, any entity proposal (entities are Phase 1's deliverable, not Phase 0's). If you find yourself drafting a "Target user roles" table — stop and replace it with the verb-only bullet list.
+
+**Final gate:** Show the brief verbatim, ask "Does this capture everything? Anything to fix or add?". Proceed only on explicit confirmation. The next message you send after confirmation should be the start of Phase 1 — proposing the entity inventory.
+
+## Phase 1 — Domain (required)
+
+**Preconditions:** intake brief written and confirmed.
+
+**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).
+
+**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; flag in the brief that upstream base-entity changes are the user's responsibility to track.
+
+**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 — Actions (optional, skip-able)
+
+**Preconditions:** Phase 1 complete.
+
+Skip entirely if the module is pure CRUD. Do **not** fabricate actions to fill the phase.
+
+When the user has a real business operation: **load `dforge://docs/dsl`** (the full action DSL reference — block structure, all 30 built-in functions, field-access syntax, batch-mode rules, JS subset, pitfalls), then call `dforge_action_add` per action — one at a time — with the full DSL body. `dforge://docs/conventions` is broader module-level guidance and does NOT cover the DSL grammar — load `docs/dsl` specifically.
+
+**Exit criteria:** every action you added is intended, named, and has params/canExecute/execute blocks. Compilation is validated in Phase 6.
+
+## Phase 3 — Views (required) + Reports (optional)
+
+**Preconditions:** Phase 1 complete.
+
+### 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. Read `dforge://schema/data-views` for the `viewConfig` shape of the type you're proposing 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). Pull `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.
+
+- **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, 3 complete (you need entity/view/action/report codes to grant rights on).
+
+### 5a. Roles + rights matrix (required)
+
+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 "users" 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
+
+### 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:** every entity is reachable to at least one role; if folders declared, every folder has security mapped.
+
+## Phase 6 — Verify (required, non-skippable)
+
+**Preconditions:** all **required** prior phases complete. Optional phases (2, 3c reports, 4 settings/seed, 5b folders) are not preconditions — explicitly skipped optional phases do not block Phase 6.
+
+**Steps:**
+
+1. `dforge_module_pack` → produces `.dforge` tarball.
+2. `dforge_module_install` with `DFORGE_URL` / `DFORGE_TOKEN`. Runs the full server-side validator.
+3. **If install fails on a module defect** (schema, FK, missing translation, etc.), the error message tells you which phase to backtrack to. Use the backtrack protocol.
+4. **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.
+
+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`; `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.
+
+**Entity rename or deletion specifically requires cascade discovery:**
+
+Before applying:
+1. Run `dforge_module_inspect` to enumerate every reference: views' `dataSources.entityCode`, role `rights` keys, action `entity`, report dataset `entityCd`, seed-data files, formula/DSL bodies.
+2. List every affected artifact to the user. Require explicit confirmation.
+3. Apply in **reverse dependency order**: roles → reports → views → actions → entity itself.
+4. Re-inspect; verify no dangling references remain.
+
+**After every backtrack** append to `_brief/changelog.md`:
+
+```markdown
+## <YYYY-MM-DD> — Phase N → Phase M backtrack
+- Trigger: <what later phase tried to do>
+- Change: <what was patched>
+- Affected files: <list>
+```
+
+## Final hygiene
+
+After Phase 6 install succeeds:
 
-## Sanity check before declaring done
+**Ask the user**: "Delete `_brief/` (session scratch) or move it to `docs/` for committed design rationale?". Wait for their answer; do not act unilaterally.
 
-- `dforge_module_pack` succeeded → archive size is non-trivial (>100 KB usually)
-- `dforge_module_install --code <tenant>` exited 0 → server validated everything
-- The user confirms the install log looks right (entities created, no warnings about missing translations / orphan rights)
+Suggest a `git commit` summarizing the module. Do not commit unless the user asks.