@atlashub/smartstack-cli 4.81.0 → 5.0.0

package/templates/skills/ba-develop/references/auto-healing.md

@@ -0,0 +1,191 @@
+# `/ba-develop` — Auto-healing + never-halt protocol
+
+> Loaded on demand when a gate fails. The SKILL.md just mentions "the gate
+> enters the auto-healing loop" — the full mechanics live here.
+
+## Default behavior: never halt — auto-heal, else defer the item
+
+The orchestrator **never halts the run and never asks the user mid-flight.**
+Every phase wraps its gate in a retry loop. The subagent observes the failure,
+classifies it, applies a targeted fix, and re-runs the gate. **Up to 25 retries
+per item**, with two additional safety nets so the loop never spins forever.
+When a failure is genuinely unhealable, the item is **deferred** — a blocker is
+recorded, the safest best-effort action is taken — and the run continues to the
+end of the module.
+
+## Per-item retry loop (defers, never halts)
+
+```
+attempt = 1
+while attempt <= 25:
+    runPhase()
+    gate = runGate()
+    if gate.ok:
+        commit()
+        return SUCCESS
+
+    failure = classifyFailure(gate.errors)
+
+    if failure.kind in DEFER_KINDS:                       # see table below
+        deferItem(blocker(failure)); bestEffort(failure)  # skip / keep / stub safely
+        return DEFERRED(failure.kind, attempt)            # ← item deferred, RUN CONTINUES
+
+    if same fingerprint already seen 2 times before:
+        deferItem(blocker(kind='infinite-loop')); bestEffort(failure)
+        return DEFERRED('infinite-loop', attempt)
+
+    applyFix(failure)                                     # ← the auto-heal
+    rememberFingerprint(failure)
+    attempt += 1
+
+deferItem(blocker(kind='retry-budget-exhausted')); bestEffort(lastFailure)
+return DEFERRED('retry-budget-exhausted', 26)
+```
+
+`SUCCESS` and `DEFERRED` are the only two outcomes — there is no `HALT`.
+`DEFERRED` records a blocker and lets the orchestrator move on to the next
+item / sub-phase / phase. The run as a whole always reaches the end of the
+module and reports `blockers[]`.
+
+The **fingerprint** is `hash(failure.kind + sorted(errorPaths) + first 200
+chars of stderr)`. Two retries with the same fingerprint = the fix did not
+change anything; a third retry would loop forever — defer the item early.
+
+The **retry budget** is per-item (25). It is a loop terminator, NOT a run
+terminator: exhausting it defers exactly that one item and the run carries on.
+
+## Failure classification → auto-fix
+
+| Failure kind | Detection | Auto-fix |
+|--------------|-----------|----------|
+| `compile.missing-using` | `dotnet build` CS0246/CS0234 + namespace in entité.md / DTO inventory | Insert the missing `using <Ns>.<Layer>.<Module>.<X>;` at top of offending file. Retry. |
+| `compile.missing-type` | CS0246 with no matching declaration | Identify the missing layer (DTO? Service? Interface?), re-invoke its scaffolder. Retry. |
+| `compile.partial-method-mismatch` | CS0759 / CS0762 | Delete the stale `*.Custom.cs` partial fragment, log the removed lines to `heal.log` for manual re-add. Retry. |
+| `migration.naming-collision` | `dotnet ef migrations add` "name already exists" | Bump the sequence (`_v1.0.0_002_…` → `_v1.0.0_003_…`) via `cli/lib/migration-name.ts`. Retry. |
+| `migration.destructive` | `up.cs` contains `DROP COLUMN`, `DROP TABLE`, `RENAME COLUMN`, or non-nullable col without `defaultValue` | **DEFER** (blocker `migration.destructive`, severity `critical`). Keep the generated migration but **never auto-apply** it (`database update`); embed the `.sql` in the blocker for user review before any apply. Continue. |
+| `business.todo-br` | `grep -rn "// TODO\[BR-"` under `src/<Ns>.Application` | Read `règles-métier.md` for BR-NN expression + invalidExamples, implement as `RuleFor(…).Must(…)` on Create+Update validators OR a service guard. Retry. |
+| `business.todo-uc` | `grep -rn "// TODO\[UC-"` under same path | Read `<section>/use-case.md` main + alternative flows, write the service body. Retry. |
+| `business.todo-screen` | `grep -rn "// TODO\[SCREEN-"` under Controllers/Screens/ | Add the missing method to `I{Entity}Service` + impl in `{Entity}Service`. Reuse Phase 2a Linq primitives. Retry. |
+| `acceptance.todo-ac` | `grep -rn "// TODO\[AC-"` under Tests/<Module>/Acceptance/ | Read the AC bullet from `<section>/use-case.md`, fill the Fact body using WebApplicationFactory + controller route + DTO from Phase 2. Retry. |
+| `audit-dev-api.applicable` | `audit-dev-api --mode audit` emits a finding with `{autoApplyable: true}` | Run `audit-dev-api --mode apply` for that finding. Retry. |
+| `audit-dev-frontend.applicable` | Same shape, frontend audit | Run `audit-dev-frontend --mode apply` for that finding. Retry. |
+| `validate-page.import-resolve` | `violations[].rule === 'imports-resolve'` | Re-invoke `scaffold-api-client` for the entity, then re-`scaffold-component`. Retry. |
+| `validate-page.i18n-keys-resolve` | `violations[].rule === 'i18n-keys-resolve'` | Re-invoke `scaffold-component` with `priorErrors` — deep-merge writer adds missing locale entries. Retry. |
+| `validate-page.pagetemplate-wrapping` | `violations[].rule === 'pagetemplate-wrapping'` | Re-invoke `scaffold-component`; emitter always wraps. Retry. |
+| `registry.phantom-import` | `aggregate-component-registry` exit 1 "import does not resolve" | Either drop the registration (deferred page) or re-`scaffold-component` (wrong path). Retry. |
+| `registry.componentkey-collision` | `aggregate` exit 1 "componentKey collision" | **DEFER** (blocker `registry.componentkey-collision`, `high`). Keep the first registration, skip the colliding one, finish 3c. `userAction`: two BAs claim `{app}.{module}.{section}` — pick one. Continue. |
+| `build.vite.broken-import` | `npm run build` "Could not resolve `@/…`" | Re-aggregate the registry (Phase 3c) — phantom slipped past. Retry. |
+| `tests.business.fail` | `dotnet test Category=Business` fail with stub still in place | Treat as `business.todo-br`. Retry. |
+| `tests.business.fail-real` | Same, but no stub; the rule is implemented and still rejects a valid example | **DEFER** (blocker `tests.business.disagreement`, `high`). Keep the implemented rule — never weaken the test — and leave it red (the red test IS the signal). `userAction`: BA `validExamples` and impl disagree; reconcile `règles-métier.md` or the rule. Continue. |
+| `tests.acceptance.fail` | `dotnet test Category=Acceptance` fail | Stub still in place → auto-fix as `acceptance.todo-ac`. No stub → **DEFER** (blocker `tests.acceptance.disagreement`, `high`); leave the test red (it is the signal), continue. |
+| `dotnet.config-mismatch` | EF Core Configuration class missing or wrong | Re-run `scaffold-entity` for the entity (idempotent — respects `// @customised`). Retry. |
+| `ba.gap-persistent` | Same auto-fix attempted 2× and gate still red with same fingerprint | **DEFER** (blocker `ba.gap`, `high`). Skip / mark-stub the affected item so downstream phases proceed. `userAction`: BA file lacks data (rule expression empty, AC bullet with no entity ref) — edit `règles-métier.md` / `use-case.md`. Continue. |
+| `wire.frontend-orphan` | `audit-dev-wire` emits `DEV-WIRE-001 err` with `params.calls` referencing a frontend service URL not matched by any backend route | Read the params: if the URL starts with `/api/screens/` → re-invoke `scaffold-screen-controller` for the entity (refresh the pagespecs). If the URL starts with `/api/v1/integration/` → re-invoke `scaffold-controller`. If the URL canonicalises to `unknown` stratum (orphan template artifact) → re-invoke `scaffold-api-client` (legacy `apiBasePath` got removed; the api-client now derives the URL deterministically). Retry. |
+| `wire.strata-mismatch` | `audit-dev-wire` `params.stratum === 'integration'` AND only `{EntityPlural}ScreenController.cs` exists for that entity | Re-invoke `scaffold-api-client` for this entity with `useScreens: true` AND `screenColumns` freshly extracted from pagespecs. Retry. |
+| `wire.verb-mismatch` | Frontend calls VERB X on /api/.../path; backend exposes VERB Y on /api/.../path | **DEFER** (blocker `wire.verb-mismatch`, `high`). Pagespec is the source of truth; leave the call as-is and continue (does not block Phase 4). `userAction`: align the controller or the pagespec on the path. (Future: ACTION-DRIFT-005 will auto-pick once AST-safe-apply lands.) |
+| `smoke.4xx` | `run-smoke` returns a 4xx (other than 401/403) on a probed endpoint | Treat as `wire.frontend-orphan` — the route most likely exists but on a different verb. Retry. |
+| `smoke.5xx` | `run-smoke` returns a 5xx on a probed endpoint | The route exists but the handler throws. Treat as `business.todo-uc` if a TODO marker is on the matching service method, otherwise **DEFER** (blocker `smoke.5xx`, `high`) — leave it, continue (the real bug surfaces in the report). |
+| `smoke.boot` | `run-smoke` returns `passed: false` with reason `backend boot timeout` / `frontend boot timeout` | **DEFER** (blocker `smoke.boot`, `medium`). Skip the runtime probe, keep the static `audit-dev-wire` result. Infra failure — inspect dotnet/npm logs and re-run smoke manually. Continue. |
+| `fk.cross-module-missing` | Phase 3a generated page imports `use<TargetEntity>Lookup` from `@/features/<targetModule>/...`, but the upstream module hasn't been scaffolded (file missing OR file exists but does not export the lookup hook). | Auto-scaffold upstream: invoke `scaffold-api-client` on the target entity (lookup hook is the primary deliverable), then `scaffold-routes` to wire the upstream URL helpers. Continue Phase 3a. If retry budget exhausts, **DEFER** (blocker `fk.cross-module-missing`, `high`) — best-effort skip/guard the unresolved import so the rest of the page compiles; `userAction`: run /ba-develop on <targetModule> first. Pre-flight Phase 3a.0 catches this proactively; the failure kind covers the case where a pagespec FK gets added mid-flight. |
+
+## Defer conditions (never abort the run)
+
+When one of these is hit, the item is **deferred**: the orchestrator takes the
+best-effort action below, records a blocker (see § Blocker log), and continues.
+None of them stops the run or asks the user mid-flight — they all surface in the
+final `blockers[]` instead.
+
+| Defer kind | Best-effort action | Severity |
+|------------|--------------------|----------|
+| `migration.destructive` | Keep the migration, **never auto-apply**; embed `.sql` in the blocker. | critical |
+| `tests.business.disagreement` | Keep the rule, leave the `Category=Business` test red. | high |
+| `tests.acceptance.disagreement` | Leave the `Category=Acceptance` test red (it is the signal). | high |
+| `registry.componentkey-collision` | Keep the first registration, skip the colliding one. | high |
+| `wire.verb-mismatch` | Leave the frontend call as-is (pagespec = source of truth). | high |
+| `ba.gap` | Skip / mark-stub the affected item so downstream phases proceed. | high |
+| `prd.gap` | Implement what the PRD specifies; skip / stub the gap. | high |
+| `prd.not-dev-ready` | Proceed with the build anyway. | high |
+| `fk.cross-module-missing` | Skip/guard the unresolved import; the page still compiles. | high |
+| `smoke.5xx` | Leave the throwing handler; record the failing probe. | high |
+| `smoke.boot` | Skip the runtime probe, keep the static wire audit. | medium |
+| `scaffolder.missing` | Skip that artifact (never improvise a scaffolder). | high |
+| `cli.runtime-error` | Skip that one artifact (never hand-write `.tsx`). | high |
+| `customised-file-conflict` | **Skip the overwrite** — preserve the user's `// @customised` file; embed the diff in the blocker. | medium |
+| `infinite-loop` | Stop retrying this item (fix is broken); skip / stub it. | high |
+| `retry-budget-exhausted` | Stop retrying this item after 25 attempts; skip / stub it. | high |
+| `git.cannot-commit` | Skip commits (branch is `main` / not a repo / other git error); code still lands on disk. | medium |
+
+## Heal log
+
+Each retry pushes one entry to `.smartstack/ba/<APP>/<MODULE>/_dev/heal.log.json`:
+
+```json
+{
+  "phase": "api.2a",
+  "attempt": 4,
+  "failureKind": "business.todo-br",
+  "fingerprint": "f7a3c2…",
+  "fix": "Implemented BR-005 in BudgetService.Validate() from règles-métier.md L42",
+  "outcome": "gate-passed"
+}
+```
+
+The orchestrator's final JSON output includes `healingSummary[]` aggregating
+every retry across every phase — the user sees what was auto-fixed without
+having to read the log.
+
+## Blocker log
+
+Each deferred item pushes one entry to
+`.smartstack/ba/<APP>/<MODULE>/_dev/blockers.json`:
+
+```json
+{
+  "phase": "api.2a",
+  "kind": "tests.business.disagreement",
+  "severity": "high",
+  "summary": "BR-005 rejects a documented valid example",
+  "whatWasSkipped": "left the Category=Business test for BR-005 red",
+  "bestEffortTaken": "kept the implemented rule (did not weaken the test)",
+  "userAction": "reconcile règles-métier.md BR-005 validExamples with the rule",
+  "artifacts": ["src/…/BudgetService.cs:42", "Tests/…/BudgetRuleTests.cs:88"]
+}
+```
+
+`severity` is `critical` (data-loss — only `migration.destructive`), `high`
+(needs a human decision before the feature is correct), or `medium` (infra /
+environment / cosmetic). The orchestrator's final JSON output includes
+`blockers[]` aggregating every deferred item across every phase, and the
+`overallStatus` becomes `completed-with-blockers` whenever `blockers[]` is
+non-empty (see `references/output-contract.md`). This is the ONLY channel for
+surfacing work the user must do — never a mid-run interaction.
+
+## What this changes vs. the prior behavior
+
+**Before Wave G**: any gate failure halted → user fixes → user re-runs. Slow,
+manual, broke flow.
+
+**Wave G**: 80%+ of typical failures (TODO markers, missing methods, import
+resolution, audit-applyable findings, i18n missing keys, migration name
+collision) are healed in 1-3 retries, transparently — but genuinely structural
+failures still HARD HALTED and asked the user (regenerate the PRD, edit a BA
+file, review a migration). That broke the autonomy contract.
+
+**Now (never-halt protocol)**: nothing hard-halts. Healable failures are healed
+as before; genuinely structural failures are **deferred** — the safest
+best-effort action is taken, a blocker is recorded, and the run continues to the
+end of the module. The user is never interrupted mid-run; everything that needs
+a human decision waits in `blockers[]` until the final report. **The run always
+completes — `halted` is not a reachable outcome.**
+
+## Anti-patterns specific to the protocol
+
+- **Halting the run, or asking the user mid-flight** (regenerate the PRD, edit a
+  BA file, pick a key, review a migration). There is no hard-halt list any more:
+  every unhealable failure is a deferred item + a blocker. The orchestrator must
+  reach the end of the module unconditionally.
+- **Increasing the retry budget beyond 25** to "force it through". The 25-retry
+  ceiling exists so a genuinely incorrigible item is deferred (not spun on
+  forever). Cranking it to 100 masks a real problem before finally deferring.
+- **Swallowing a deferred item silently.** A defer is not a success — it MUST
+  push a blocker so the user sees it in the final report. Best-effort ≠ done.

package/templates/skills/ba-develop/references/commit-checkpoints.md

@@ -0,0 +1,79 @@
+# `/ba-develop` — Commit checkpoints
+
+> Loaded on demand when a phase passes and the orchestrator emits a commit.
+
+## Commit command
+
+After every phase whose gate passes, create a local commit directly with git
+via Bash, run in `projectPath`:
+
+```bash
+git add -A && git commit -m "<message>"
+```
+
+**No push** — the feature branch stays local until the user runs `/gitflow pr`
+or `/gitflow sync`. Before committing, confirm the working branch is a feature
+branch (not `main`) — if it is not, **skip commits** and record a
+`git.cannot-commit` blocker (the code still lands on disk). If Phase 2 produced
+an EF migration, review it for destructive ops (DROP COLUMN/TABLE): commit it
+anyway but record a `migration.destructive` blocker (critical) and **never
+auto-apply** the migration. None of these stop the run.
+
+- Conventional-commits scope = the module code (e.g. `hr.leave`).
+- Never push from this orchestrator.
+
+## When NOT to commit
+
+- Gate failed AND auto-healing exhausted — the item is **deferred** (blocker +
+  best-effort). Commit whatever DID pass in the phase; the deferred item is
+  recorded in `blockers[]`, never committed as if it were done.
+- `nothing to commit` — re-running a phase that produced no diff. Log
+  `nothing to commit`, continue.
+
+**Exception — Phase 3 sub-phase 3.5 (audit-apply) MUST always run** even when
+3.0-3c reported no file changes. Drift can exist in files no generator touched
+this run. Skipping audit-apply is the silent re-run failure mode users report
+as "I re-ran and nothing was fixed".
+
+## Per-phase message templates
+
+| After phase | Message |
+|-------------|---------|
+| Core | `feat({appCode}): add core foundation seed (nav + roles + permissions)` |
+| Entities | `feat({moduleCode}): add domain entities + migrations` |
+| API (2a) | `feat({moduleCode}): add api controllers + business handlers` |
+| API (2b) | `feat({moduleCode}): add screen-driven controllers + screen DTOs` |
+| Frontend | `feat({moduleCode}): add frontend pages + routes` |
+| Acceptance | `feat({moduleCode}): add acceptance tests from AC (N facts, 0 TODO)` |
+
+## Auto-healed commit body
+
+When the auto-healing loop ran one or more retries before the gate passed,
+append a body line summarising what was fixed:
+
+```
+feat(hr.leave): add api controllers + business handlers
+
+Auto-healed in 3 iterations:
+  attempt 1 → business.todo-br (BR-005 implemented from règles-métier.md L42)
+  attempt 2 → audit-dev-api.applicable (DEV-API-008 auto-applied, 4 findings)
+  attempt 3 → gate passed
+```
+
+The body lines come straight from `_dev/heal.log.json` — no hand-editing.
+
+## Failure handling
+
+Interpret the `git commit` result:
+
+- **success** → record the short hash (`git rev-parse --short HEAD`) in the
+  phase summary, continue.
+- **not a git repo** OR **branch is `main`** → **skip commits**, record a
+  `git.cannot-commit` blocker (medium, `userAction: run /gitflow start
+  feature/{moduleCode} then commit`), and keep generating — the code still
+  lands on disk. Do NOT halt.
+- **`nothing to commit, working tree clean`** → no-op, log, continue.
+- **destructive EF migration detected** in Phase 2 review → commit it, record a
+  `migration.destructive` blocker (critical), never auto-apply. Continue.
+- **any other error** → record a `git.cannot-commit` blocker with the message,
+  continue (a commit failure never aborts the run).

package/templates/skills/ba-develop/references/gates.md

@@ -0,0 +1,380 @@
+# `/ba-develop` — Per-phase gates
+
+> Loaded on demand when running a specific phase's gate. The SKILL.md just
+> mentions "gates between phases enter the auto-healing loop on failure".
+
+A phase passes **only if all these hold**. **When a gate fails, the phase
+enters the auto-healing loop** (see `references/auto-healing.md`) — it does
+NOT halt. A failure that cannot be healed is **deferred** (a blocker is
+recorded, the safest best-effort action is taken) and the run continues. No
+gate failure ever stops the orchestrator or asks the user mid-run — everything
+that needs a human decision waits in `blockers[]` until the final report.
+
+## Pre-entry coverage checks (Phases 0-2) — BEFORE skip decision
+
+On re-runs, Phases 0-2 were historically skipped when artifacts exist and
+gates pass. This missed PRD additions (new entities, new attributes, new
+custom actions) that arrived between runs. The pre-entry coverage check
+closes this gap by comparing the PRD/BA spec against what is actually on
+disk BEFORE deciding to skip.
+
+**The check runs BEFORE launching any subagent** — it uses fast,
+deterministic tools (< 5 seconds total) so no agent context is wasted on
+a phase that genuinely needs no work.
+
+### Decision flow (applies to Phases 0, 1, 2a, 2b individually)
+
+```
+if artifacts_do_not_exist:
+    → ENTER phase (first run)
+elif pre_entry_coverage_check() has ERR findings:
+    → RE-ENTER phase (PRD has items not yet implemented)
+elif compile_and_test_gate_passes:
+    → SKIP phase (everything implemented, everything green)
+else:
+    → RE-ENTER phase (existing code is broken)
+```
+
+### Phase 0 — Core Foundation Seed coverage
+
+1. **Module navigation coverage** (mirrors DEV-CORE-002): Grep
+   `CoreNavigationSeedDataProvider.cs` for every module code declared
+   in the BA `index.md` tree. Any BA module WITHOUT a matching
+   `NavigationModule.Create(... code: "{moduleCode}" ...)` line → ERR.
+2. **Permission floor** (mirrors DEV-CORE-004): Read
+   `CorePermissionsSeedDataProvider.cs`, group permission tuples by
+   module segment. Compare against modules declared in `rbac.md`. Any
+   BA module with < 2 permissions → ERR.
+
+If ANY check returns ERR → Phase 0 MUST re-enter.
+
+### Phase 1 — Entities coverage
+
+Run `project-inventory`:
+```bash
+npx tsx skills/validation/project-inventory/cli/project-inventory/index.ts \
+  --project-path "<projectPath>" --domains domain
+```
+
+1. **Entity existence** (mirrors DEV-DOM-001): for each entity declared
+   in `entité.md`, check `report.domain.entities[].name`. Any BA entity
+   NOT in the inventory → ERR.
+2. **Attribute completeness** (mirrors DEV-DOM-002): for each entity
+   that IS in the inventory, Read its `.cs` file and verify every
+   attribute from `entité.md` has a matching `public <Type> <Name>`
+   property. Any missing attribute → ERR.
+
+If ANY check returns ERR → Phase 1 MUST re-enter.
+
+### Phase 2a — API Integration coverage
+
+1. **Controller existence** (mirrors DEV-API-001): run
+   `project-inventory --domains api`. For each entity in `entité.md`
+   that the PRD declares should have an API surface, verify a matching
+   controller in `report.api.controllers[].className`. Missing → ERR.
+2. **Custom action coverage** (DEV-API-010): run the audit CLI:
+   ```bash
+   npx tsx skills/development/audit-dev-api/cli/audit-dev-api/index.ts \
+     --project-path "<dotnet-root>" \
+     --module-path  "<moduleDir>" \
+     --module-code  "{moduleCode}" \
+     --app-code     "{appCode}" \
+     --mode audit \
+     --rules DEV-API-010
+   ```
+   Parse JSON stdout. Any `findings[].severity === "err"` → ERR.
+
+If ANY check returns ERR → Phase 2a MUST re-enter.
+
+### Phase 2b — API Screen-driven coverage
+
+Run the audit CLI:
+```bash
+npx tsx skills/development/audit-dev-api/cli/audit-dev-api/index.ts \
+  --project-path "<dotnet-root>" \
+  --module-path  "<moduleDir>" \
+  --module-code  "{moduleCode}" \
+  --app-code     "{appCode}" \
+  --mode audit \
+  --rules DEV-API-012
+```
+Parse JSON stdout. Any `findings[].severity === "err"` on DEV-API-012
+(pagespec view missing its endpoint on screen controller) → ERR.
+
+If no screen controllers exist at all (Phase 2b never ran), the CLI
+emits `ok` — this is NOT a coverage gap but a first-run signal.
+
+If ANY check returns ERR → Phase 2b MUST re-enter.
+
+### Interaction with `--force`
+
+`--force` affects Phase 3 only. It does NOT bypass coverage checks for
+Phases 0-2 because they auto-detect PRD changes. The two mechanisms
+are orthogonal:
+
+| Scenario | Phases 0-2 | Phase 3 |
+|----------|------------|---------|
+| PRD unchanged, no --force | SKIP | Re-enter (always) |
+| PRD changed, no --force | RE-ENTER | Re-enter |
+| PRD unchanged, --force | SKIP | Full regen |
+| PRD changed, --force | RE-ENTER | Full regen |
+
+### Performance budget
+
+Each pre-entry check MUST complete in < 5 seconds:
+- `project-inventory` runs in < 2 s (regex-based, no LLM).
+- `Grep` on Core providers is instant (single file).
+- `audit-dev-api` CLI runs in < 3 s (glob + regex, no LLM).
+
+Total overhead for all 4 checks: < 15 seconds.
+
+## After Phase 0 (Core Foundation Seed)
+- `.NET build` succeeds (the 5 generated `Core/*SeedDataProvider.cs` files
+  reference SmartStack NuGet types only — should compile in isolation).
+- `verifyCoreFoundationSeed` PASSES every per-module check:
+  - Each declared module has a `NavigationModule.Create(... code: "{moduleCode}" ...)`
+    call in `CoreNavigationSeedDataProvider.cs`.
+  - `CoreRolesSeedDataProvider.cs` contains ≥ 1 `Role.Create(... applicationId: {Pascal}ApplicationId ...)`
+    for the application.
+  - `CorePermissionsSeedDataProvider.cs` contains ≥ 2 permission tuples per
+    declared module (access + read floor).
+- `DependencyInjection.cs` (or sibling) carries the 5
+  `services.AddScoped<IClientSeedDataProvider, Core*SeedDataProvider>()` lines
+  between `<<< CORE-SEED-DI BEGIN/END >>>` markers.
+
+> Phase 0 is deterministic. The agent does not write any `.cs` — `scaffold-core-seed`
+> does. If the gate fails, root cause is upstream (stale CoreSeedSpec) — rebuild
+> the spec and re-run. Hand-editing the Core providers is forbidden.
+
+## After Phase 1 (Entities)
+- `.NET build` succeeds.
+- Every entity in `structured.entities[]` has a `.cs` under `Domain/{ModuleCode}/`.
+- Every entity has an EF Core Configuration registered via
+  `ApplyConfigurationsFromAssembly`.
+- EF migration created under the appropriate `Migrations.{Provider}` project —
+  `dotnet ef migrations script` generates valid SQL.
+- Module-scoped reference-data providers under
+  `Persistence/Seeding/Modules/{ModuleCode}/` are OPTIONAL (only required for
+  pre-populated lookup tables). Soft warning — nav/roles/perms are Phase 0's job.
+- `scaffold-tests --layer=domain` produced ≥ 1 `{Entity}Tests.cs` per entity
+  and `dotnet test --filter "Category=Domain&FullyQualifiedName~{ModuleCode}"` passes.
+
+## After Phase 2a (API Integration)
+- `.NET build` still succeeds.
+- Every controller carries `[RequirePermission]` matching a path from
+  `structured.permissions[]`.
+- Integration tests for CRUD on each entity pass
+  (`dotnet test --filter "Category=Integration&FullyQualifiedName~{ModuleCode}"`).
+- **BLOCKING** — Business-rule tests pass
+  (`dotnet test --filter "Category=Business&FullyQualifiedName~{ModuleCode}"`) —
+  one `[Theory]` per `structured.businessRules[]` entry, fed by
+  `validExamples` / `invalidExamples`. Non-negotiable.
+- **BLOCKING — No residual stubs**:
+  `grep -rn "NotImplementedException\|TODO\[BR-\|TODO\[UC-"` across
+  `src/{Ns}.Application` + `src/{Ns}.Infrastructure` returns nothing.
+  Audit DEV-API-008/009 perform the same check with structured findings.
+- **BLOCKING — Business-rule test parity**: count of `Category=Business` test
+  cases ≥ number of rules in `règles-métier.md`. (Vacuous "0 rules → 0 tests
+  → green" is disallowed.)
+- **BLOCKING — Use-case action coverage**: every custom action linked to a
+  `UC-…` has a service method with a real body + `// UC-…` trace comment.
+- **BLOCKING — `audit-dev-api --mode audit` returns 0 `err`**:
+  ```bash
+  npx tsx skills/development/audit-dev-api/cli/audit-dev-api/index.ts \
+    --project-path "<dotnet-root>" \
+    --module-path  "<absolute path to .smartstack/ba/{appCode}/{moduleCode}>" \
+    --module-code  "{moduleCode}" \
+    --app-code     "{appCode}" \
+    --mode audit
+  ```
+  Runs DEV-API-010 (every pagespec `kind:api` non-CRUD has a matching
+  `[HttpVerb]` on the integration controller) + DEV-API-011 (no phantom
+  endpoint). An `err` here = orchestrator's custom-action derivation skipped
+  an entry — auto-heal applies the derivation, retries; if still red,
+  `ba.gap-persistent` → DEFER (blocker `ba.gap`, high), continue.
+
+## After Phase 2b (API Screen-driven)
+- `.NET build` still succeeds with every new `{EntityPlural}ScreenController.cs`
+  + `{Entity}{View}ScreenDto.cs` compiled.
+- Every pagespec in `<MODULE>/pagespecs/` has a matching endpoint on its
+  `{EntityPlural}ScreenController`.
+- The Swagger document group `screens` lists exactly N endpoints, where N =
+  count of pagespecs with view ∈ {list, detail, form, dashboard} + sum of
+  `actions[]` `kind:api` entries.
+- No `// TODO[SCREEN-` markers in generated controllers (audit-dev-api
+  DEV-API-012/013 BLOCKING).
+- Every screen-driven endpoint calls the SAME `I{Entity}Service` exposed by
+  Phase 2a (DEV-API-014 enforces structurally — no parallel service forks).
+- `dotnet test --filter "Category=Acceptance"` still green (no AC regression).
+
+## Phase 3 pre-entry — MANDATORY even on re-runs
+
+### Normal mode (no `--force`) — targeted re-gen via spec-diff ∪ disk-drift
+
+Phase 3 ALWAYS re-enters this gate, but on a re-run it regenerates only the
+**delta**, not all 28 pages. This is the frontend pendant of the Phases 0-2
+`pre_entry_coverage_check` (§ above): compute what genuinely needs work BEFORE
+fanning out, so a single-label edit costs ~15 s instead of ~3 min.
+
+The regeneration set is the **union of two independent drifts**:
+
+**A. Spec-drift** — `compute-page-diff` (pure, < 1 s, no LLM):
+```bash
+npx tsx skills/ba-develop/cli/compute-page-diff/index.ts \
+  --spec '{"moduleRoot":"<.smartstack/ba/{appCode}/{moduleCode}>"}'
+```
+Reads `report.diff.{added,modified,unchanged,removed}` and
+`report.toRegenerate` (= `added ∪ modified`). On the first run there is no
+`.run-snapshot.json` (`snapshotFound:false`) → every page is `added` →
+regenerate all, naturally.
+
+**B. Disk-drift** — close the **silent-skip class**. A page whose pagespec
+hash is `unchanged` can still have a drifted `.tsx` (deleted, hand-edited into
+an err state, broken i18n/import). For **each** key in `report.diff.unchanged`,
+run `validate-page` on its `.tsx`:
+```bash
+npx tsx skills/development/frontend/component/cli/validate-page/index.ts \
+  --project-path "<web-root>" --page-file "<src/pages/{appLower}/{module}/{section}/{Entity}{View}Page.tsx>"
+```
+`validate-page` returns an `err` for a **missing** file too (it short-circuits
+to `imports-resolve: pageFile does not exist`), and for the
+`cli-generated-marker` rule — so a page that exists but was NOT produced by
+`scaffold-component` (no `@generated-by` header) counts as drift. Any
+`unchanged` page with ≥ 1 `err` → add it to the disk-drift set.
+
+**Decision flow** (mirrors `gates.md` Phases 0-2 lines 23-34):
+```
+regenerate = unique( report.toRegenerate  ∪  disk-drift )
+if regenerate == [] :
+    → SKIP Phase 3a   (spec AND disk both clean — the real perf win)
+else :
+    → RE-ENTER Phase 3a for the entities owning a page in `regenerate`,
+      regenerating exactly those views (see phases-detail.md § Phase 3a loop)
+```
+`removed` pages (pagespec gone, `.tsx` orphaned) are logged as a non-blocking
+warning — not auto-deleted (git is the backup; the BA-side `reconcile-menu`
+owns orphan removal).
+
+**This gate is NOT optional.** The orchestrator MUST NOT skip Phase 3 on
+artifact presence alone — skip requires BOTH an empty spec-diff AND zero
+disk-drift. The `@generated-by scaffold-component` marker is the proof of
+provenance; `validate-page` enforces it on every `unchanged` page.
+
+**After a successful regeneration** (Phase 3 build gate green), write the new
+baseline so the NEXT run diffs against it:
+```bash
+npx tsx skills/ba-develop/cli/update-snapshot/index.ts \
+  --spec '{"moduleRoot":"<.smartstack/ba/{appCode}/{moduleCode}>"}'
+```
+Snapshot the run ONLY after success — a failed run must never poison the baseline.
+
+### `--force` mode
+
+When `forceMode = true`, skip the spec-diff + validate-page scan entirely.
+Re-enter Phase 3 from sub-phase 3.0 unconditionally. In Phase 3a, the skip
+rule is disabled — every entity × every view invokes `scaffold-component` and
+`scaffold-api-client` even if the files already exist. The CLIs overwrite in
+place; no files are deleted. `update-snapshot` still runs after the build gate
+so the baseline reflects the forced regeneration.
+
+The run report logs every overwritten file under `phase3.regeneratedFiles[]`.
+
+## After Phase 3 (Frontend)
+- `validate-page` returns success for every page under
+  `src/pages/{appLower}/{module}/` — ALL pages, not just those written during
+  the current run.
+- `audit-dev-frontend --mode audit` returns **0 `err` findings** after the
+  apply pass. Remaining `warn` are tolerated.
+- `npm run build` passes (Vite resolves every
+  `lazyWithRetry(() => import('@/…'))` — catches broken imports that
+  type-check misses).
+- Every screen code from `structured.screens[]` has a `.tsx` under
+  `src/pages/…` or `src/features/…`.
+- Every `PageRegistry.register(key, lazyWithRetry(() => import('@/…')))` in
+  `src/extensions/*Registry*.ts` resolves to an existing file.
+- **BLOCKING — ComponentKey sanity**: every registered key MUST match the
+  shape `{appCode}.{module}.{section}[.{view}]` and MUST equal a
+  `componentKey` returned by `GET /api/navigation/menu`. Verify with:
+  ```bash
+  curl -s -b $cookie -H "X-Tenant-Slug: $tenant" \
+    http://localhost:5142/api/navigation/menu \
+    | jq '.. | .componentKey? // empty' | sort -u
+  ```
+  Forbidden patterns (silent spinner with no console error):
+  - kebab-case: `'contacts-directory'` → must be `'crm.contacts.directory'`
+  - missing app prefix: `'contacts.directory'` → must be `'crm.contacts.directory'`
+  - single segment: `'directory'` → must be `'crm.contacts.directory'`
+  - appCode-prefixed legacy `'TestV2.crm.contacts.directory'` is wrong (appCode
+    is the **navigation app code** lowercased, not the .NET project name)
+- `src/main.tsx` imports `./extensions/componentRegistry.generated` (side-effect
+  import — triggers `register()` at startup).
+- The `apiClient.ts` reads tenant from `localStorage.getItem('currentTenantSlug')`
+  (NOT `tenant_slug`), uses `withCredentials: true` (SmartStack auth = httpOnly
+  cookies), does NOT auto-redirect on 401 (let `SmartStackProvider` handle).
+- Every route in `structured.permissions[]` is registered in the dynamic router
+  (backend `NavigationConfiguration` seed — Phase 0).
+- Locale parity: every `t('key')` in generated pages resolves in fr/en/it/de.
+- `npm test` — component tests pass (one per page from `scaffold-tests
+  --layer=frontend`).
+
+## After Phase 3e (Wire-up gate — static parity + runtime smoke)
+
+Inserted after Phase 3 build gate; runs before Phase 4 boots. Two-step
+gate, fast then slow:
+
+### Step 1 — `audit-dev-wire` (static, ~1 s)
+
+- **Gate (defer-not-halt)** — runs the URL parity audit defined in
+  `templates/skills/development/audit-dev-wire/SKILL.md`. Cross-references
+  every URL the generated frontend calls against every route the generated
+  backend exposes.
+- Pass condition: `report.counts.errors == 0` (zero `DEV-WIRE-001 err`).
+- Failure routes to auto-healing via `wire.frontend-orphan` or
+  `wire.strata-mismatch` (see `references/auto-healing.md`). Auto-fix
+  re-invokes the appropriate scaffolder; a `wire.verb-mismatch` that cannot be
+  reconciled is **deferred** as a blocker (high), not a stop.
+- Invocation:
+  ```bash
+  npx tsx skills/development/audit-dev-wire/cli/audit-dev-wire/index.ts \
+    --project-path "<dotnet-root>" \
+    --web-path     "<web-root>" \
+    --module-code  "<MODULE>" \
+    --app-code     "<APP>" \
+    --mode audit
+  ```
+
+### Step 2 — `run-smoke` (runtime, ~30-120 s)
+
+- **Gate (defer-not-halt)** — boots `dotnet run` + `npm run dev` in background,
+  probes every page route + API endpoint, flags any `4xx`/`5xx`.
+- Pass condition: `report.passed == true` AND `report.failedProbes == 0`.
+- Failure routes to auto-healing via `smoke.4xx` / `smoke.5xx` / `smoke.boot`;
+  an unhealable failure is **deferred** as a blocker (`smoke.5xx` high,
+  `smoke.boot` medium) — the run continues, it never stops here.
+- Skips boot if Step 1 already emitted `err` findings (no point booting a
+  backend known to be missing routes).
+- Boot timeout default: 120 s per service (configurable). A boot timeout is a
+  `medium` blocker (infra), never a stop.
+
+The smoke gate is additive — it never bypasses the static audit. Both feed
+Phase 3's result; an unhealable failure on either is **deferred** as a blocker,
+so Phase 3 always completes and the run moves on to Phase 4.
+
+## After Phase 4 (Acceptance Tests)
+- `scaffold-tests-from-ac` returned `success: true` with `factsEmitted == acsParsed`.
+- **`audit-dev-tests` returns `success: true`** (all of DEV-TEST-001/002/003 are
+  `ok` or `warn`, no `err`):
+  ```bash
+  npx tsx skills/development/audit-dev-tests/cli/audit-dev-tests/index.ts \
+    --spec '{"moduleDir":"<moduleDir>","projectPath":"<projectPath>"}' --json
+  ```
+  - DEV-TEST-001 (err) — every BA AC has a generated `[Fact]`.
+  - DEV-TEST-002 (err) — no `// TODO[AC-` markers remain.
+  - DEV-TEST-003 (warn) — no stale `[Trait("AC", "<ref>")]` references.
+- `dotnet test --filter "Category=Acceptance"` ideally returns 0 failures. Tests
+  failing because the production code does not satisfy the AC ARE the signal —
+  auto-heal tries `acceptance.todo-ac` first; persistent failure with no stub
+  → `tests.acceptance.fail-real` is **deferred** (blocker
+  `tests.acceptance.disagreement`, high): the test stays red and the run continues.
+- `acCoverage` aggregates to `{ total: baAcCount, covered: baAcCount -
+  <DEV-TEST-001.refs>.length, missing: <DEV-TEST-001.refs> }`.