@open-mercato/cli 0.6.7-develop.6863.1.61001cf9a8 → 0.6.7

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

@@ -3,146 +3,30 @@
   "default": ["core"],
   "external": {
     "source": "open-mercato/skills",
-    "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"
-        ]
-      }
-    },
+    "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.",
     "skills": [
-      "om-spec-writing",
-      "om-code-review",
-      "om-integration-tests",
-      "om-prepare-test-env",
       "om-apply-upgrade-notes",
-      "om-auto-create-pr",
       "om-auto-continue-pr",
-      "om-auto-create-pr-loop",
       "om-auto-continue-pr-loop",
-      "om-auto-review-pr",
-      "om-auto-implement-spec",
-      "om-auto-write-spec",
-      "om-auto-qa-pr",
+      "om-auto-create-pr",
+      "om-auto-create-pr-loop",
       "om-auto-fix-issue",
-      "om-prepare-issue",
-      "om-verify-in-repo",
-      "om-root-cause",
+      "om-auto-review-pr",
+      "om-code-review",
       "om-fix",
+      "om-integration-tests",
       "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"
-    }
+      "om-prepare-issue",
+      "om-prepare-test-env",
+      "om-root-cause",
+      "om-setup-agent-pipeline",
+      "om-spec-writing",
+      "om-verify-in-repo"
+    ]
   },
   "tiers": {
     "core": {
-      "description": "Daily standalone architecture, implementation, extension, debugging, and harness-maintenance skills.",
+      "description": "Daily-driver standalone skills installed by default.",
       "skills": [
         "om-help",
         "om-implement-spec",
@@ -150,27 +34,21 @@
         "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": "Optional advanced delivery workflows and module-footprint maintenance.",
+      "description": "Module-management helpers. Opt-in.",
       "skills": ["om-trim-unused-modules"]
     },
+    "infra": {
+      "description": "Rare, special-case skills.",
+      "skills": ["om-integration-builder"]
+    },
     "migration": {
-      "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"
-      ]
+      "description": "One-shot, version-pinned migrations. Install only when needed.",
+      "skills": ["om-auto-upgrade-0.4.10-to-0.5.0"]
     }
   }
 }

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

@@ -1,100 +1,88 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://open-mercato.dev/schemas/skills/tiers.schema.json",
-  "title": "Standalone Open Mercato skill manifest",
+  "title": "Open Mercato skills tier manifest",
+  "description": "Manifest mapping skill folders under .ai/skills/ to install tiers consumed by scripts/install-skills.sh.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["default", "external", "tiers"],
+  "required": ["default", "tiers"],
   "properties": {
-    "$schema": { "type": "string" },
+    "$schema": {
+      "type": "string"
+    },
     "default": {
       "type": "array",
       "minItems": 1,
-      "uniqueItems": true,
-      "items": { "$ref": "#/$defs/tierName" }
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Tier names installed when install-skills.sh is invoked with no flags."
     },
     "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",
-          "uniqueItems": true,
-          "items": { "enum": ["claude-code", "codex", "cursor"] }
+          "description": "Agents whose directories install-skills.sh must never write. Overridden by --ignore-agents.",
+          "items": {
+            "type": "string",
+            "enum": ["claude-code", "codex", "cursor"]
+          }
         }
       }
     },
     "external": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["source", "ref", "tiers", "skills", "dependencies", "contentHashes"],
+      "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.",
       "properties": {
-        "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" }
-              }
-            }
-          }
+        "source": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The skills package source, e.g. a GitHub owner/repo."
+        },
+        "description": {
+          "type": "string"
         },
         "skills": {
           "type": "array",
           "minItems": 1,
-          "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" }
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9._-]*$"
           }
-        },
-        "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,
-            "uniqueItems": true,
-            "items": { "$ref": "#/$defs/skillName" }
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z0-9][a-z0-9._-]*$"
+            }
           }
         }
       }
     }
-  },
-  "$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,7 +21,6 @@ Example: 2026-03-01-inventory-module.md
 
 ## Workflow
 
-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.
+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

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

@@ -3,249 +3,33 @@
 **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
 
-{What is being built, who benefits, which existing Open Mercato capabilities are reused, and the smallest coherent outcome.}
+{2-3 sentence summary}
 
 ## Problem Statement
 
-{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.}
+{What problem this feature solves}
 
 ## Proposed Solution
 
-{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.
+{High-level approach}
 
 ## Data Models
 
-### `{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.
+{Entity definitions, relationships}
 
-### Phase 1 — {Foundation or first complete vertical slice}
+## API Contracts
 
-- **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.
+{Endpoints, request/response schemas}
 
 ## Acceptance Criteria
 
-- [ ] **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} |
+- [ ] {Criterion 1}
+- [ ] {Criterion 2}
 
 ## Changelog
 
 | Date | Change |
-|---|---|
-| {date} | Initial draft |
+|------|--------|
+| {date} | Initial spec |