@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/development/audit-dev-data/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: audit-dev-data
+description: Audit code generated by the Data phase against the PRD slice — migrations, seed providers, navigation/permissions coverage, FK constraints, drift detection
+group: D
+phase: devData
+kind: audit
+audit_only: true
+section_label: 'AUDIT-DEV-DATA (rules to apply against generated migrations + seed providers vs the PRD Data slice)'
+allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
+---
+
+# audit-dev-data — Data Phase Code-vs-PRD Audit
+
+## Context
+
+You are auditing the output of the Data phase of `ba-develop`.
+Compare the PRD slice (spec) against the generated EF Core migrations and
+seed providers (reality), and emit findings for every drift.
+
+You receive in the system prompt:
+
+- `--- PRD SLICE: DATA ---` — Markdown listing migrations to create + seed
+  data the user wants for this application.
+- `--- PROJECT INVENTORY (data) ---` — deterministic scan of:
+  - `migrations[]` (file, name, timestamp, tablesCreated, tablesDropped, action),
+  - `seedProviders[]` (file, className, entitiesReferenced, tablesReferenced,
+    seedsNavigation, seedsPermissions),
+  - the entities visible from the Domain layer (already generated upstream).
+- `--- FILES TOUCHED THIS PHASE ---` — files modified during the current run.
+- `--- APPLICATION CODE / MODULE CODE ---` — active scope.
+
+You may use `Read` / `Glob` / `Grep` to verify rules. **No `Edit` /
+`Write` / `Bash`** — you are read-only.
+
+Apply every rule across the module scope. Emit `ok` findings for passing
+rules (UI green checks). Use `err` only when the gap is unambiguous (an
+entity from the slice has no migration covering it; a seed provider that
+should bring navigation declares none); use `warn` for conventions and
+nice-to-haves.
+
+## Rules
+
+### DEV-DAT-001 — Every PRD entity has at least one migration creating its table
+- **Severity**: err (if any entity uncovered), ok (if all covered)
+- Check: for each entity in the Domain inventory (passed alongside the
+  Data slice), scan `inventory.data.migrations[*].tablesCreated`. There
+  must be at least one migration whose `tablesCreated` contains a table
+  whose name matches the entity (case-insensitive, stripping table prefix
+  like `crm_`, `inv_`, `auth_`).
+- Skip entities whose classification is `component` — they are owned by
+  a parent entity and don't get their own table.
+- **ok**: label=`DEV_DAT_001_ok`, params=`{ count: <number> }`
+- **err**: label=`DEV_DAT_001_err`, params=`{ entities: "<comma-separated entity names without table>" }`
+- **fixSkill**: `backend-data-layer`, **fixPhaseKey**: `data`
+- **solution** (mandatory on err): "Re-run the Data phase. The subagent
+  must call `scaffold-migration` once per missing entity (the migration
+  generator infers `tablesCreated` from the EF Core ModelSnapshot)."
+
+### DEV-DAT-002 — Migration table names follow the `<prefix>_<EntityPlural>` convention
+- **Severity**: warn (if any violation), ok (if all comply)
+- Check: every entry in `inventory.data.migrations[*].tablesCreated`
+  must match `^[a-z]{2,5}_[A-Z][A-Za-z0-9]*$` — a 2-5 letter lowercase
+  prefix + underscore + PascalCase entity-plural form. Use `Grep` on
+  the migration `.cs` if a name looks suspicious.
+- **ok**: label=`DEV_DAT_002_ok`
+- **warn**: label=`DEV_DAT_002_warn`, params=`{ tables: "<comma-separated bad table names>" }`
+- **solution** (mandatory on warn): "Update the EF Core configuration of
+  each entity (`b.ToTable(\"<prefix>_<EntityPlural>\")`) and regenerate
+  the migration. Untyped table names will collide once another module
+  introduces an entity with the same simple name."
+
+### DEV-DAT-003 — No duplicate migrations for the same table
+- **Severity**: err (if any table appears twice in `tablesCreated`), ok (otherwise)
+- Check: build a set of `tablesCreated` across all migrations; flag any
+  table that appears in `tablesCreated` more than once. A duplicate
+  create migration breaks `dotnet ef database update` — the second
+  attempt errors on `table already exists`.
+- **ok**: label=`DEV_DAT_003_ok`
+- **err**: label=`DEV_DAT_003_err`, params=`{ tables: "<comma-separated duplicate tables>" }`
+- **solution** (mandatory on err): "Delete one of the duplicate migrations
+  AND its `.Designer.cs` companion. Squash via `efcore squash` if you
+  want to consolidate without losing history."
+
+### DEV-DAT-004 — At least one seed provider exists for the module
+- **Severity**: err (if zero providers AND PRD declares any seed data), ok otherwise
+- Check: if the Data slice mentions seed entries (lookup rows, navigation
+  entries, permissions) AND `inventory.data.seedProviders` is empty,
+  emit err. Skip when the slice has zero `seed` mentions.
+- **ok**: label=`DEV_DAT_004_ok`
+- **err**: label=`DEV_DAT_004_err`, params=`{ moduleCode: "<from PRD>" }`
+- **fixSkill**: `backend-seed-data`, **fixPhaseKey**: `data`
+- **solution** (mandatory on err): "Run `scaffold-seed --module <moduleCode>`
+  in the Data phase. The generated provider implements `ISeedDataProvider`
+  and is auto-discovered via DI registration."
+
+### DEV-DAT-005 — Module seed provider declares navigation if PRD adds menu entries
+- **Severity**: err (if PRD has new menu entries AND no provider sets `seedsNavigation`), ok otherwise
+- Check: if the PRD slice introduces an application/module/section
+  (the menu or seed sections of the slice mention `NavigationApplication`,
+  `NavigationModule`, or `NavigationSection`), at least one entry in
+  `inventory.data.seedProviders[*].seedsNavigation` must be `true`.
+  Otherwise the new module never appears in the Studio menu at runtime.
+  This rule mirrors the existing seed-coverage gate (`verifySeedCoverage`).
+- **ok**: label=`DEV_DAT_005_ok`
+- **err**: label=`DEV_DAT_005_err`, params=`{ providers: "<comma-separated providers without nav>" }`
+- **solution** (mandatory on err): "Edit the main provider's `SeedAsync`
+  method to call `NavigationApplication.Create(...)` /
+  `NavigationModule.Create(...)` / `NavigationSection.Create(...)` for
+  the new menu entries. A `ref-data only` provider that seeds lookup rows
+  but skips navigation leaves the module orphaned."
+
+### DEV-DAT-006 — Module seed provider declares permissions if PRD adds RBAC entries
+- **Severity**: err (if PRD permissions exist AND no provider sets `seedsPermissions`), ok otherwise
+- Check: same shape as DEV-DAT-005 but on `seedsPermissions`. If the PRD
+  slice declares permission codes for the module, at least one
+  `inventory.data.seedProviders[*].seedsPermissions` must be `true`.
+- **ok**: label=`DEV_DAT_006_ok`
+- **err**: label=`DEV_DAT_006_err`, params=`{ providers: "<comma-separated providers without perms>" }`
+- **solution** (mandatory on err): "Add `Permission.CreateForModule(...)`
+  + `Role.Create(...)` calls in the provider's `SeedAsync`. Without these,
+  no role can ever access the module's actions and the API gates with
+  `403 Forbidden` for every authenticated user."
+
+### DEV-DAT-007 — Migration filenames follow `<timestamp>_<Verb><Subject>.cs`
+- **Severity**: warn (if any violation), ok (if all comply)
+- Pattern: `/^\d{14}_[A-Z][A-Za-z0-9]+\.cs$/` — 14-digit timestamp +
+  underscore + PascalCase verbsubject (e.g. `20260430120000_AddBudget.cs`).
+- Check `inventory.data.migrations[*].file` (basename only).
+- **ok**: label=`DEV_DAT_007_ok`
+- **warn**: label=`DEV_DAT_007_warn`, params=`{ files: "<comma-separated bad filenames>" }`
+- **solution** (mandatory on warn): "Rename via `efcore rename` so the
+  EF Core toolchain keeps a coherent history. Manual renames must update
+  the `Designer.cs` and the `[Migration(\"...\")]` attribute too."
+
+### DEV-DAT-008 — Same-module relationships are realized as real FK constraints with the declared cascade
+- **Severity**: err (if any same-module relationship has no FK constraint OR a wrong cascade), ok (if all match or no relationships)
+- Catches the historical gap where a same-module PRD relationship produced only
+  a bare `Guid` column — no `HasForeignKey` / `OnDelete`, no navigation — so
+  referential integrity was silently absent. `scaffold-entity` now emits the
+  constraint from `relations[]`; this rule guards that it actually reached the
+  EF configuration **and** the migration.
+- Scope: **same-module** relationships ONLY. A relationship whose target lives
+  in another module / app / SmartStack Core is intentionally a plain `Guid`
+  attribute (no constraint — see `create-data-model/levels/relationships.md`
+  § Cross-module) and is SKIPPED here.
+- Check, for every (source, target, cascade) triple declared in this module's
+  PRD relationships:
+  1. **Constraint exists** — `Read` the entity's EF configuration AND `Grep` the
+     migration `.cs`: there MUST be a `HasOne(...).HasForeignKey(...)` (or
+     `HasMany(...).WithOne()`) for the relationship AND a corresponding
+     `OnDelete(DeleteBehavior.<X>)` / FK constraint in the migration. Absent →
+     **err** (FK not realized — the relationship is a bare `Guid`).
+  2. **Cascade matches** — the `DeleteBehavior` must equal the PRD cascade
+     (`Cascade` ↔ cascade, `Restrict` ↔ restrict, `SetNull` ↔ set-null,
+     `NoAction` ↔ no-action). Mismatch → **err**.
+- Skip when the PRD slice declares no same-module relationships.
+- **ok**: label=`DEV_DAT_008_ok`
+- **err (missing)**: label=`DEV_DAT_008_missing`, params=`{ refs: "<comma-separated source→target>" }`
+- **err (mismatch)**: label=`DEV_DAT_008_mismatch`, params=`{ refs: "<comma-separated source.fk:expected:got>" }`
+- **solution** (mandatory on err): "Pass the relationship to `scaffold-entity`
+  as a `relations[]` entry (`type`, `targetEntity`, `foreignKey`, `onDelete`) so
+  it emits `HasOne(...).HasForeignKey(...).OnDelete(DeleteBehavior.<X>)` + the
+  navigation property, then regenerate the migration. A same-module FK that
+  exists only as a bare `Guid` column has NO referential integrity; a wrong
+  cascade silently corrupts data at delete time."
+
+## Output
+
+Emit EXACTLY ONE JSON code block matching the standard `auditReport`
+envelope. Set `dimension` to `devData` on every finding. Include one
+`ok` finding per passing rule and one finding per failing rule.
+
+```json
+{
+  "auditReport": {
+    "scope": "devData",
+    "applicationCode": "<from PRD>",
+    "moduleCode": "<from PRD>",
+    "findings": [
+      {
+        "dimension": "devData",
+        "code": "DEV-DAT-005",
+        "severity": "err",
+        "label": "DEV_DAT_005_err",
+        "params": { "providers": "CrmSeedDataProvider" },
+        "solution": "Add NavigationApplication.Create / NavigationModule.Create / NavigationSection.Create in SeedAsync.",
+        "fixSkill": "backend-seed-data",
+        "fixPhaseKey": "data"
+      }
+    ]
+  }
+}
+```
+
+Stop immediately after the JSON block. Do not narrate.

package/templates/skills/development/audit-dev-domain/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: audit-dev-domain
+description: Audit code generated by the Domain phase against the PRD slice — entity files, FK pairing, naming, traceability, drift detection
+group: D
+phase: devDomain
+kind: audit
+audit_only: true
+section_label: 'AUDIT-DEV-DOMAIN (rules to apply against generated .cs entities vs the PRD Domain slice)'
+allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
+---
+
+# audit-dev-domain — Domain Phase Code-vs-PRD Audit
+
+## Context
+
+You are auditing the output of the Domain phase of `ba-develop`.
+Your job is to compare what the PRD slice says should exist (spec) against
+what is actually present in the generated `.cs` files (reality), and emit
+findings for every drift.
+
+You receive in the system prompt:
+
+- `--- PRD SLICE: DOMAIN ---` — Markdown listing entities, attributes, and
+  relationships the user wants for this application.
+- `--- PROJECT INVENTORY (domain) ---` — deterministic scan of `.cs` files
+  with each entity's name, file path, base class and namespace.
+- `--- FILES TOUCHED THIS PHASE ---` — files modified during the current run.
+- `--- APPLICATION CODE / MODULE CODE ---` — the active scope of the audit.
+
+You may also use `Read` / `Glob` / `Grep` on the project to verify rule
+checks. **No `Edit` / `Write` / `Bash`** — you are read-only.
+
+Apply every rule below across the whole module scope. Emit `ok` findings for
+passing rules so the UI shows green checks. Emit `err` findings only when
+the spec is unambiguous and the code is clearly wrong (missing entity,
+broken FK target). Use `warn` for naming, conventions, and drift signals
+that the user should review but won't block execution by themselves.
+
+## Rules
+
+### DEV-DOM-001 — Every PRD entity has a generated `.cs` file
+- **Severity**: err (if any entity from PRD missing in inventory), ok (if all present)
+- Check: for each entity declared in the PRD slice, find an
+  `inventory.domain.entities[*].name` matching case-insensitively. The
+  comparison strips trailing/leading whitespace.
+- **ok**: label=`DEV_DOM_001_ok`, params=`{ count: <number> }`
+- **err**: label=`DEV_DOM_001_err`, params=`{ missing: "<comma-separated entity names>" }`
+- **fixSkill**: `backend-data-layer`, **fixPhaseKey**: `domain`
+- **solution** (mandatory on err): "Re-run the Domain phase. The subagent
+  must call `scaffold-entity` for each missing entity (PascalCase class +
+  EF Core configuration). Do not commit until all entities exist."
+
+### DEV-DOM-002 — Every PRD attribute is declared in the matching `.cs` file
+- **Severity**: err (if any attribute missing), ok (if all present)
+- Check: for each (entity, attribute) pair in the PRD slice, `Read` the
+  matching `.cs` file and verify a `public <Type> <Name>` declaration is
+  present. The match is case-insensitive on the attribute name; the type
+  may be the C# equivalent (`string` / `int` / `decimal` / `bool` /
+  `DateTime` / `Guid`) or the EF nullable form (`<Type>?`).
+- **ok**: label=`DEV_DOM_002_ok`
+- **err**: label=`DEV_DOM_002_err`, params=`{ attrs: "<comma-separated entity.attr pairs>" }`
+- **fixSkill**: `backend-data-layer`, **fixPhaseKey**: `domain`
+- **solution** (mandatory on err): "Add the missing properties to each
+  listed entity. Match the PRD type and respect EF Core nullability when
+  the PRD marks the attribute optional."
+
+### DEV-DOM-003 — Every relationship `targetEntityCode` resolves to an existing `.cs` file
+- **Severity**: err (if any FK target missing), ok (if all valid)
+- Check: for each relationship in the PRD slice, the target entity must
+  appear in `inventory.domain.entities[*].name` (case-insensitive). A
+  broken FK target means the migration phase will fail.
+- **ok**: label=`DEV_DOM_003_ok`
+- **err**: label=`DEV_DOM_003_err`, params=`{ refs: "<comma-separated source→target pairs>" }`
+- **solution** (mandatory on err): "Either generate the missing target
+  entity in this phase before continuing, or remove the relationship
+  from the PRD slice if it was hallucinated upstream."
+
+### DEV-DOM-004 — `baseClass` matches the PRD classification
+- **Severity**: warn (if any mismatch), ok (if all match)
+- Calque DM-015. Check `inventory.domain.entities[*].baseClass`:
+  - PRD `classification: lookup` → baseClass should be `LookupEntity` or
+    contain `Lookup` (e.g. `BaseLookupEntity`).
+  - PRD `classification: component` → baseClass should be `Entity` (no
+    soft-delete needed, owned-by-parent).
+  - PRD `classification: full-module` (default) → baseClass should be
+    `Entity` and the file should reference the audit/soft-delete fields.
+- **ok**: label=`DEV_DOM_004_ok`
+- **warn**: label=`DEV_DOM_004_warn`, params=`{ entities: "<entity:expected:got list>" }`
+- **solution** (mandatory on warn): "For each entity, switch its base class
+  so it matches the PRD classification. Lookup entities must inherit
+  `LookupEntity` so the seed-data scaffolder picks them up."
+
+### DEV-DOM-005 — Naming conventions (calque DM-006 + DM-007)
+- **Severity**: warn (if any violation), ok (if all comply)
+- Pattern (entities): `/^[A-Z][A-Za-z0-9]*$/` — PascalCase, no underscores.
+- Pattern (attributes / properties): `/^[A-Z][A-Za-z0-9]*$/` for C# public
+  properties (PascalCase mandatory in C#). The PRD camelCase form is
+  expected to translate to PascalCase in the generated `.cs`.
+- Check filenames + class declarations + property declarations against
+  the patterns. Skip C# keywords and well-known framework members
+  (`Equals`, `GetHashCode`, etc.).
+- **ok**: label=`DEV_DOM_005_ok`
+- **warn**: label=`DEV_DOM_005_warn`, params=`{ names: "<comma-separated bad names>" }`
+- **solution** (mandatory on warn): "Rename the listed identifiers to
+  PascalCase. The generated EF Core configuration relies on the property
+  names matching the PRD attribute names exactly."
+
+### DEV-DOM-006 — No "ghost" entities (drift detector)
+- **Severity**: warn (if any ghost found), ok (if none)
+- Reciprocal of DEV-DOM-001: every entity in
+  `inventory.domain.entities[*].name` must appear in the PRD slice.
+  Ghost entities indicate either a stale `.cs` from a previous run that
+  the user has since removed from the PRD, or a hallucinated entity the
+  subagent emitted without spec authority.
+- **ok**: label=`DEV_DOM_006_ok`
+- **warn**: label=`DEV_DOM_006_warn`, params=`{ entities: "<comma-separated ghost names>" }`
+- **solution** (mandatory on warn): "Either re-add these entities to the
+  PRD slice if they were removed by mistake, or delete their `.cs` file
+  and the matching EF Core configuration. Leaving ghosts in the codebase
+  triggers stale FK relationships in the next phase."
+
+### DEV-DOM-007 — `*Id` Guid attributes are paired with a navigation property or `[ForeignKey]` (calque DM-013)
+- **Severity**: warn (if any unpaired), ok (if all paired)
+- Check: for each generated entity, `Read` the `.cs` and look for
+  properties of the form `public Guid <Name>Id { get; set; }` (or
+  `Guid?`). For each one:
+  - PASS if the same class declares a `public <Target> <Name> { get; set; }`
+    nav property (e.g. `BudgetId` ↔ `Budget`), OR
+  - PASS if the property carries a `[ForeignKey(...)]` attribute, OR
+  - PASS if a sibling EF configuration file (`<Entity>Configuration.cs`)
+    declares `HasOne(...)/HasMany(...)` on that key.
+  - Otherwise WARN with the entity.attr pair.
+- Skip when the attribute is the primary key (`Id`).
+- **ok**: label=`DEV_DOM_007_ok`
+- **warn**: label=`DEV_DOM_007_warn`, params=`{ attrs: "<comma-separated entity.attr pairs>" }`
+- **solution** (mandatory on warn): "Add a navigation property whose name
+  matches the attribute without the trailing `Id`, OR decorate the key
+  with `[ForeignKey(nameof(<Nav>))]`, OR declare the relationship in the
+  EF configuration file. Without one of these, EF Core will not infer
+  a constraint and the migration phase will produce a malformed schema."
+
+### DEV-DOM-008 — Lookup entities expose `Code`, `Label`, and `IsActive` (calque DM-015 lookup contract)
+- **Severity**: warn (if any lookup missing the canonical trio), ok (if all comply)
+- Check: every inventory entity whose `baseClass` contains `Lookup` must
+  declare three public properties named `Code`, `Label`, `IsActive`.
+  Use `Grep` on the `.cs` file with patterns `public string Code`,
+  `public string Label`, `public bool IsActive` (allow the nullable form).
+- Skip when `inventory.domain.entities` has no lookup entity.
+- **ok**: label=`DEV_DOM_008_ok`
+- **warn**: label=`DEV_DOM_008_warn`, params=`{ entities: "<entity:missing list>" }`
+- **solution** (mandatory on warn): "Add the missing properties on each
+  listed lookup. The seed-data scaffolder reads `Code` to seed the row
+  identity, and the frontend renders `Label` + filters by `IsActive`."
+
+## Output
+
+Emit EXACTLY ONE JSON code block matching the standard `auditReport`
+envelope (same shape as `audit-data-model`). Set `dimension` to
+`devDomain` on every finding. Include one `ok` finding per passing rule
+(so the UI lights up green) and one finding per failing rule.
+
+```json
+{
+  "auditReport": {
+    "scope": "devDomain",
+    "applicationCode": "<from PRD>",
+    "moduleCode": "<from PRD>",
+    "findings": [
+      {
+        "dimension": "devDomain",
+        "code": "DEV-DOM-001",
+        "severity": "err",
+        "label": "DEV_DOM_001_err",
+        "params": { "missing": "Budget,BudgetType" },
+        "solution": "Re-run the Domain phase. The subagent must call scaffold-entity for each missing entity.",
+        "fixSkill": "backend-data-layer",
+        "fixPhaseKey": "domain"
+      }
+    ]
+  }
+}
+```
+
+Stop immediately after the JSON block. Do not narrate.