|
| 1 | +# mcpt-marketing |
| 2 | + |
| 3 | +Deterministic marketing data layer for MCP Tool Shop. Schema-validated claims, hash-addressed evidence, and reproducible marketing builds. |
| 4 | + |
| 5 | +Internally, the schema and IR layer is called **MarketIR** — a structured intermediate representation of tools, audiences, claims, evidence, messages, and campaigns. |
| 6 | + |
| 7 | +## Ground Rules |
| 8 | + |
| 9 | +These rules are non-negotiable. CI enforces them. |
| 10 | + |
| 11 | +### IDs are stable and permanent |
| 12 | + |
| 13 | +- IDs follow a namespace pattern: `tool.<slug>`, `aud.<name>`, `claim.<tool>.<slug>`, `ev.<tool>.<slug>.v<n>`, `msg.<tool>.<slug>`, `camp.<tool>.<slug>` |
| 14 | +- IDs are **never renamed**. Deprecate instead (`status: "deprecated"`) |
| 15 | +- All IDs must be unique across the entire graph |
| 16 | + |
| 17 | +### Claims must declare status |
| 18 | + |
| 19 | +Every claim has a `status`: |
| 20 | + |
| 21 | +| Status | Meaning | |
| 22 | +|--------|---------| |
| 23 | +| `proven` | Backed by at least one `evidenceRef` | |
| 24 | +| `aspirational` | Believed true, evidence not yet captured | |
| 25 | +| `deprecated` | No longer valid — kept for audit trail | |
| 26 | + |
| 27 | +**Proven claims require evidence.** If a claim is `proven`, it must reference at least one entry in the evidence manifest. CI rejects proven claims with zero evidence. |
| 28 | + |
| 29 | +### Evidence is hash-addressed |
| 30 | + |
| 31 | +Every evidence artifact includes: |
| 32 | + |
| 33 | +- `sha256` hash of the file content |
| 34 | +- `bytes` size |
| 35 | +- `provenance` object: who/what generated it, from which commit, and any notes |
| 36 | + |
| 37 | +This makes evidence tamper-evident and reproducible. |
| 38 | + |
| 39 | +### The lockfile is canonical |
| 40 | + |
| 41 | +`marketing/manifests/marketing.lock.json` pins every included file by hash. CI regenerates the lockfile and fails if it differs from what's committed. This guarantees reproducible "marketing releases." |
| 42 | + |
| 43 | +### Messages must trace to claims |
| 44 | + |
| 45 | +Every message should be derivable from claims. If a message asserts something not represented as a claim, that's a schema violation enforced by validation. |
| 46 | + |
| 47 | +### Deterministic serialization |
| 48 | + |
| 49 | +All JSON files use: |
| 50 | + |
| 51 | +- Stable key ordering (sorted) |
| 52 | +- Stable array ordering (by ID) |
| 53 | +- Trailing newline |
| 54 | + |
| 55 | +This prevents "same data, different diff" noise. |
| 56 | + |
| 57 | +## Repo Structure |
| 58 | + |
| 59 | +``` |
| 60 | +marketing/ |
| 61 | + schema/ # JSON Schema (2020-12) definitions |
| 62 | + data/ |
| 63 | + tools/ # One file per tool |
| 64 | + campaigns/ # One file per campaign |
| 65 | + audiences/ # One file per audience |
| 66 | + evidence/ # Evidence artifacts (screenshots, reports) |
| 67 | + manifests/ # evidence.manifest.json + marketing.lock.json |
| 68 | + scripts/ # validate, hash, gen-lock |
| 69 | +``` |
| 70 | + |
| 71 | +## Usage |
| 72 | + |
| 73 | +```bash |
| 74 | +npm install |
| 75 | +node marketing/scripts/validate.mjs # Schema + invariant checks |
| 76 | +node marketing/scripts/gen-lock.mjs # Regenerate lockfile |
| 77 | +node marketing/scripts/gen-lock.mjs --check # Fail if lock differs (CI mode) |
| 78 | +``` |
| 79 | + |
| 80 | +## License |
| 81 | + |
| 82 | +MIT |
0 commit comments