create-mercato-app 0.6.7-develop.6690.1.d1d863d951 → 0.6.7-develop.6692.1.d0a4413933

package/agentic/guides/backend-ui.md

@@ -26,7 +26,7 @@ For a new editable entity or module, unless the brief explicitly excludes an ope
 
 ## DataTable
 
-- Use `DataTable` with stable colon-form `entityId`, `apiPath`, and `extensionTableId`. These are host contracts, not cosmetic props.
+- Use `DataTable` with a stable colon-form `entityId`, explicit typed data/pagination loaded through shared API helpers, and `extensionTableId`. These are host contracts, not cosmetic props; `DataTable` has no `apiPath` prop.
 - Use shared column helpers, `RowActions` with stable action IDs, built-in filter/search/export/column controls, and DataTable bulk-action surfaces.
 - When owning pagination, wire page, page size, total count, and change handlers together. Do not slice a server page again in the client.
 - Use the table's empty state and shared loading/error components. A successful empty result is not an error.

package/agentic/guides/spec-delivery.md

@@ -0,0 +1,22 @@
+# Specification Delivery
+
+Use this guide for a new application, multi-module feature, or other non-trivial business slice.
+
+## Authoring readiness gate
+
+1. Invoke `om-spec-writing` before authoring or revising. Mentioning the skill or reading only `SPEC-000-template.md` is not sufficient.
+2. After invocation, read `.ai/specs/SPEC-000-template.md` and preserve every section; use `N/A — reason` only when a section genuinely does not apply.
+3. Keep status `Draft` until no blocking open question remains and every requirement maps to an acceptance criterion, implementation phase, and self-contained test oracle.
+4. For each affected UI route, inspect and cite the closest existing Open Mercato page plus `.ai/guides/backend-ui.md`; specify its text mockup/structure, actions, data source and mutations, permissions, canonical shell/components, and loading/empty/error/conflict/keyboard/a11y/responsive/light/dark states. Tabular admin data names `DataTable`; CRUD create/edit names `CrudForm`; backend reads name shared API helpers; every exception has an explicit rationale.
+5. New applications and multi-module requests also define domain vocabulary/invariants, measurable success, navigation/widgets, module ownership and extension points, architecture/data flow, and concrete risk scenarios. A page inventory alone is not an app architecture.
+6. Phases are dependency-ordered complete vertical slices with concrete deliverables, acceptance IDs, bounded slices, tests, validation commands, business value, and observable exit gates. Do not defer required behavior to a catch-all “integration/polish” phase.
+7. Mark the spec `Ready for implementation` only after the traceability and final compliance matrices pass and the user approves implementation.
+
+## Implementation phase gate
+
+- Use `om-implement-spec` for local delivery and `om-auto-implement-spec` for whole-spec PR delivery.
+- Only the current unblocked phase may be in progress. Parallelize independent slices inside that phase only; never start a dependent module/phase before its prerequisite exit gate passes.
+- Delegation does not bypass routing. Before any UI slice, actually invoke `om-backend-ui-design` and read `.ai/guides/backend-ui.md`; naming them in an agent prompt is not invocation. Every implementation brief names the active phase, routed guides/skills, closest reference page, canonical primitives, acceptance IDs, owned files, and validation oracle.
+- Reject raw backend tables/forms/fetch, copied component families, arbitrary values, hard-coded palette/status colors, and light-only styling unless the approved spec records a necessary exception. UI phase evidence exercises affected routes in light and dark mode and at narrow width, including loading/empty/error/conflict and keyboard behavior.
+- A phase remains open while it has stubs, missing integration evidence, unmet acceptance IDs, or failing validation. Generated discovery, file count, and typecheck alone do not prove completion.
+- If no remote/tracker exists, report PR delivery unavailable and invoke local `om-implement-spec` phase-by-phase; never improvise a concurrent whole-spec build.

package/agentic/shared/AGENTS.md.template

@@ -93,7 +93,7 @@ Pinned delivery skills: `yarn install-skills` (refresh: `--update`). Read BOTH `
 
 | Route ID | Delivery need | Skill |
 |---|---|---|
-| `spec-pr` | Write/revise spec | `om-spec-writing` (OMH-005) + exact `.ai/agentic.config.json` for its specs-directory setting |
+| `spec-pr` | Write/revise spec | MUST invoke `om-spec-writing` (OMH-005) + `.ai/guides/spec-delivery.md` + config specs path |
 | `spec-pr` | Implement approved phases locally | `om-implement-spec` (OMH-006) |
 | `spec-pr` | Whole-spec / commit+ready PR / issue / review | `om-auto-implement-spec` / `om-auto-create-pr` / `om-auto-fix-issue` / `om-auto-review-pr` |
 | `testing` | Integration/E2E/UI QA | `om-integration-tests` / `om-auto-qa-pr` |
@@ -105,7 +105,7 @@ Absent skill: run `yarn install-skills` once; never substitute.
 
 - Load matched guides once, then only needed references/facts.
 - Hard budgets: guide > skill > references; open a reference only for its named subject.
-- Specs: list names; open one task match; skip README/template.
+- Specs: open one match; `spec-pr` reads template via spec-delivery.
 - Inspect app call sites before bounded `framework-context`.
 - Additive page/form/table/conflict UI skips it.
 - Never bulk-read guide, skill, fact, or source trees.

package/agentic/shared/ai/skills/om-auto-implement-spec/SKILL.md

@@ -0,0 +1,21 @@
+> **Repo-local override.** This folder extends the external `om-auto-implement-spec` skill installed from `open-mercato/skills`. Apply these standalone readiness and no-remote rules on top of the external workflow; do not install this file as a replacement skill.
+
+# Standalone portability overrides — `om-auto-implement-spec`
+
+Everything tracker-facing uses the operations and guards from `.ai/trackers/github.md`. Resolve an automatic base branch through **default-branch**; never assume `main` or `develop`.
+
+## 1. Audit the resolved spec before choosing an engine
+
+After resolving the spec and before creating implementation tasks, read `.ai/specs/SPEC-000-template.md` and `.ai/skills/om-implement-spec/references/phases-and-gates.md`, then run the complete readiness audit. The spec must be `Ready for implementation`, have no blocking open questions, map every requirement to an acceptance criterion/phase/self-contained test oracle, define every affected UI and API contract, and give every phase dependencies plus an observable exit gate. UI contracts must cite an installed reference and require the platform shell/components, shared API helpers, semantic tokens, and light/dark plus responsive state coverage.
+
+An incomplete or `Draft` spec is not an engine plan. Stop implementation, report the missing readiness items, and route revision through `om-spec-writing`; never fill the gaps inside generated agent prompts.
+
+## 2. Preserve phase dependencies in PR delivery
+
+When a remote and tracker are available, keep the external PR workflow but seed its execution plan from the spec phases. Only the current unblocked phase may be in progress. Parallel agents may own independent slices inside that phase only, and each brief must name routed guides/skills, closest installed reference, canonical primitives, acceptance IDs, owned files, and a validation oracle. Invoke routed skills before delegation, including `om-backend-ui-design` for rendered surfaces. A phase advances only after its integration paths and exit gate pass.
+
+Do not launch one agent per future module, mark blocked phases in progress, or treat generated files/typecheck as proof that a business slice is implemented.
+
+## 3. No-remote fallback is local and phase-safe
+
+Standalone apps commonly start without a Git remote. If the tracker operations cannot resolve a repository/remote, report that PR delivery is unavailable and invoke the local `.ai/skills/om-implement-spec/SKILL.md` against the resolved spec, phase-by-phase. Do not improvise the external PR engine locally, claim a PR exists, or collapse the whole spec into concurrent module scaffolding.

package/agentic/shared/ai/skills/om-implement-spec/SKILL.md

@@ -10,15 +10,19 @@ Leave the app working after every phase and keep implementation traceable to the
 ## Workflow
 
 1. Read the full spec, root `AGENTS.md`, existing related specs, and `references/phases-and-gates.md`; resolve contradictions before coding.
-2. Map each selected phase to Task Router rows and package/module facts. Use `om-framework-context` only for missing exact-version details.
-3. Break work into cohesive dependency-ordered slices. Use one bounded subagent per independent research/implementation/test/review task when available; never let agents overlap files without coordination.
-4. Implement one slice through real call sites, run its focused tests, and update spec/progress evidence before starting dependent work.
-5. Run generation/migration probes at their owning slice. Ask before schema application, dependency changes, public-contract changes, or scope reduction.
-6. Execute integration paths from the spec, then type/lint/test/build gates and a code review. Remediate findings before reporting completion.
+2. Run the reference's readiness audit. A `Draft`, blocking open question, missing requirement traceability, or unspecified UI/API contract returns to `om-spec-writing`; do not infer the missing design while implementing.
+3. Map the selected current phase to Task Router rows and package/module facts. Invoke every routed skill before delegating or coding; for any rendered surface this includes `om-backend-ui-design` and `.ai/guides/backend-ui.md`. A prompt that merely names a skill is not a substitute for loading it. Use `om-framework-context` only for missing exact-version details.
+4. Break only that phase into cohesive dependency-ordered slices. Use one bounded subagent per independent research/implementation/test/review task when available; never let agents overlap files or enter a later phase.
+5. Implement one complete slice through real call sites, run its focused tests, and update spec/progress evidence before starting dependent work.
+6. Run generation/migration probes at their owning slice. Ask before schema application, dependency changes, public-contract changes, or scope reduction.
+7. Close the current phase with its specified integration paths and exit gate. Only then may the next phase enter implementation; after the final phase run type/lint/test/build gates and a code review.
 
 ## Rules
 
 - Do not silently skip acceptance criteria, collapse phases, or treat partial scaffolding as implementation.
+- Only one dependency-ordered phase may be `in_progress`. A phase remains open when it has stubs, failing validation, missing integration evidence, or unmet acceptance IDs, regardless of how many files were generated.
+- Parallel agents may own independent slices inside the active phase only. Every brief names its owned files, routed guides/skills, closest installed reference, canonical primitives, acceptance IDs, and validation oracle.
+- Backend UI must use the platform page shell, `DataTable`/`CrudForm` where their contracts apply, shared API helpers, exported controls, and semantic tokens. Raw tables/forms/fetch, copied component families, arbitrary values, hard-coded palette/status colors, and light-only styling require an approved spec exception.
 - Each completed implementation phase must leave a working app (`working-phases`) and report its smallest focused validation gate (`smallest-validation`); `integration-coverage` belongs to writing the spec, not implementing already approved phases.
 - Preserve compatibility and standalone writable boundaries; never patch installed/generated files.
 - Regression tests must fail before their fix and use self-contained fixtures.

package/agentic/shared/ai/skills/om-implement-spec/references/phases-and-gates.md

@@ -2,11 +2,32 @@
 
 Load this reference before implementation.
 
+## Readiness audit
+
+Before creating implementation tasks, require all of the following:
+
+1. The spec status is `Ready for implementation`, not `Draft`.
+2. No blocking open question is unresolved.
+3. Every requirement maps to an acceptance criterion, phase, and self-contained test oracle.
+4. Every affected UI route cites the closest installed reference and names its structure/mockup, actions, data source/mutations, permissions, canonical shell/components, and loading/empty/error/conflict/keyboard/a11y/responsive/light/dark states. Lists and CRUD surfaces name `DataTable`/`CrudForm` and shared API helpers unless an approved exception explains why they cannot satisfy the interaction.
+5. Every affected API/command names its auth, scope, input, response/event, error, concurrency, and compatibility contracts.
+6. Each phase names dependencies, concrete deliverables, acceptance IDs, tests, validation commands, and an observable exit gate.
+
+If any item is absent, stop implementation and return the spec to `om-spec-writing`. Do not fill design gaps opportunistically in agent prompts.
+
+## Phase state machine
+
 1. Build a requirement-to-phase matrix with acceptance path, affected modules/packages, routed guides/skills, dependencies, BC surfaces, schema impact, and test oracle.
-2. Order by foundations then complete vertical slices. Every phase leaves generation/typecheck/tests working.
-3. Assign independent research, implementation, integration-test, and review tasks to bounded subagents when available; one owner per file/slice.
-4. After each slice, run focused tests and record files/commands/results plus remaining work in the spec/progress artifact.
-5. Run schema probe at the data slice; run generation at each discovery slice; never defer all integration until the end.
-6. Final gate: all spec API/UI paths with self-contained fixtures, affected safety cases, typecheck/lint/test/build, packed standalone boundary when relevant, and code review findings resolved.
+2. Keep phases in `pending → in_progress → verified` order. Only one phase may be `in_progress`; a phase can start only when every declared dependency is `verified`.
+3. Order by foundations and then complete vertical slices. Do not launch one agent per later module or implement all entities/APIs first and postpone their required UI/integration to a catch-all phase.
+4. Inside the active phase, assign only independent research, implementation, integration-test, and review slices to bounded agents. Give each one owned files, routed guides/skills, closest installed reference, canonical primitives, acceptance IDs, and a validation oracle; one owner per file/slice. Invoke routed skills before delegation—especially `om-backend-ui-design` for rendered surfaces—rather than paraphrasing guessed conventions into the prompt.
+5. After each slice, run focused tests and record files/commands/results plus remaining work in the spec/progress artifact. File count, generated discovery, and typecheck alone never prove a business slice works.
+6. Run the schema probe at its data slice and generation at every discovery slice; never defer all integration until the end.
+
+## Phase exit gate
+
+A phase becomes `verified` only when all of its specified deliverables exist through real call sites, no required page is a stub, every mapped acceptance ID is exercised, its self-contained API/UI paths pass, and its focused generation/typecheck/tests are green. For affected UI, compare the result with the cited reference and verify the platform shell/components, shared API helpers, semantic tokens, light/dark themes, narrow width, quality states, keyboard flow, and absence of undocumented raw-table/form/fetch or hard-coded-color substitutes. A failure keeps the phase `in_progress` and blocks every dependent phase.
+
+After the final phase, run all spec API/UI paths with self-contained fixtures, affected safety cases, typecheck/lint/test/build, the packed standalone boundary when relevant, and code review. Resolve findings before reporting completion.
 
 If an acceptance criterion cannot be met without scope/architecture/public-contract change, stop and ask rather than silently revising the spec.

package/agentic/shared/ai/specs/README.md

@@ -21,6 +21,7 @@ Example: 2026-03-01-inventory-module.md
 
 ## Workflow
 
-1. Before coding any significant feature, check for an existing spec
-2. If none: create from SPEC-000-template.md, review with team, then code
-3. After implementation: update the spec's Changelog and Acceptance Criteria
+1. Route every new application, multi-module feature, or non-trivial business slice through `om-spec-writing` and `.ai/guides/spec-delivery.md`.
+2. After invoking the skill, create the skeleton from `SPEC-000-template.md`; keep it `Draft` while blocking questions or incomplete contracts remain.
+3. Set `Ready for implementation` only after the final compliance report and requirement traceability pass and the user approves implementation.
+4. Implement through `om-implement-spec` (local) or `om-auto-implement-spec` (PR), one dependency-ordered phase at a time; update the Changelog, acceptance evidence, and phase state as work lands.

package/agentic/shared/ai/specs/SPEC-000-template.md

@@ -3,33 +3,249 @@
 **Date**: {YYYY-MM-DD}
 **Status**: Draft
 
+> Use `om-spec-writing` for every new application, multi-module feature, or other non-trivial business slice. Keep every section below; write `N/A — {reason}` when a section does not apply. Change the status to `Ready for implementation` only after every blocking open question is resolved and the traceability table covers every requirement.
+
 ## TLDR
 
-{2-3 sentence summary}
+{What is being built, who benefits, which existing Open Mercato capabilities are reused, and the smallest coherent outcome.}
 
 ## Problem Statement
 
-{What problem this feature solves}
+{Current workflow, concrete pain, evidence, affected users, and why existing behavior is insufficient.}
+
+## Overview and Success Measures
+
+- **Primary outcome:** {Measurable business result and target.}
+- **Leading indicators:** {Signals available before the final outcome.}
+- **Baseline:** {Current measurable state or `unknown — measurement plan`.}
+- **Market / product reference:** {Comparable product or workflow studied; what is adopted, rejected, and why.}
+
+## Goals
+
+- **REQ-001** — {Observable business outcome.}
+- **REQ-002** — {Observable business outcome.}
+
+## Non-goals
+
+- {Explicitly excluded behavior, module, integration, or migration.}
 
 ## Proposed Solution
 
-{High-level approach}
+{Describe the product and technical approach, how it closes each stated problem, and why it is the smallest platform-native solution that can deliver the goals.}
+
+### Design Decisions and Alternatives
+
+| Decision | Rationale | Alternative considered | Why rejected / deferred |
+|---|---|---|---|
+| {choice} | {why it fits the requirements and platform} | {alternative} | {tradeoff} |
+
+## Domain Vocabulary and Business Rules
+
+| Term / invariant | Precise meaning or rule | Source of truth | Failure behavior |
+|---|---|---|---|
+| {term} | {one unambiguous meaning, formula, lifecycle, or constraint} | {module/entity/provider} | {reject/degrade/retry/audit} |
+
+Define fields, states, transitions, calculations, ownership, and invariants precisely enough that implementation does not need to invent domain behavior.
+
+## Users, Permissions, and Scope
+
+| Actor | Allowed outcomes | Scope rule | Required feature IDs |
+|---|---|---|---|
+| {actor} | {view/create/update/etc.} | {own/team/organization/system} | `{module}.view`, `{module}.manage` |
+
+Document how trusted `tenantId` and `organizationId` are derived. Describe any legitimate system-scope operation and the installed contract that authorizes it.
+
+## Reuse and Ownership Map
+
+| Capability | Reuse / extend / app-own | Existing module or new module | Integration seam | Why |
+|---|---|---|---|---|
+| {capability} | {reuse/UMES/app-owned} | `{module}` | {ID/snapshot/event/enricher/extension/optional DI} | {decision} |
+
+Name the installed records that remain the source of truth. Do not duplicate CRM, auth, directory, notification, workflow, or other installed capabilities in app-owned entities.
+
+## Architecture and Data Flow
+
+```text
+{actor/surface} -> {API/command} -> {owning entity}
+                                  -> {event/subscriber/integration}
+```
+
+- **Module boundaries:** {Why each new module owns a distinct invariant; merge modules that must remain transactionally consistent.}
+- **Extension points:** {Installed page/menu/widget/enricher/interceptor/event seams used instead of modifying installed code.}
+- **Alternatives considered:** {Simpler platform-native alternative and why it was not selected.}
+- **Compatibility:** {Existing API/data/UI behavior that must remain stable.}
+
+## User Journeys
+
+### Journey J-001 — {Name}
+
+1. {Actor starts from a named page or API.}
+2. {Primary action and system response.}
+3. {Success state and downstream side effects.}
+4. {Recoverable failure, permission denial, conflict, and retry behavior.}
+
+## UI and Interaction Contracts
+
+List every new or changed page before implementation. Inspect the closest existing Open Mercato page and `.ai/guides/backend-ui.md`; record that reference below. Tabular admin data uses `DataTable`, CRUD create/edit surfaces use `CrudForm`, and backend reads use the shared API helpers. Any custom page or component exception needs an explicit rationale and approval in this section.
+
+| Surface / route | Purpose and primary actions | Data source / mutations | Closest installed reference | Canonical shell / components | Required states | Requirement IDs |
+|---|---|---|---|---|---|---|
+| `/backend/{route}` | {list/create/edit/etc.} | `{API paths / command IDs}` | `{module/path or component family}` | `Page`, `PageBody`, `DataTable`, `CrudForm`, {others} | loading, empty, error, conflict, success, permission denied | REQ-001 |
+
+### UI architecture
+
+| Role | Navigation groups in order | Dashboard / injected widgets | Login-to-primary-task flow |
+|---|---|---|---|
+| {role} | {group → item} | {widget, host, click-through} | {page → action → result; target ≤3 clicks} |
+
+| Surface / widget | Empty state guidance and action | Responsive behavior | Keyboard / focus behavior |
+|---|---|---|---|
+| {surface} | {localized explanation + next action} | {narrow/mobile layout} | {focus order, submit/cancel, announcements} |
+
+### `/backend/{route}` — {Page name}
+
+```text
+┌────────────────────────────────────────────────────────────┐
+│ {Page title}                               [{Primary action}]│
+│ {Filters / summary / navigation}                           │
+├────────────────────────────────────────────────────────────┤
+│ {DataTable, CrudForm groups, calendar, or detail sections} │
+├────────────────────────────────────────────────────────────┤
+│ {Pagination / save-delete actions / status feedback}       │
+└────────────────────────────────────────────────────────────┘
+```
+
+- **Behavior:** {sorting/filtering/pagination, validation, keyboard behavior, navigation, destructive confirmation, optimistic-lock conflict recovery.}
+- **Responsive and accessibility:** {focus order, labels, screen-reader status, small-screen behavior.}
+- **Localization:** {translation namespaces and dynamic values.}
+- **Design-system and theming:** {semantic tokens and shared primitives; verify light and dark mode, contrast, reduced motion, and no hard-coded palette/status colors.}
+
+For backend UI, implementation must invoke `om-backend-ui-design` and follow `.ai/guides/backend-ui.md`. Raw `<table>`, raw admin `<form>`, raw `fetch`, copied component families, arbitrary Tailwind values, hard-coded light-only colors, and manual `dark:` patches fail readiness unless the approved contract explains why the platform primitive cannot support the interaction. A custom calendar, board, or clinical workspace may be justified, but its surrounding shell, controls, status treatment, dialogs, states, and tokens remain platform-native.
 
 ## Data Models
 
-{Entity definitions, relationships}
+### `{Entity}`
+
+| Field | Type / nullability | Scope / index | Sensitive / encrypted | Lifecycle and validation |
+|---|---|---|---|---|
+| `id` | UUID, required | primary key | no | immutable |
+| `tenant_id` / `organization_id` | UUID, required | composite scope indexes | no | trusted context only |
+| `updated_at` | timestamp, required | optimistic-lock version | no | updated on every edit |
+
+Document entity ownership, soft-delete or append-only rules, cross-module IDs/snapshots, uniqueness, transactions, encryption maps, retention, migrations, and compatibility impact.
+
+## API, Command, and Error Contracts
+
+| Method / command | Path / ID | Auth and feature gate | Input | Success response / event | Errors and concurrency | Requirement IDs |
+|---|---|---|---|---|---|---|
+| `GET` | `/api/{path}` | auth + `{module}.view` | {query schema} | `{ items, totalCount }` | 400/401/403 | REQ-001 |
+| `POST` | `/api/{path}` | auth + `{module}.manage` | {body schema} | 201 + `{module}.{entity}.created` | 400/403/409 | REQ-002 |
+
+State whether each route uses `makeCrudRoute` or a custom guarded command route. Include per-method `metadata`, OpenAPI schemas, scope derivation, idempotency, optimistic locking, and stable public-contract implications.
+
+## Events, Jobs, Notifications, and Cross-Module Flows
+
+| Trigger | Producer | Consumer | Side effect | Retry / idempotency / audit behavior |
+|---|---|---|---|---|
+| `{module}.{entity}.{action}` | `{module}` | `{subscriber}` | {result} | {contract} |
+
+Describe scheduled work, progress, cache invalidation, failure recovery, and optional-module behavior where applicable.
+
+## Security, Privacy, and Compliance
+
+- **Authorization:** {feature gates and record-level scope; never role-name checks.}
+- **Tenant isolation:** {read/write filters and fail-closed behavior.}
+- **Sensitive data:** {encryption map, safe reads, redaction, retention, audit policy.}
+- **Abuse and failure modes:** {enumeration, injection, replay, concurrency, destructive action, secret exposure.}
+
+## Integration Coverage
+
+Tests must be self-contained and map to real API and UI paths.
+
+| Test ID | Level | Setup / fixture | Actions | Assertions | Requirement IDs |
+|---|---|---|---|---|---|
+| TEST-001 | integration | {tenant/org/users/records} | {API or browser flow} | {success + persisted state + event} | REQ-001 |
+| TEST-002 | security | {second tenant / insufficient feature} | {forbidden read/write} | {fail closed; no data leak} | REQ-001 |
+| TEST-003 | UI | {records and permissions} | {loading/empty/error/conflict/keyboard flow} | {observable result} | REQ-002 |
+
+## Implementation Phases
+
+Phases are dependency ordered. Only the current phase may enter implementation; parallel work is limited to independent slices inside that phase. Each phase must leave a working app and close with its own evidence before the next phase starts.
 
-## API Contracts
+### Phase 1 — {Foundation or first complete vertical slice}
 
-{Endpoints, request/response schemas}
+- **Depends on:** none
+- **Outcome:** {user-visible or independently verifiable result}
+- **Why this order / value delivered:** {dependency and measurable business value available at phase completion}
+- **Deliverables:** {specific entities, commands, routes, pages, subscribers, migrations}
+- **Independent slices / estimated commits:** {bounded work that may run in parallel inside this phase only}
+- **Requirements closed:** REQ-001
+- **Tests:** TEST-001, TEST-002
+- **Validation:** `yarn generate`, {focused typecheck/tests/integration paths}
+- **Exit gate:** {observable criteria proving this phase works end to end, including affected UI in light/dark and narrow-width states}
+
+### Phase 2 — {Next complete vertical slice}
+
+- **Depends on:** Phase 1 exit gate
+- **Outcome:** {result}
+- **Why this order / value delivered:** {dependency and measurable business value}
+- **Deliverables:** {specific files/seams}
+- **Independent slices / estimated commits:** {bounded work inside this phase}
+- **Requirements closed:** REQ-002
+- **Tests:** TEST-003
+- **Validation:** {focused commands}
+- **Exit gate:** {observable criteria}
+
+## Requirement Traceability
+
+| Requirement | Journey / surface | Data/API/event contracts | Phase | Tests | Acceptance criterion |
+|---|---|---|---|---|---|
+| REQ-001 | J-001, `/backend/{route}` | `{entity}`, `GET /api/{path}` | Phase 1 | TEST-001, TEST-002 | AC-001 |
+
+Every requirement must map to a phase, at least one test oracle, and a measurable acceptance criterion. No phase may be a catch-all “integration and polish” bucket for behavior required by earlier slices.
+
+## Rollout, Migration, and Rollback
+
+{Migration generation/application boundary, seed/setup work, feature flags, compatibility bridge, observability, rollout order, and reversible rollback steps.}
+
+## Risks and Tradeoffs
+
+| Risk / tradeoff | Impact | Mitigation / detection | Residual risk |
+|---|---|---|---|
+| {risk} | {impact} | {test/metric/guard} | {accepted remainder} |
+
+Cover data integrity and concurrency, cascading/event failures, tenant isolation and privacy, migration/rollback, external-service degradation, scale/storage, and operational detection. Do not use “standard risks” as a substitute for concrete failure scenarios.
 
 ## Acceptance Criteria
 
-- [ ] {Criterion 1}
-- [ ] {Criterion 2}
+- [ ] **AC-001** — {Measurable end-to-end result, including actor and scope.}
+- [ ] **AC-002** — {Measurable failure/safety result.}
+- [ ] Every listed backend surface matches its recorded Open Mercato reference and uses the canonical shell/components, shared API helpers, semantic tokens, and complete loading, empty, error, conflict, keyboard, accessibility, responsive, light-mode, and dark-mode states.
+- [ ] Every affected API and UI path has self-contained integration coverage and the configured validation gate passes.
+
+## Final Compliance Report
+
+| Check | Status | Evidence / resolution |
+|---|---|---|
+| Applicable `AGENTS.md` files and routed guides/skills reviewed | pass/fail | {paths} |
+| Data models, APIs, events, UI, and tests are internally consistent | pass/fail | {traceability rows} |
+| Every workflow completes end to end without a catch-all integration phase | pass/fail | {journeys/phases} |
+| Platform-native reuse and extension points were chosen before custom code | pass/fail | {reuse decisions} |
+| UI contracts identify references, canonical components, and theme/state coverage | pass/fail | {surfaces} |
+| Every phase has dependencies, bounded slices, tests, value, and an observable exit gate | pass/fail | {phases} |
+
+Verdict must be exactly `Ready for implementation` or `Blocked — {unresolved items}`. The document status may change to ready only when every row passes.
+
+## Open Questions
+
+Blocking questions must be resolved before setting `Status: Ready for implementation`.
+
+| ID | Question | Owner | Blocking? | Resolution / decision date |
+|---|---|---|---|---|
+| Q-001 | {question} | {owner} | yes/no | {pending or decision} |
 
 ## Changelog
 
 | Date | Change |
-|------|--------|
-| {date} | Initial spec |
+|---|---|
+| {date} | Initial draft |

package/dist/agentic/guides/backend-ui.md

@@ -26,7 +26,7 @@ For a new editable entity or module, unless the brief explicitly excludes an ope
 
 ## DataTable
 
-- Use `DataTable` with stable colon-form `entityId`, `apiPath`, and `extensionTableId`. These are host contracts, not cosmetic props.
+- Use `DataTable` with a stable colon-form `entityId`, explicit typed data/pagination loaded through shared API helpers, and `extensionTableId`. These are host contracts, not cosmetic props; `DataTable` has no `apiPath` prop.
 - Use shared column helpers, `RowActions` with stable action IDs, built-in filter/search/export/column controls, and DataTable bulk-action surfaces.
 - When owning pagination, wire page, page size, total count, and change handlers together. Do not slice a server page again in the client.
 - Use the table's empty state and shared loading/error components. A successful empty result is not an error.