@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/ba-develop/references/output-contract.md

@@ -0,0 +1,95 @@
+# `/ba-develop` — Output contract
+
+> Loaded on demand when the orchestrator emits its final summary.
+
+Emit one JSON object describing the entire run:
+
+```json
+{
+  "moduleDir": ".smartstack/ba/<APP>/<MODULE>",
+  "moduleCode": "…",
+  "forceMode": false,
+  "memoriesCleaned": [],
+  "phase3": { "regeneratedFiles": [] },
+  "phases": [
+    { "name": "core",       "status": "passed",            "artifacts": [...], "gatesPassed": ["build", "core-foundation-seed"], "warnings": [], "commitHash": "a1b2c3d", "healIterations": 0 },
+    { "name": "entities",   "status": "passed",            "artifacts": [...], "gatesPassed": ["build", "entities-present", "migration-valid", "configs-registered"], "warnings": [], "commitHash": "e4f5a6b", "healIterations": 0 },
+    { "name": "api",        "status": "passed-after-heal", "artifacts": [...], "gatesPassed": ["build", "permissions-wired", "tests-pass", "business-tests-pass"], "warnings": [], "commitHash": "c7d8e9f", "healIterations": 3 },
+    { "name": "frontend",   "status": "passed-after-heal", "artifacts": [...], "gatesPassed": ["build", "screens-present", "routes-registered", "tests-pass"], "warnings": [], "commitHash": "01a2b3c", "healIterations": 1 },
+    { "name": "wire",       "status": "passed",            "artifacts": ["_audit/dev-wire-<module>.md"], "gatesPassed": ["audit-dev-wire", "run-smoke"], "warnings": [], "commitHash": null, "healIterations": 0, "wireReport": { "scope": "devWire", "findings": [], "counts": { "errors": 0, "warnings": 0, "oks": 1 } }, "smokeReport": { "passed": true, "totalProbes": 18, "passedProbes": 18, "failedProbes": 0, "backendBootMs": 4200, "frontendBootMs": 2800 } },
+    { "name": "acceptance", "status": "passed",            "artifacts": ["Tests/<Module>/Acceptance/*.cs"], "gatesPassed": ["scaffold-emitted", "no-todo-marker", "dotnet-test-pass", "ac-coverage-complete"], "warnings": [], "commitHash": "12abf3d", "factsEmitted": 14, "acsParsed": 14, "healIterations": 0 }
+  ],
+  "healingSummary": [
+    { "phase": "api",      "attempt": 1, "failureKind": "business.todo-br",              "fix": "Implemented BR-005 in BudgetService.Validate() from règles-métier.md L42" },
+    { "phase": "api",      "attempt": 2, "failureKind": "audit-dev-api.applicable",      "fix": "Auto-applied DEV-API-008 (4 findings)" },
+    { "phase": "api",      "attempt": 3, "failureKind": null,                             "outcome": "gate-passed" },
+    { "phase": "frontend", "attempt": 1, "failureKind": "validate-page.i18n-keys-resolve","fix": "Re-scaffold-component for EmployeeListPage with priorErrors (i18n keys added)" }
+  ],
+  "blockers": [
+    { "phase": "preflight", "kind": "prd.not-dev-ready", "severity": "high", "summary": "PRD score 72/100 (< 80)", "whatWasSkipped": "nothing — proceeded best-effort", "bestEffortTaken": "ran all phases on the current PRD", "userAction": "run /ba-audit-prd, fix findings, regenerate the PRD", "artifacts": ["_audit/prd.md"] }
+  ],
+  "acCoverage": { "total": 14, "covered": 14, "missing": [] },
+  "nonGoalViolations": [],
+  "overallStatus": "completed-with-blockers"
+}
+```
+
+## Field reference
+
+`commitHash` — short hash from `git rev-parse --short HEAD` after the phase
+commit. Omit when no diff (do NOT fabricate).
+
+`status` (per phase):
+- `passed` — gate passed on first try, no heal.
+- `passed-after-heal` — gate passed after N retries (see `healIterations`).
+- `completed-with-blockers` — the phase ran to the end but ≥ 1 item was
+  **deferred**; see `blockers[]` filtered to this phase. The phase is NOT a stop.
+- `skipped` — re-run; pre-entry coverage confirmed all PRD items are
+  implemented AND compile + test gate passed. No work needed.
+
+There is no `halted` status — the run always completes.
+
+`healIterations` — number of retries this phase consumed (0 when no auto-heal
+needed).
+
+`healingSummary[]` — cross-phase aggregation of every retry from
+`_dev/heal.log.json` so the user sees what was auto-fixed without reading the
+log.
+
+`forceMode` — `true` when the user passed `--force`. Affects Phase 3 only.
+
+`memoriesCleaned[]` — list of memory file names rewritten during pre-flight
+memory cleanup (e.g. `["ba-develop-phase3-cli-stack-mismatch.md"]`). Empty when
+no stale memories found.
+
+`phase3.regeneratedFiles[]` — files overwritten during `--force` mode
+(pages, api-client services, i18n files). Empty in normal mode.
+
+`phases[].wireReport` (Phase 3e only) — JSON envelope from
+`audit-dev-wire/cli/audit-dev-wire`. Includes `findings[]` (every
+`DEV-WIRE-001 err`/`warn`/`ok`) + `counts.errors|warnings|oks`. A non-zero
+`counts.errors` triggers the `wire.frontend-orphan` / `wire.strata-mismatch`
+auto-healing kinds.
+
+`phases[].smokeReport` (Phase 3e only) — JSON envelope from
+`smoke-test/cli/run-smoke`. Includes `passed`, `backendBootMs`,
+`frontendBootMs`, `totalProbes`, `passedProbes`, `failedProbes`, and
+`probes[]` with status + `failureReason`. A non-zero `failedProbes`
+triggers `smoke.4xx` / `smoke.5xx` / `smoke.boot` auto-healing.
+
+`overallStatus`:
+- `success` — no warnings, all ACs covered, no heal needed, no blockers.
+- `success-after-heal` — gates passed but ≥ 1 phase needed heal iterations; no blockers.
+- `success-with-warnings` — gates passed, coverage gaps or minor warnings; no blockers.
+- `completed-with-blockers` — the run reached the end of the module but ≥ 1 item
+  was **deferred** (see `blockers[]`). This is the terminal state for any run
+  that hit a structural issue — it is NOT a failure to complete. `halted` is
+  never emitted; the run always finishes.
+
+`blockers[]` — every deferred item across every phase, aggregated from
+`_dev/blockers.json`. Each entry: `{ phase, kind, severity (critical | high |
+medium), summary, whatWasSkipped, bestEffortTaken, userAction, artifacts[] }`.
+This is the ONLY channel for work the user must do — `/ba-develop` never asks
+mid-run. After the JSON, print a short human recap, e.g.:
+`⚠ 2 blockers — 1 critical (review migration M_xxx before applying), 1 high
+(regenerate the frontend PRD slice for Demande).`