@open-mercato/cli 0.6.7 → 0.6.8-canary.319.1.5b4be4bc52

package/dist/agentic/shared/ai/skills/tiers.json

@@ -3,30 +3,146 @@
   "default": ["core"],
   "external": {
     "source": "open-mercato/skills",
-    "description": "Skills installed from the shared open-mercato/skills collection via `npx skills add` (see scripts/install-skills.sh). Only the subset this standalone app ships is installed. A folder under .ai/skills/ matching one of these names is a repo-local override read by the external skill, never symlinked into the harness directories.",
+    "ref": "c6103c034571f3610323a1b53d97c81abe110b58",
+    "description": "Tier-selected delivery workflows installed at an exact tested collection commit. Same-name folders under .ai/skills are repo-local overrides and never replace these copies.",
+    "tiers": {
+      "core": {
+        "description": "Smallest dependency-closed set for daily standalone delivery.",
+        "skills": [
+          "om-spec-writing",
+          "om-code-review",
+          "om-integration-tests",
+          "om-prepare-test-env",
+          "om-auto-create-pr",
+          "om-auto-continue-pr",
+          "om-auto-review-pr",
+          "om-auto-implement-spec",
+          "om-auto-qa-pr",
+          "om-auto-fix-issue",
+          "om-verify-in-repo",
+          "om-root-cause",
+          "om-fix",
+          "om-open-pr",
+          "om-setup-agent-pipeline"
+        ]
+      },
+      "automation": {
+        "description": "Opt-in loop engines, issue authoring, and release-upgrade maintenance.",
+        "skills": [
+          "om-apply-upgrade-notes",
+          "om-auto-create-pr-loop",
+          "om-auto-continue-pr-loop",
+          "om-auto-write-spec",
+          "om-prepare-issue"
+        ]
+      }
+    },
     "skills": [
+      "om-spec-writing",
+      "om-code-review",
+      "om-integration-tests",
+      "om-prepare-test-env",
       "om-apply-upgrade-notes",
-      "om-auto-continue-pr",
-      "om-auto-continue-pr-loop",
       "om-auto-create-pr",
+      "om-auto-continue-pr",
       "om-auto-create-pr-loop",
-      "om-auto-fix-issue",
+      "om-auto-continue-pr-loop",
       "om-auto-review-pr",
-      "om-code-review",
-      "om-fix",
-      "om-integration-tests",
-      "om-open-pr",
+      "om-auto-implement-spec",
+      "om-auto-write-spec",
+      "om-auto-qa-pr",
+      "om-auto-fix-issue",
       "om-prepare-issue",
-      "om-prepare-test-env",
+      "om-verify-in-repo",
       "om-root-cause",
-      "om-setup-agent-pipeline",
-      "om-spec-writing",
-      "om-verify-in-repo"
-    ]
+      "om-fix",
+      "om-open-pr",
+      "om-setup-agent-pipeline"
+    ],
+    "dependencies": {
+      "om-spec-writing": [],
+      "om-code-review": ["om-setup-agent-pipeline"],
+      "om-integration-tests": ["om-prepare-test-env"],
+      "om-prepare-test-env": [],
+      "om-apply-upgrade-notes": ["om-setup-agent-pipeline"],
+      "om-auto-create-pr": ["om-auto-review-pr", "om-setup-agent-pipeline"],
+      "om-auto-continue-pr": ["om-auto-review-pr", "om-setup-agent-pipeline"],
+      "om-auto-create-pr-loop": [
+        "om-auto-continue-pr-loop",
+        "om-auto-review-pr",
+        "om-integration-tests",
+        "om-setup-agent-pipeline"
+      ],
+      "om-auto-continue-pr-loop": [
+        "om-auto-review-pr",
+        "om-integration-tests",
+        "om-open-pr",
+        "om-setup-agent-pipeline"
+      ],
+      "om-auto-review-pr": ["om-code-review", "om-setup-agent-pipeline"],
+      "om-auto-implement-spec": [
+        "om-auto-create-pr",
+        "om-auto-continue-pr",
+        "om-auto-review-pr",
+        "om-auto-qa-pr",
+        "om-setup-agent-pipeline"
+      ],
+      "om-auto-qa-pr": [
+        "om-auto-review-pr",
+        "om-integration-tests",
+        "om-prepare-test-env",
+        "om-setup-agent-pipeline"
+      ],
+      "om-auto-write-spec": ["om-spec-writing", "om-open-pr", "om-setup-agent-pipeline"],
+      "om-auto-fix-issue": [
+        "om-auto-implement-spec",
+        "om-auto-qa-pr",
+        "om-auto-review-pr",
+        "om-verify-in-repo",
+        "om-root-cause",
+        "om-fix",
+        "om-open-pr",
+        "om-setup-agent-pipeline"
+      ],
+      "om-prepare-issue": [
+        "om-auto-write-spec",
+        "om-auto-fix-issue",
+        "om-auto-implement-spec",
+        "om-spec-writing",
+        "om-setup-agent-pipeline"
+      ],
+      "om-verify-in-repo": ["om-setup-agent-pipeline"],
+      "om-root-cause": ["om-setup-agent-pipeline"],
+      "om-fix": ["om-setup-agent-pipeline"],
+      "om-open-pr": ["om-setup-agent-pipeline"],
+      "om-setup-agent-pipeline": []
+    },
+    "contentHashes": {
+      "om-spec-writing": "sha256:80d5def47ff844748b1c7407cae8b8ee8588ccdfaee54022e15de885d59fa398",
+      "om-code-review": "sha256:f4503da210e6e5eb7d79a0972d3922a2888d8aed93e98a1bb73091c0dc2a750e",
+      "om-integration-tests": "sha256:a1385dbb9fe11fe8c7a16dbe8576e44b9e03f34254e5575955d5a6ea862ee741",
+      "om-prepare-test-env": "sha256:ccfeb9accfffeaf35423576aacc08c9a6e3d3b07ecf8f72da694878fb3a571ab",
+      "om-apply-upgrade-notes": "sha256:15d4166a9229ebe15365ad3ef50919443478ef5f4c1f2e7cccbf1b8a61482d0d",
+      "om-auto-create-pr": "sha256:fe5a8ff632234c74cd1b948dfa2f69bf79683df067d3b8bc116d7a954d017138",
+      "om-auto-continue-pr": "sha256:ced195e0e571672188b34322a9c215df225a9a1822e1db27f6b864b01624e66e",
+      "om-auto-create-pr-loop": "sha256:0e7c015705a89e623c4f6865901121404feb1f443e0e096facb2a337ad9d33a5",
+      "om-auto-continue-pr-loop": "sha256:2997eb7cbf131e1b88abf05ad930e793675c3cd1db1fece18438ec21b327c6ef",
+      "om-auto-review-pr": "sha256:c05b3f45de9563faa0561a3a12129f4fda8bb1780f60d1cdcce7383e75e2d1c5",
+      "om-auto-implement-spec": "sha256:f5408771aa3765c9c8f2709f5d17247d9b8fef19fd2461c2fedf25c90bb8cda7",
+      "om-auto-write-spec": "sha256:b0d79e189fef7f5c03540becda01d933f5153e39276988f58f9c1dd81e9887f7",
+      "om-auto-qa-pr": "sha256:bff71bf4020a1e92b56a17f35f9c63c5f8f942e95048d5bbdf5589443c2cbda9",
+      "om-auto-fix-issue": "sha256:8ca990752fc1e73f2a70902d567b94da6c74b15f4e409410aa27ba09b1506521",
+      "om-prepare-issue": "sha256:07dd578b00902e65abb408e233688675cc92d6783af1a43257ebfd2d5be34663",
+      "om-verify-in-repo": "sha256:2fcf67187b129261aeb59b53c8058e95eb91c1f3c0314756ff5f432a34c43a62",
+      "om-root-cause": "sha256:7c14fd6388ff72c8bb058de905264899b7ee9797bb4985b1891ec2da0ec1c815",
+      "om-fix": "sha256:c9eb58f7834026c13f2533ae6fc4987d32a0e3cec1fd7b220b47d7154ee6e804",
+      "om-open-pr": "sha256:18ef43308dd3e5aff2099b38779cb7447ae26b754d31e18a0f49f857bafdcba7",
+      "om-setup-agent-pipeline": "sha256:6f906df68194af5ef4d40ccaf6f4335d44f45ddcffa6e1f36331291ac90377c8"
+    }
   },
   "tiers": {
     "core": {
-      "description": "Daily-driver standalone skills installed by default.",
+      "description": "Daily standalone architecture, implementation, extension, debugging, and harness-maintenance skills.",
       "skills": [
         "om-help",
         "om-implement-spec",
@@ -34,21 +150,27 @@
         "om-module-scaffold",
         "om-data-model-design",
         "om-system-extension",
+        "om-integration-builder",
+        "om-create-ai-agent",
+        "om-build-workflow",
         "om-troubleshooter",
+        "om-framework-context",
+        "om-evolve-harness",
+        "om-judge-agent-session",
+        "om-share-this-session",
         "om-eject-and-customize"
       ]
     },
     "automation": {
-      "description": "Module-management helpers. Opt-in.",
+      "description": "Optional advanced delivery workflows and module-footprint maintenance.",
       "skills": ["om-trim-unused-modules"]
     },
-    "infra": {
-      "description": "Rare, special-case skills.",
-      "skills": ["om-integration-builder"]
-    },
     "migration": {
-      "description": "One-shot, version-pinned migrations. Install only when needed.",
-      "skills": ["om-auto-upgrade-0.4.10-to-0.5.0"]
+      "description": "One-shot, version-pinned migrations. Install only for the named upgrade.",
+      "skills": [
+        "om-auto-upgrade-0.4.10-to-0.5.0",
+        "om-auto-upgrade-0.6.6-to-0.6.7"
+      ]
     }
   }
 }

package/dist/agentic/shared/ai/skills/tiers.schema.json

@@ -1,88 +1,100 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://open-mercato.dev/schemas/skills/tiers.schema.json",
-  "title": "Open Mercato skills tier manifest",
-  "description": "Manifest mapping skill folders under .ai/skills/ to install tiers consumed by scripts/install-skills.sh.",
+  "title": "Standalone Open Mercato skill manifest",
   "type": "object",
   "additionalProperties": false,
-  "required": ["default", "tiers"],
+  "required": ["default", "external", "tiers"],
   "properties": {
-    "$schema": {
-      "type": "string"
-    },
+    "$schema": { "type": "string" },
     "default": {
       "type": "array",
       "minItems": 1,
-      "items": {
-        "type": "string",
-        "minLength": 1
-      },
-      "description": "Tier names installed when install-skills.sh is invoked with no flags."
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/tierName" }
     },
     "agents": {
       "type": "object",
       "additionalProperties": false,
-      "description": "Agent harness settings for install-skills.sh. Skills always install into the canonical .agents/skills/ directory; per-agent symlinks are created only for agents that cannot read it.",
       "properties": {
         "ignore": {
           "type": "array",
-          "description": "Agents whose directories install-skills.sh must never write. Overridden by --ignore-agents.",
-          "items": {
-            "type": "string",
-            "enum": ["claude-code", "codex", "cursor"]
-          }
+          "uniqueItems": true,
+          "items": { "enum": ["claude-code", "codex", "cursor"] }
         }
       }
     },
     "external": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["source", "skills"],
-      "description": "Skills owned by an external collection and installed via `npx skills add` instead of local symlinks. Folders under .ai/skills/ matching these names are repo-local overrides, not installable skills.",
+      "required": ["source", "ref", "tiers", "skills", "dependencies", "contentHashes"],
       "properties": {
-        "source": {
-          "type": "string",
-          "minLength": 1,
-          "description": "The skills package source, e.g. a GitHub owner/repo."
-        },
-        "description": {
-          "type": "string"
+        "source": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$" },
+        "ref": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+        "description": { "type": "string" },
+        "tiers": {
+          "type": "object",
+          "minProperties": 1,
+          "propertyNames": { "$ref": "#/$defs/tierName" },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["description", "skills"],
+            "properties": {
+              "description": { "type": "string", "minLength": 1 },
+              "skills": {
+                "type": "array",
+                "minItems": 1,
+                "uniqueItems": true,
+                "items": { "$ref": "#/$defs/skillName" }
+              }
+            }
+          }
         },
         "skills": {
           "type": "array",
           "minItems": 1,
-          "items": {
-            "type": "string",
-            "pattern": "^[a-z0-9][a-z0-9._-]*$"
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/skillName" }
+        },
+        "dependencies": {
+          "type": "object",
+          "propertyNames": { "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+          "additionalProperties": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": { "$ref": "#/$defs/skillName" }
           }
+        },
+        "contentHashes": {
+          "type": "object",
+          "propertyNames": { "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+          "additionalProperties": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
         }
       }
     },
     "tiers": {
       "type": "object",
       "minProperties": 1,
-      "propertyNames": {
-        "pattern": "^[a-z][a-z0-9-]*$"
-      },
+      "propertyNames": { "pattern": "^[a-z][a-z0-9-]*$" },
       "additionalProperties": {
         "type": "object",
         "additionalProperties": false,
         "required": ["description", "skills"],
         "properties": {
-          "description": {
-            "type": "string",
-            "minLength": 1
-          },
+          "description": { "type": "string", "minLength": 1 },
           "skills": {
             "type": "array",
             "minItems": 1,
-            "items": {
-              "type": "string",
-              "pattern": "^[a-z0-9][a-z0-9._-]*$"
-            }
+            "uniqueItems": true,
+            "items": { "$ref": "#/$defs/skillName" }
           }
         }
       }
     }
+  },
+  "$defs": {
+    "skillName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+    "tierName": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }
   }
 }

package/dist/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` (interactive local) or `om-auto-implement-spec` (whole-spec PR), one dependency-ordered phase at a time; update the Changelog, acceptance evidence, and phase state as work lands. Local delivery confirms its phase-derived plan before coding and ends with the stable `Spec:` reference without implying PR automation.

package/dist/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 |