Metadata-Version: 2.4
Name: spec-mdm
Version: 0.3.0
Summary: File-canonical MDM + governed marketplace for Data SDLC -> ADLC agents & skills
License: MIT
Project-URL: Homepage, https://github.com/longddl/spec_mdm
Keywords: mdm,data-engineering,agents,skills,governance,sdlc,adlc
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0
Requires-Dist: jsonschema>=4.0

# spec_mdm — File-canonical MDM + governed marketplace

Spec / rule / `_meta` / backlog management platform for keeping agentic
systems running on approved master data — now also a **governed marketplace
for Data SDLC → ADLC agents & skills**.

**New:** Unified intent-driven CLI following dwarves-kit patterns. One command
does what you need: `spec-mdm <intent>`.

## Quickstart

```bash
pip install spec-mdm

# Validate everything
spec-mdm validate

# List approved skills
spec-mdm list skills --sdlc quality

# Approve an item
spec-mdm approve --kind skill --id SKILL-001 --approver alice

# Install from marketplace
spec-mdm install SKILL-001 --into ~/.codex/skills

# Run safety gates
spec-mdm gate

# Check status
spec-mdm status
```

## Source-of-truth rule

* **Canonical MDM = version-controlled files** in `mdm/` inside the
  customer cluster.
* `runtime/mdm.db` is a **derived projection** — deletable and rebuildable
  from `mdm/`. Never commit it.
* Code holds schemas, validation, connectors, and the approval state
  machine. It never holds customer master rows, PII, or secrets.

## Layout

```text
mdm/
  spec/        # durable intent + solution contracts
  rule/        # executable governance / validation policies
  agent/       # governed Data SDLC -> ADLC agents (AGENT-*.yaml)
  skill/       # governed skills (SKILL-*.yaml, hash-pinned SKILL.md)
  _meta/       # provenance + sync records
  backlog/     # work items derived from / governed by specs & rules
  approvals/   # append-only approval decision events
  _incoming/   # staged candidates
schema/        # JSON Schemas (contracts, not data)
src/spec_mdm/  # validators, loader, connector, approval, monitor, marketplace, gates
scripts/       # unified CLI (spec-mdm.py) + legacy entry points
bin/           # npx shims
docs/          # privacy boundary, deployment, marketplace, decisions, architecture
```

## Unified CLI (Recommended)

**Governance commands:**
```bash
spec-mdm validate                    # Validate all canonical files
spec-mdm approve --kind skill --id SKILL-001 --approver alice
spec-mdm list skills --sdlc quality
spec-mdm install SKILL-001 --into ~/.codex/skills
spec-mdm gate                        # Run mechanical safety gates
spec-mdm status                      # Show current state
```

**Execution commands (optional layer, future):**
```bash
spec-mdm execute BG-001              # Execute backlog item
spec-mdm retro                       # Run retrospective/learning
```

## Legacy CLI (Still Works)

All old commands remain available for backward compatibility:

```bash
spec-mdm-validate
spec-mdm-rebuild
spec-mdm-monitor
spec-mdm-pull
spec-mdm-approve
spec-mdm-marketplace
spec-mdm-promote
```

Or use scripts directly:
```bash
python3 scripts/validate.py
python3 scripts/approve.py --kind skill --id SKILL-001 ...
python3 scripts/marketplace.py list --sdlc quality
```

## Mechanical Gates

The unified CLI includes mechanical safety gates that block dangerous operations:

- Secret key detection in canonical files
- Validation before status changes
- Runtime files not committed to git
- Approval required for status changes

Run `spec-mdm gate` to check all gates.

## Lifecycle

Spec/Rule/Agent/Skill: `draft → in_review → approved → deprecated | superseded`
Backlog: `proposed → ready → in_progress → done | blocked`
Approval decisions: `approved | rejected | changes_requested`

Unapproved content is never presented as operational truth. Agents keep
running on last-known-good approved content; new/unknown changes queue as
pending and the system reports degraded mode explicitly.

## Privacy

* No data leaves the customer cluster. Connectors are read-only and local.
* No credentials, tokens, API keys, PII, generated DBs, or model outputs
  are committed. See `docs/privacy-boundary.md`.
* Marketplace stores manifests + hashes only; SKILL.md bodies are hashed,
  never copied into canonical records. See `docs/marketplace.md`.

## Architecture

See `ARCHITECTURE.md` for the hybrid design combining solid MDM governance
with optional execution layer inspired by dwarves-kit patterns.
