@atlashub/smartstack-cli 4.81.0 → 5.0.0

package/templates/skills/apex/SKILL.md

@@ -1,234 +0,0 @@
----
-name: apex
-description: |
-  SmartStack incremental development using APEX methodology (Analyze-Plan-Execute-eXamine).
-  Use this skill when:
-  - Adding a new section/resource to an existing module
-  - Developing feature by feature without /business-analyse
-  - Fixing or extending code generated by /business-analyse-develop
-  - Any incremental SmartStack development task
-argument-hint: "[-a] [-x] [-s] [-e] [-r] [-pr] <task description>"
----
-
-<objective>
-Execute incremental SmartStack development using the APEX methodology. This skill knows the SmartStack hierarchy (application/module/section/resource), delegates code creation to existing skills (/controller, /application, /ui-components, /efcore, /notification, /workflow) and MCP tools, and validates via MCP conventions.
-
-**Key principle:** /apex ORCHESTRATES — it never generates SmartStack code directly. All generation goes through skills and MCP tools.
-</objective>
-
-<quick_start>
-
-```bash
-# Direct use (you know exactly what to build):
-/apex add absence management to HR module           # Add section to module
-/apex -a fix the leave request controller            # Auto fix
-/apex -a -x -s -pr add PDF export to Orders           # Full workflow
-/apex -e add status field to Project entity          # Economy (no agents)
-/apex -r                                             # Resume previous
-
-# From /business-analyse-quick (vague idea → Mini-PRD):
-/business-analyse-quick une app RH avec employés     # → generates PRD for /apex -d
-
-# From /business-analyse-develop (automated multi-module):
-# /business-analyse-develop delegates to /apex -d automatically
-```
-
-</quick_start>
-
-<parameters>
-
-| Flag | Description |
-|------|-------------|
-| `-a` | Auto mode: skip confirmations |
-| `-x` | Deep review: adversarial code review (beyond step-04 automated checks) |
-| `-s` | Save mode: output to `.claude/output/apex/` |
-| `-e` | Economy mode: no subagents |
-| `-r` | Resume: continue from previous state |
-| `-pr` | PR mode: create pull request at end |
-| `-d {path}` | Delegate mode: read context from PRD file at `{path}`. Implies `-a -e`. Used by `/business-analyse-develop`. |
-| `--foundation` | Foundation mode: generate ONLY entities + EF configs + migration. No services/controllers/frontend. Used by business-analyse-develop Phase 0. |
-
-</parameters>
-
-<state_variables>
-
-| Variable | Type | Description |
-|----------|------|-------------|
-| `{task_description}` | string | What to implement (flags removed) |
-| `{task_id}` | string | Kebab-case identifier |
-| `{auto_mode}` | boolean | Skip confirmations |
-| `{examine_mode}` | boolean | Adversarial review |
-| `{save_mode}` | boolean | Save outputs to `.claude/output/apex/{task-id}/` |
-| `{economy_mode}` | boolean | No subagents |
-| `{pr_mode}` | boolean | Create PR at end |
-| `{delegate_mode}` | boolean | Delegated by `/business-analyse-develop` via `-d` flag |
-| `{delegate_prd_path}` | string? | Path to PRD file (`.ralph/prd.json` or `.ralph/prd-{module}.json`) |
-| `{foundation_mode}` | boolean | Foundation mode: entities-only (no services/controllers/frontend). Used by business-analyse-develop Phase 0. |
-| `{app_name}` | string | Application name |
-| `{module_code}` | string | Module code |
-| `{sections}` | object[] | Sections (required, min 1) with code/labels/icon/displayOrder |
-| `{entities}` | string[] | Main entities to manage (from need-challenge) |
-| `{module_complexity}` | string | "simple-crud", "crud-rules", "crud-workflow", "complex" |
-| `{has_dependencies}` | string | "none", "references", "unknown" |
-| `{key_properties}` | string[] | Key business properties mentioned by user |
-| `{code_patterns}` | object[] | Per-entity code generation config [{entity, strategy, prefix, digits, includeTenantSlug, separator}] |
-| `{prd_path}` | string? | `.ralph/prd-{module}.json` if exists |
-| `{feature_path}` | string? | `docs/business/.../feature.json` if exists |
-| `{needs_seed_data}` | boolean | Seed data creation required |
-| `{needs_migration}` | boolean | EF Core migration required |
-| `{needs_workflow}` | boolean | Workflow integration required |
-| `{needs_notification}` | boolean | Notification integration required |
-</state_variables>
-
-<state_persistence>
-
-**These variables exist only in the conversation context.** There is no file-based persistence between sessions.
-
-- Variables are set in step-00 (init) and propagated through subsequent steps via conversation context
-- If the conversation is interrupted, use `-r` (resume) — the model will re-derive state from existing files and git history
-- The `save_mode` (`-s`) flag writes step outputs to `.claude/output/apex/` but this is documentation, not resumable state
-- Delegate mode (`-d`) reads initial state from the PRD file, making it more resilient to interruptions
-
-</state_persistence>
-
-<entry_point>
-
-**FIRST ACTION:** Load `steps/step-00-init.md`
-
-</entry_point>
-
-<step_files>
-**Progressive loading — only load current step. Step 03 dispatches to layer sub-steps.**
-
-| Step | File | Model | Purpose |
-|------|------|-------|---------|
-| 00 | `steps/step-00-init.md` | Sonnet | Parse flags, detect application, verify MCP, define hierarchy (4 levels), scope validation |
-| 01 | `steps/step-01-analyze.md` | Opus | Explore existing code (parallel Agent tool or sequential) |
-| 02 | `steps/step-02-plan.md` | Opus | Layer-by-layer plan with skill/MCP mapping |
-| 03 | `steps/step-03-execute.md` | Opus | **Orchestrator** — dispatches to layer sub-steps below |
-| 03a | `steps/step-03a-layer0-domain.md` | Opus | Layer 0: Domain entities, EF configs, migration |
-| 03b | `steps/step-03b-layer1-seed.md` | Opus | Layer 1: Seed data (navigation, permissions, roles) |
-| 03c | `steps/step-03c-layer2-backend.md` | Opus | Layer 2: Services, controllers, backend tests |
-| 03d | `steps/step-03d-layer3-frontend.md` | Opus | Layer 3: Pages, i18n, routes, frontend tests |
-| 03e | `steps/step-03e-layer4-devdata.md` | Opus | Layer 4: Development test data (optional) |
-| 04 | `steps/step-04-examine.md` | Opus | eXamine: MCP validation, build, POST-CHECKs, acceptance criteria |
-| 05 | `steps/step-05-deep-review.md` | Opus | Deep Review: adversarial code review (if -x) |
-| 06 | `steps/step-06-resolve.md` | Opus | Fix BLOCKING findings (if any) |
-| 07 | `steps/step-07-tests.md` | Opus | Final Test Sweep: security tests, coverage, remaining failures |
-| 08 | `steps/step-08-run-tests.md` | Opus | Run Final Test Sweep until 100% pass |
-</step_files>
-
-<apex_phases>
-**APEX = Analyze → Plan → Execute → eXamine**
-
-| Phase | Step | Required | Description |
-|-------|------|----------|-------------|
-| *Init* | 00 | Yes | Setup, hierarchy, scope validation, **scope guard** (skipped in `-d` delegate mode) |
-| **A** — Analyze | 01 | Yes | Explore existing code |
-| **P** — Plan | 02 | Yes | File-by-file plan with skill/MCP mapping |
-| **E** — Execute | 03 | Yes | Orchestrate creation via skills and MCP (5 layers: domain, seed, backend, frontend, devdata) |
-| **X** — eXamine | 04 | Yes | 3 MCP tools + POST-CHECKs (security + convention + architecture, see post-checks.md), build, acceptance criteria |
-| *Deep Review* | 05 (if -x) | No | Adversarial code review beyond automated checks |
-| *Resolve* | 06 (if BLOCKING) | No | Fix BLOCKING findings |
-| *Final Test Sweep* | 07-08 | **Yes** | Security tests, coverage sweep, remaining failures |
-</apex_phases>
-
-<reference_files>
-**Loaded conditionally by steps that need them:**
-
-| File | Purpose | Loaded by | Stays in context for |
-|------|---------|-----------|---------------------|
-| `references/smartstack-api.md` | BaseEntity, interfaces, entity/config/controller patterns | step-01 | step-03a/03b/03c (released after L2) |
-| `references/smartstack-layers.md` | Layer rules, skill/MCP mapping, planning templates, delegate fast path | step-02 | step-03a/03b/03c (released after L2) |
-| `references/core-seed-data.md` | Comprehensive seed data templates (navigation, permissions, roles) | step-03b (Layer 1) | released after Layer 1 |
-| `references/smartstack-frontend.md` | Frontend patterns, EntityLookup, i18n (sections 1-6) | step-03d (Layer 3, deferred) | step-04 |
-| `references/smartstack-frontend-compliance.md` | Documentation, form testing, compliance gates (sections 7-9) | step-03d (Layer 3, deferred) | step-04 |
-| `references/challenge-questions.md` | Hierarchy rules, challenge questions, delegate mode skip | step-00 | — |
-| `references/error-classification.md` | Build error diagnosis categories A-F | step-03 (build failure), step-04 | — |
-| `references/parallel-execution.md` | Agent tool launch patterns, task coordination, decision matrix | step-01, step-03c/03d (if NOT economy_mode) | — |
-| `references/post-checks.md` | Compact checklist — indexes checks in `references/checks/*.sh` | step-04 | — |
-| `references/checks/*.sh` | Bash check scripts (security, backend, frontend, seed, architecture, infrastructure) | step-04 (executed via bash) | — |
-
-**Context propagation rule:** Files loaded in step N remain in conversation context for step N+1. Steps mark "do NOT re-read" to avoid duplicate reads.
-</reference_files>
-
-<execution_rules>
-
-- **ULTRA THINK at each step transition** — Deep reasoning about scope, existing code, and whether elements need to be CREATED or MODIFIED before acting. This is critical when updating an existing module (adding sections/resources to existing seed data, permissions, roles).
-- **Load one step at a time** - Progressive loading to manage context
-- **ORCHESTRATE, never generate** - All SmartStack code via skills (/controller, /application, etc.) or MCP tools
-- **MCP-first** - Use MCP scaffold/validate tools before manual approaches
-- **Verify MCP at startup** - step-00 checks MCP availability
-- **Layer order** - Layer 0 (domain+infra+migration) → Layer 1 (seed data) → Layer 2 (backend+tests) → Layer 3 (frontend+tests) → Layer 4 (devdata)
-- **Parallel Agent tool** - Parallel execution for scan (step-01) and within Layer 2/3 (step-03) for multi-entity, unless economy_mode
-- **Tests inline** - Backend tests run after Layer 2, frontend tests run after Layer 3 (max 3 fix iterations each). Step-07 = final sweep (security + coverage).
-- **Exception: seed data** — The templates in core-seed-data.md and person-extension-pattern.md are generated directly because no MCP tool covers seed data creation yet. This is a documented exception to the "orchestrate, never generate" rule. <!-- TODO: Remove exception when MCP scaffold_seed_data (B1) is ready -->
-- **Frontend pages: ALWAYS via Skill("ui-components")** — economy_mode affects parallelization only, NOT whether /ui-components is called. NEVER generate .tsx pages directly, even in delegate or economy mode.
-- **Save outputs** if `{save_mode}` = true
-- **Commits per layer** - Atomic commits after each execution layer
-- **Delegate mode** (`-d`): Read PRD context, skip challenge questions, auto+economy mode implied. Used when `/business-analyse-develop` delegates code generation to `/apex`.
-- **Foundation mode** (`--foundation`): Generate ONLY entities + EF configs + migration (domain + infrastructure layers). Skip application/api/frontend/tests. Used by business-analyse-develop Phase 0 to create database foundation before spawning parallel teammates.
-
-</execution_rules>
-
-<execution_guarantee>
-
-## Execution Guarantee (CRITICAL — read before ANY step)
-
-> **The user is NOT watching. There is NOBODY to answer your questions. Stopping is a FAILURE.**
-
-When APEX runs (especially in `-d` delegate mode or `-a` auto mode), the execution is **fully autonomous**. The user has launched the command and walked away. Any pause, question, or numbered option list is a **dead end** — nobody will respond.
-
-**YOU MUST NOT:**
-- Stop to ask the user a question between layers
-- Present numbered options ("Would you like to: 1. Continue... 2. Generate... 3. Stop...")
-- Pause between layers to summarize progress and wait for confirmation
-- Stop because the work seems "large" or "complex" — that is expected
-- Add "Let me know if you want me to continue" at any point
-
-**YOU MUST:**
-- After Layer N completes, **IMMEDIATELY** load the next sub-step file. No pause, no summary, no question.
-- Execute the full pipeline: Layer 0 → Layer 1 → Layer 2 → Layer 3 → Layer 4 → step-04, with **ZERO pauses** between layers
-- Treat each "Load `steps/step-03X-...md`" instruction as a **mandatory immediate action**, not a suggestion
-- Continue even if a layer produced warnings (only a build gate failure after max retries is a valid stop)
-
-**The ONLY valid reasons to stop:**
-1. A build gate fails after maximum retries (3 attempts)
-2. ALL layers are completed and step-04 (eXamine) is done
-3. The user presses Ctrl+C
-
-**Anything else — including "being helpful" by asking — is a VIOLATION of the execution guarantee.**
-
-</execution_guarantee>
-
-<error_handling>
-
-## Error Handling Strategy
-
-| Error | Action | Max Retries |
-|-------|--------|-------------|
-| `dotnet build` fails | Identify error, fix via skill/MCP, rebuild | 3 |
-| `npm run typecheck` fails | Fix TypeScript error, retry | 3 |
-| MCP unavailable | Degraded mode: use `smartstack-api.md` as sole reference, no MCP validation | — |
-| File lock (MSB3021) | Auto-use `--output /tmp/{project}_build` for build verification | — |
-| NuGet restore required | Run `dotnet restore` before first `dotnet build` | 1 |
-| Migration fails | Rollback migration (`dotnet ef migrations remove`), fix entity/config, retry | 2 |
-| MCP scaffold output wrong | Verify against `smartstack-api.md` patterns, fix manually | — |
-| POST-CHECK fails | Return to step-03, fix the issue, re-validate | 2 |
-| Stuck after max retries | AskUserQuestion with options: "Try alternative", "Skip", "Discuss" | — |
-
-**Principle:** Always fix CODE, never bypass checks. If stuck, escalate to user.
-
-</error_handling>
-
-<success_criteria>
-- SmartStack hierarchy detected (app/module)
-- Plan validated with skill/MCP mapped for each file
-- Code created/corrected via existing skills and MCP (no direct generation)
-- MCP validate_conventions: 0 errors
-- Build: dotnet build PASS + npm run typecheck PASS (if frontend)
-- Seed data complete as dedicated Layer 1 (navigation, permissions, roles, provider) — impossible to skip
-- Tests inline: backend tests after Layer 2, frontend tests after Layer 3
-- Final test sweep: security tests + coverage >= 80% + target 100% pass rate (acceptable fallback: skip with TODO after max retries)
-- Commits atomic per layer
-</success_criteria>

package/templates/skills/apex/_shared.md

@@ -1,197 +0,0 @@
-# APEX Shared — SmartStack Detection & MCP References
-
-> **Loaded by:** step-00-init (always), other steps as needed
-
----
-
-## SmartStack Project Detection
-
-### Scan Pattern
-
-1. `*.sln` → .NET backend confirmed
-2. `docs/business/` → BA artifacts exist
-3. `.ralph/prd-*.json` → PRDs exist
-4. `src/pages/` → React frontend exists
-
----
-
-## Delegate Mode Context
-
-> **Active when:** `-d {path}` flag is set. Implies `-a` (auto) + `-e` (economy).
-
-When `/business-analyse-develop` invokes `/apex -d {prd_path}`:
-
-1. **Read PRD** from `{delegate_prd_path}` (`.ralph/prd.json` or `.ralph/prd-{module}.json`)
-2. **Extract context:**
-   - `app_name` = `prd.project.application` (e.g., "HumanResources")
-   - `module_code` = `prd.project.module` (e.g., "EmployeeManagement")
-   - `sections` = from `_seedDataMeta.coreSeedData.navigationSections` in infrastructure tasks
-   - `entities` = from `prd.tasks` filtered by `category == 'domain'` (entity names from description)
-   - `feature_path` = `prd.source.feature_json_path`
-3. **Read task metadata** per category:
-   - `_seedDataMeta` → seed data scope (coreSeedData, navRoute, appLabels)
-   - `_frontendMeta` → wireframes, filesToCreate, fkFields
-   - `_migrationMeta` → entities[], moduleCode
-4. **Skip:** challenge questions (step-00 §5), user checkpoints (step-01 §6, step-02 §6)
-5. **No nested teams:** `-e` implied, all execution sequential on agent principal
-
-### PRD State Update Protocol (delegate mode only)
-
-After completing each layer in step-03, update the PRD file:
-```
-Read {delegate_prd_path}
-For each task executed in this layer:
-  task.status = 'completed' (or 'failed')
-  task.completed_at = ISO timestamp
-  task.commit_hash = git rev-parse --short HEAD
-  task.files_changed = { created: [...], modified: [...] }
-Write back to {delegate_prd_path}
-```
-
----
-
-## MCP Tools Reference
-
-### Required (every execution)
-
-| Tool | Purpose | Step |
-|------|---------|------|
-| `validate_conventions` | Validate SmartStack conventions | 00 (check), 04 (examine) |
-
-### Permission Path Format
-
-> **NOTE:** Permission paths use the navigation hierarchy as base (2+ segments).
-> Controller `[NavRoute]` attributes use the same segments: minimum 2 (`app.module`) for module-level, 3 (`app.module.section`) for section-level.
-
-| Level | Permission format | Segments |
-|-------|------------------|----------|
-| Module | `{app}.{module}.{action}` | 2+1 segments |
-| Section | `{app}.{module}.{section}.{action}` | 3+1 segments |
-| Resource | `{app}.{module}.{section}.{resource}.{action}` | 4+1 segments |
-
-**Examples:**
-- Module: `human-resources.employees.read` (2+1)
-- Section: `human-resources.employees.departments.read` (3+1)
-- Resource: `human-resources.employees.departments.export.execute` (4+1)
-
-> Permission codes use the SAME kebab-case segments as NavRoute codes.
-> Every dot-separated segment in a permission path is a navigation entity code.
-> Multi-word codes must use kebab-case: `human-resources`, NOT `humanresources`.
->
-> SmartStack.app reference: `support-client.my-tickets.read`, `administration.email-templates.read`
->
-> Do not use: `humanresources.employees.read` (concatenated — no kebab-case)
-> Correct: `human-resources.employees.read` (kebab-case — matches NavRoute)
-
-### Generation (step-03)
-
-| Tool | Purpose | Condition |
-|------|---------|-----------|
-| `scaffold_extension` | Generate entities, services, controllers | New code creation |
-| `suggest_migration` | Get standardized migration name | EF Core changes |
-| `generate_permissions` | Generate RBAC permissions + seed data | New module/section |
-| `scaffold_api_client` | Generate TypeScript API client | Frontend changes |
-| `scaffold_routes` | Generate React Router routes | Frontend changes |
-
-### eXamine (step-04) — POST-CHECKs (see post-checks.md)
-
-| Tool | Purpose | Condition |
-|------|---------|-----------|
-| `check_migrations` | Validate EF Core migrations | Migration created |
-| `validate_frontend_routes` | Validate route/layout alignment | Frontend changes |
-| `validate_security` | Check security patterns | API changes |
-
-**Key POST-CHECKs (most common failures):**
-- **#8:** Forms must be full pages — no modals/dialogs
-- **#13:** No hardcoded Tailwind colors — use CSS variables only
-- **#6+27:** i18n in separate `locales/{lang}/{module}.json` — not embedded in .ts
-- **#10:** Form pages must have `.test.tsx` companion files
-- **#28:** Pages must use `useTranslation` — no hardcoded strings
-
-### Analysis (step-01)
-
-| Tool | Purpose |
-|------|---------|
-| `api_docs` | Existing API documentation |
-| `analyze_extension_points` | React extension points |
-
-### Tests (step-07)
-
-| Tool | Purpose |
-|------|---------|
-| `scaffold_tests` | Generate tests (domain, app, api, security) |
-| `suggest_test_scenarios` | Suggest test scenarios |
-| `analyze_test_coverage` | Check coverage percentage |
-
-### Deep Review (step-05, if -x)
-
-| Tool | Purpose |
-|------|---------|
-| `review_code` | Adversarial code review |
-| `analyze_code_quality` | Code quality metrics |
-
----
-
-## Severity Labels
-
-| Label | Meaning | When to use |
-|-------|---------|-------------|
-| **BLOCKING** | Build fails or security vulnerability. Cannot proceed. | `dotnet build` / `npm typecheck` failure, OWASP violation, tenant isolation bypass |
-| **CRITICAL** | Functionally broken at runtime but compiles. | Missing DI registration, wrong route, empty translations at runtime |
-| **WARNING** | Suboptimal but works. Should fix before merge. | Missing tests, non-canonical naming, cosmetic issues |
-| **INFO** | Suggestion or best practice. Non-blocking. | Performance tips, alternative patterns |
-
-> **Rule:** Only use BLOCKING for issues that prevent compilation or create security vulnerabilities.
-> CRITICAL is for runtime failures. Everything else is WARNING or INFO.
-
----
-
-## MCP Degraded Mode
-
-> When MCP is unavailable, fall back to manual patterns from reference files.
-
-| MCP Tool | Fallback |
-|----------|----------|
-| `validate_conventions` | Manual review against `smartstack-api.md` patterns |
-| `scaffold_extension` | Create files manually following `smartstack-api.md` entity/service/controller patterns |
-| `suggest_migration` | Name format: `{context}_v{version}_{sequence}_{Description}` (see existing migrations for version) |
-| `generate_permissions` | Write `HasData()` code manually following `core-seed-data.md` permission section |
-| `scaffold_routes` | Create `componentRegistry.generated.ts` manually. Keys MUST use DOT notation: `PageRegistry.register('{app_code}.{module_code}.{section_code}', lazy(...))`. Example: `PageRegistry.register('rh.employes.list', lazy(() => import('../pages/Rh/Employes/EmployeesListPage')));` — NEVER use hyphens as hierarchy separator. For client projects: `import { PageRegistry } from '@atlashub/smartstack';`. For SmartStack core: `import { PageRegistry } from '@/extensions/PageRegistry';`. See `frontend-route-wiring-app-tsx.md` §Client SDK |
-| `validate_frontend_routes` | Run POST-CHECK bash scripts from `post-checks.md` |
-| `validate_security` | Run security POST-CHECKs S1-S6 from `post-checks.md` |
-| `check_migrations` | Run `dotnet ef migrations has-pending-model-changes` manually |
-| `scaffold_tests` | Create test files manually following `smartstack-frontend-compliance.md` §8 patterns |
-
----
-
-## Context Bridge for Skill Delegation
-
-> When delegating to `/controller`, `/ui-components`, `/application`, etc., pass this context block to ensure the skill has enough information.
-
-```
-Context for {skill_name}:
-- Application: {app_name}
-- Module: {module_code}
-- NavRoute: {navRoute} (e.g., "human-resources.employees")
-- Entity: {entity_name} with properties: {key_properties}
-- Tenant mode: {strict|optional|scoped|none}
-- CSS: Use CSS variables ONLY (see smartstack-frontend.md §4)
-- I18n: 4 languages (fr, en, it, de), namespace: {module-kebab}
-- Forms: Full pages with own routes, ZERO modals/drawers
-- FK fields: Use EntityLookup component (see smartstack-frontend.md §6)
-```
-
-> Adjust the template based on the skill: backend skills don't need CSS/i18n context, frontend skills don't need tenant mode details.
-
----
-
-## Existing Skills Delegation
-
-| Skill | When to delegate |
-|-------|-----------------|
-| `/controller` | Complex controller with custom routes |
-| `/application` | New application/module structure |
-| `/ui-components` | Complex React pages (tables, grids, dashboards) |
-| `/efcore` | Complex EF Core configurations |
-| `/notification` | In-app or email notifications |
-| `/workflow` | Automated workflow triggers |

package/templates/skills/apex/references/analysis-methods.md

@@ -1,178 +0,0 @@
-# Analysis Methods — FK Detection, Tenant Modes, Code Patterns, Gap Analysis
-
-> **Loaded by:** step-01-analyze.md (sections 4-7)
-> **Purpose:** Detailed methods for analyzing existing code and planning entity-level requirements.
-
----
-
-## FK Field Detection
-
-For each entity found (or to be created), identify FK relationships:
-- Properties ending in "Id" with matching navigation property
-- Record: `{ entity, fkProperty, targetEntity, isRequired }`
-
-**Why:** FK fields drive two critical requirements:
-1. **Frontend:** Each FK field MUST use `<EntityLookup />` (not `<input>`, not `<select>`)
-2. **Backend:** Each target entity's GetAll MUST support `?search=` parameter + return `PaginatedResult<T>`
-
-See `references/smartstack-frontend.md` section 6 for EntityLookup patterns.
-
----
-
-## Tenant Mode Decision
-
-For each entity found (or to be created), determine the `tenantMode`:
-
-| Mode | Meaning | Examples | EF Filter |
-|------|---------|----------|-----------|
-| `strict` | Data belongs to one tenant | Employee, Order, Invoice | `TenantId == current` |
-| `optional` | Can be shared or tenant-specific | Department, Currency, JobTitle | `TenantId == current OR TenantId == null` |
-| `scoped` | Explicit scope rules | Settings, Workflow, EmailTemplate | `TenantId == current AND Scope == current` |
-| `none` | Shared across all tenants (not filtered) | Navigation, Permission, User | No TenantId |
-
-**Why:** Tenant mode drives EF query filters, seed data generation, and API access control.
-
-**Reference:** See `references/smartstack-api.md` for TenantId handling patterns and `smartstack-layers.md` for seed data strategies per tenant mode.
-
----
-
-## Code Pattern Detection
-
-For each entity found (or to be created), identify code generation needs using the following **priority order**:
-
-```
-PRIORITY 1 — User choice from scope validation (step-00):
-  IF {code_patterns} is set (from step-00 section 5c):
-    → Use {code_patterns} for each entity
-    → This is the user's explicit choice — always takes precedence
-
-PRIORITY 2 — feature.json (from /business-analyse):
-  IF feature.json exists AND entity has codePattern:
-    → Use codePattern config from feature.json (strategy, prefix, digits, etc.)
-    → Record in analysis: entity has auto-generated code
-
-PRIORITY 3 — Heuristic fallback (delegate mode only):
-  IF delegate_mode AND no code pattern from Priority 1 or 2:
-    → Apply heuristic default based on entity name:
-      Invoice/Order/Receipt/PurchaseOrder → timestamp-daily
-      Ticket/Incident/SupportRequest → timestamp-minute
-      Contract/Policy/Agreement → year-sequential
-      Category/Status/Type (reference data) → uuid-short
-      Employee/Customer/Project → sequential
-    → Note: heuristic applied — PRD was incomplete
-
-FALLBACK — Manual (safest default):
-  IF none of the above apply:
-    → strategy: "manual" (Code field in CreateDto, user-provided)
-    → No auto-generation, no ICodeGenerator injection
-```
-
-**Important:** In interactive mode (no `-d` flag), heuristics are never applied silently. The user is always asked via scope validation (step-00 section 5c). Heuristics only serve as fallback in delegate mode when the PRD is incomplete.
-
-**Why:** Code generation strategy drives CreateDto structure, service injection (ICodeGenerator<T>), and DI registration.
-
-**Reference:** See `references/code-generation.md` for strategy table, volume-to-digits calculation, and backend patterns.
-
-
-
----
-
-## Gap Analysis
-
-Compare what EXISTS vs what the TASK REQUIRES:
-
-```
-For each element: EXISTS+COMPLETE → "skip" | EXISTS+INCOMPLETE → "modify" | MISSING → "create"
-```
-
-Cross-reference with step-00 challenge responses:
-- Each entity: entity, EF config, service, controller, frontend pages → exists/missing
-- Each section: NavigationSectionSeedData, frontend route → exists/missing
-- If dependencies: verify FK target entities and their `?search=` support
-
-### Seed Data Completeness Criteria (CRITICAL)
-
-> **A seed file EXISTS does NOT mean it's COMPLETE.** When adding sections/resources to an existing module, seed files are the most commonly missed update.
-
-For seed data files, apply these SPECIFIC completeness criteria:
-
-| File | COMPLETE if | INCOMPLETE if |
-|------|-------------|---------------|
-| NavigationModuleSeedData.cs | Contains entries for ALL {sections} from step-00 scope | Missing GetSectionEntries/GetResourceEntries for ANY new section |
-| Permissions.cs | Has constants for ALL {sections} (Read/Create/Update/Delete/Wildcard per section) | Missing permission constants for ANY new section |
-| PermissionsSeedData.cs | Has HasData() entries for ALL permissions in Permissions.cs | Missing HasData() for ANY new permission |
-| RolesSeedData.cs | Has role-permission mappings for ALL permissions | Missing mappings for ANY new permission |
-| {App}SeedDataProvider.cs | Calls seed methods that cover ALL modules/sections | Missing calls for new module/section seed data |
-
-**Decision matrix:**
-
-```
-Seed file NOT found                              → "create"
-Seed file found + covers ALL target sections     → "skip"
-Seed file found + MISSING some target sections   → "modify"  ← THIS IS THE COMMON MISS
-```
-
-> **ULTRA THINK:** When the task says "add absence management to HR module" and NavigationModuleSeedData.cs already has entries for "employees" section — the file EXISTS but is INCOMPLETE (missing "absences" section). Action = "modify", NOT "skip".
-
----
-
-## Scope Re-Check (after exploration)
-
-**Re-validate scope after code exploration reveals the true entity count.**
-Step-00 guard uses the user's description (may undercount). Now we know the actual entities.
-
-```
-IF NOT delegate_mode:
-  actual_entities = count of entities marked "create" in gap analysis
-  actual_sections = count of sections marked "create"
-
-  IF actual_entities > 6:
-    WARNING: "Code exploration reveals {actual_entities} entities.
-     This exceeds the recommended maximum (4) for a single /apex invocation.
-     Risk: incomplete migrations, lost conventions, missing pages.
-     Consider: split into {ceil(actual_entities/4)} iterations of ~4 entities each."
-
-    Ask user to confirm or re-scope.
-```
-
----
-
-## Analysis Validation — User Checkpoint
-
-**Objective:** Present findings and validate scope BEFORE planning.
-
-### Present Findings
-
-```
-ANALYSIS FINDINGS
-═══════════════════════════════════════════════════════════════
-
-Entities expected / found / to create: {summary}
-Sections expected / found / to create: {summary}
-FK Relationships: {fkFields summary}
-Dependencies: {cross-module refs or "none"}
-Complexity: {module_complexity}
-```
-
-### Validate with User (if NOT auto_mode)
-
-Question template (same as step-01 section 6b):
-- "Scope is correct" (Recommended)
-- "Add elements" → update entities/sections, re-run gap analysis
-- "Reduce scope" → update accordingly
-- "Change approach" → potentially restart from step-00
-
----
-
-## Analysis Summary Output
-
-```
-**APEX SmartStack - Analysis Complete**
-
-Navigation: {app_name} → {module_code} → {sections[].code}
-Entities: {entity_name → create | modify | skip}
-Existing: entities, configs, services, controllers, pages, seed data, tests (with paths)
-Required: create / modify / skip lists
-Profile: complexity, dependencies, FK fields, workflow, notifications
-ACs: AC1..ACn (inferred from PRD/feature/task/challenge)
-```