m2-market/.specify/memory/constitution.md

M2 Marketplace Constitution

Core Principles

I. Assembly Over Greenfield

Every marketplace component MUST be built on an existing fleet asset when one exists (CONCEPT.md §3 asset map): package format rides fedlearn m2-core-manifest, the semantic catalog is a memory-api/Qdrant partition, the storefront evolves cargstore, identity rides fleet.json tenancy, metering federates with the m2-gpt gateway. A proposal to build a new component MUST first document why the existing asset cannot be extended. The only sanctioned genuinely-new service in the first wedge is m2-ledger.

II. Protocol + Registry, Not One App

The marketplace is a protocol with layered surfaces, never a monolith: Forgejo holds truth (listings = versioned repo releases; review = PRs; veto = labels), memory-api indexes meaning (market:catalog), cargstore/M2 Store renders, Hermes and the Solution Scout speak it in-session, and the m2-market CLI automates it. No surface may become a second source of truth; anything derivable from the registry MUST be rebuildable from it.

III. Evidence-Backed Listings (NON-NEGOTIABLE)

Every listing MUST carry provenance: machine/session origin, tokens/time cost telemetry, and outcome evidence. No listing enters market:catalog without passing the curation pipeline (auto-curate → scored PR → human veto → merge) with the commercialize disposition. Junk resistance is structural, not moderational: ratings and proposal→install conversion feed back onto listings as quality signals.

IV. Tenant Firewall & Commons Boundary (NON-NEGOTIABLE)

Client/tenant data MUST NEVER cross into the shared catalog or core. Tenant-derived work may be commercialized only owner-initiated and doubly-scrubbed. Fleet-infrastructure learnings stay free in shared m2-core; only outcome-shaped packages become priced Solutions. The Scout is opt-in per desktop, on-box summarization only, never raw keystrokes or raw client data, rate-limited, and propose-only — the install click is always the human's.

V. Ledger Integrity

All value movement flows through one append-only ledger: transactions {ts, from, to, amount, reason, ref} with balances derived, never stored authoritatively. Daily balance snapshots MUST be committed to Forgejo for audit. Internal credits only — no public coin, exchange, or custody. Installs debit before apply: no license grant without a recorded transaction.

VI. Canary-First, Reversible Deployment

The host fleet is fragile (see /home/m2/CLAUDE.md): every install/apply MUST be idempotent and reversible, rolled out canary-first (chris-m2o, gunnar-m2o), and MUST NOT require fleet-wide blasts. Runtime-sync is the only universal install path across mixed desktop images. New marketplace services deploy as Coolify apps on the coolify network. No secrets in repos or images; keys injected at runtime.

VII. Simplicity & Sequenced Wedges

Build the smallest thing that closes the loop (§12 first wedge), sequenced behind the fedlearn MVP rails it depends on. SQLite before Postgres, manual payout reconciliation before automation, fixed pricing before metering, one canary before the fleet. Features beyond the current wedge (public web marketplace, external payments, metered pricing) are explicitly deferred, not half-built.

Inherited Hard Constraints

• Tenant isolation (sdjs=GST, etc.) is inviolable — see Principle IV.
• Mixed desktop images (primus vs agent-latest): runtime-sync is the only universal path.
• Harness-agnostic where cheap: marketplace touchpoints live behind the m2-gpt gateway or as skills, not inside one agent harness (Hermes first, never Hermes-only).
• Coolify local registry self-redirects (302): primus-style images build local-only.
• fedlearn MVP artifacts (schemas, m2/m2-core repo, memory-api auth, sync/apply) are the dependency rails; marketplace work MUST consume, not fork, them.

Development Workflow

• Spec-driven: no non-trivial implementation without spec → plan → tasks (spec-kit factory loop); tasks.md is the only source of implementation slices; workers stay within their assigned task's scope.
• Every requirement in a spec maps to at least one task; acceptance criteria in spec.md gate convergence, not just passing tests.
• Review gates: /speckit.analyze CRITICAL findings block merge; P1 review findings fixed before report; curation veto applies to listings exactly as to core contributions.
• Operator decisions (CONCEPT.md §14 open forks) are recorded with their chosen resolution in the relevant spec; recommended defaults may be assumed but MUST be flagged until the operator confirms.

Governance

This constitution supersedes ad-hoc practice for all m2-market work. Amendments are made by PR to this file with a Sync Impact Report, semantic version bump (MAJOR: principle removal or redefinition; MINOR: new principle or materially expanded guidance; PATCH: clarification), and propagation across .specify/templates/*. Compliance is checked at every plan's Constitution Check gate and at converge. Complexity beyond a wedge's scope MUST be justified in the plan or deferred.

Version: 1.0.0 | Ratified: 2026-07-02 | Last Amended: 2026-07-02