<!--
Sync Impact Report
- Version change: (template) → 1.0.0
- Modified principles: all placeholders filled (initial ratification)
- Added sections: Core Principles (I–VII), Inherited Hard Constraints, Development Workflow, Governance
- Removed sections: none
- Templates requiring updates:
  ✅ .specify/templates/plan-template.md (Constitution Check gates align — no edits needed)
  ✅ .specify/templates/spec-template.md (no mandatory-section changes)
  ✅ .specify/templates/tasks-template.md (no new task categories required)
- Follow-up TODOs: none
-->

# 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