@antoneeo/mkt-agentic-sdlc-skill 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.2.0 — 2026-07-09 (v1.0 hardening)
+
+- **Deterministic doctrine gate**: `scripts/test_skill_invariants.py` asserts the load-bearing invariants (three guarantees, review red-flags R1/R11b/R15, elicitation rules, research URL rule, parseable template tokens, sales-led funnel guidance, support-file wiring). Fails on a real regression.
+- **Opt-in behavioral eval layer**: `evals/run_behavioral.py` (zero-LLM driver) + 6 scenarios (triage/escalation, owned-facts elicitation, no-number-without-ledger, swap-test enforced, low-cost-trap flagged, no-guaranteed-success). Mirrors the sibling skill.
+- **Contrast validation (B2B sales-led)**: second synthetic eval on a business unlike the first — the Vision Alignment / amendment discipline caught and held a deliberate vision-divergence (self-serve tier) instead of absorbing it.
+- **Calibration from the contrast run**: sales-led/B2B funnel guidance (funnel output = qualified demos not closed customers; separate pipeline build-up table; closed-won lag) in `frameworks.md` + `templates.md`; B2B firmographic-ICP + buying-committee variant in `templates.md`.
+- ENFORCEMENT.md §5/§6 updated to run both deterministic batteries + the behavioral layer.
+
+## 0.1.0 — 2026-07-09
+
+Initial release.
+
+- Operating contract `SKILL.md`: Marketing Values, Rule Zero engagement triage (E1/E2/E3/Spike), dual operating modes (Standalone `mkt_docs/`, Hybrid devPNT), E3 nine-phase SOSTAC workflow with user gates, adversarial review gates and mechanical validation.
+- Support files: `frameworks.md` (framework selection guide), `elicitation.md` (question waves, only-facts-you-own rule), `research.md` (research playbook + evidence ledger discipline), `templates.md` (all artifact templates), `review.md` (CMO review discipline + marketing red flags), `ENFORCEMENT.md`.
+- Mechanical validator `scripts/mkt_check.py`: `check`, `validate`, `ledger`, `budget`, `funnel`, `trace`, `index`.
+- npm packaging: `mkt-sdlc-init` (project scaffold), `mkt-sdlc-install-skill` (multi-client skill install: Claude Code, Gemini CLI, Codex, Google Antigravity).

package/README.md

@@ -0,0 +1,45 @@
+# Marketing Agentic SDLC Skill
+
+Evidence-First marketing planning protocol for AI coding agents (Claude Code, Gemini CLI, Google Antigravity, Codex). The sibling of [`@antoneeo/agentic-sdlc-skill`](https://www.npmjs.com/package/@antoneeo/agentic-sdlc-skill), transplanted from software engineering to marketing strategy.
+
+## What it does
+
+Turns an AI agent into a disciplined marketing strategist that produces a professional, professionally-recognized marketing plan (SOSTAC structure) with three engineered guarantees:
+
+1. **Evidence ledger** — every market number is classified FACT / BENCHMARK / ASSUMPTION and carries an `[EV-nn]` reference to its source. No invented numbers.
+2. **Mechanical validator** (`mkt_check.py`) — budget sums, funnel math and the objective→tactic→KPI chain are checked mechanically, not rhetorically.
+3. **Adversarial CMO review** — an independent, fresh-context reviewer attacks the strategy before the user sees it (generic-positioning swap test, untraced claims, orphan tactics).
+
+The agent asks the user only for facts the user uniquely owns (product, price, budget, capacity); everything else — market sizing, competitor analysis, channel benchmarks — is derived from real web research.
+
+## Install
+
+```bash
+npm i -g @antoneeo/mkt-agentic-sdlc-skill
+mkt-sdlc-install-skill   # copies the skill into every detected AI client
+```
+
+Initialize a project:
+
+```bash
+cd my-business-project
+npx mkt-sdlc-init        # creates mkt_docs/ + protocol pointers
+```
+
+## Engagement levels (Rule Zero)
+
+| Level | Scope | Process |
+|---|---|---|
+| E1 Quick | single question / asset feedback | direct answer, sourced numbers |
+| E2 Campaign | one campaign or channel plan | mini-brief + targeted research + campaign doc |
+| E3 Full Plan | complete marketing plan | full SOSTAC workflow, 9 phases, all gates |
+| Research Spike | time-boxed market question | `mkt_docs/spikes/RESEARCH_[topic].md` |
+
+## Modes
+
+- **Standalone** — everything on the filesystem under `mkt_docs/`.
+- **Hybrid with devPNT** — plans and strategy artifacts governed as versioned devPNT documents (MKT-VISION, ICP/Personas, Threat Map, Strategy, Tactical Plan, Measurement Plan), with proposal/approval workflow and independent review gates.
+
+## License
+
+MIT — Antonio Pinto

package/gemini-extension.json

@@ -0,0 +1,6 @@
+{
+  "name": "mkt-agentic-sdlc",
+  "version": "0.2.0",
+  "description": "Evidence-First marketing planning protocol with engagement triage, SOSTAC workflow, evidence ledger and optional devPNT integration.",
+  "author": "Antonio Pinto (https://github.com/Antoneeo)"
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@antoneeo/mkt-agentic-sdlc-skill",
+  "version": "0.2.0",
+  "description": "Evidence-First marketing planning protocol for Claude Code, Gemini CLI, Google Antigravity and Codex: engagement triage, SOSTAC workflow, evidence ledger, mechanical validator and optional devPNT integration.",
+  "keywords": [
+    "claude-code",
+    "claude-skill",
+    "gemini-cli",
+    "skill",
+    "marketing",
+    "marketing-plan",
+    "sostac",
+    "ai-agent"
+  ],
+  "author": "Antonio Pinto (https://github.com/Antoneeo)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "mkt-sdlc-init": "scripts/init.js",
+    "mkt-sdlc-install-skill": "scripts/postinstall.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "preuninstall": "node scripts/preuninstall.js"
+  },
+  "files": [
+    "skills/mkt-agentic-sdlc/SKILL.md",
+    "skills/mkt-agentic-sdlc/frameworks.md",
+    "skills/mkt-agentic-sdlc/elicitation.md",
+    "skills/mkt-agentic-sdlc/research.md",
+    "skills/mkt-agentic-sdlc/templates.md",
+    "skills/mkt-agentic-sdlc/review.md",
+    "skills/mkt-agentic-sdlc/ENFORCEMENT.md",
+    "skills/mkt-agentic-sdlc/scripts/mkt_check.py",
+    "gemini-extension.json",
+    "README.md",
+    "CHANGELOG.md",
+    "scripts/lib.js",
+    "scripts/init.js",
+    "scripts/postinstall.js",
+    "scripts/preuninstall.js"
+  ]
+}

package/scripts/init.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { SKILL_SOURCE, CLIENTS, clientDetected, loadTemplates, templateFor } = require('./lib');
+
+const cwd = process.cwd();
+
+// 1. Directory layout (canonical mkt_docs structure)
+const directories = [
+  'mkt_docs',
+  'mkt_docs/vision',
+  'mkt_docs/research',
+  'mkt_docs/strategy',
+  'mkt_docs/tactics',
+  'mkt_docs/deliverables',
+  'mkt_docs/audit',
+  'mkt_docs/spikes',
+].map((d) => path.join(cwd, d));
+
+// 2. Project protocol (thin pointer — the operating contract is the skill).
+// Deliberately short: duplicating the skill's rules here made them drift.
+const protocolContent = `# Marketing Agentic SDLC — Project Protocol (pointer)
+
+This project follows the Marketing Agentic SDLC Evidence-First process. The full
+operating contract is the \`mkt-agentic-sdlc\` skill (installed in your agent's
+skills directory); this file is only the minimal always-on pointer.
+
+## Rule Zero — Triage every request
+- E1 Quick: single question or asset feedback (positioning opinion, copy critique). Answer directly; numbers still need a source.
+- E2 Campaign: single-campaign or single-channel plan. Light path: mini-brief + targeted research + campaign document.
+- E3 Full Plan: complete marketing plan. Full SOSTAC workflow via the skill: Discovery -> Research -> Situation -> Objectives -> Strategy -> Tactics -> Action -> Control -> Packaging.
+- Research Spike: time-boxed market question; outcome in \`mkt_docs/spikes/RESEARCH_[topic].md\`.
+- When in doubt, pick the higher level. Declare the chosen level when starting.
+
+## The three non-negotiables
+1. Evidence ledger: every market number carries an [EV-nn] reference (FACT / BENCHMARK / ASSUMPTION). No invented numbers, ever.
+2. Ask only what the user owns: facts come from the user, analysis comes from research. Never ask the user to do the analysis.
+3. Internal consistency: budget sums, funnel math and the objective->tactic->KPI chain are validated mechanically before delivery.
+
+## Where things live
+- Vision (gate for E3): \`mkt_docs/vision/MKT_VISION.md\` — \`Status: DRAFT\` informs, \`Status: APPROVED\` binds.
+- Evidence: \`mkt_docs/research/evidence_ledger.md\` (the single source for every number).
+- Strategy artifacts: \`mkt_docs/strategy/\`; tactical artifacts: \`mkt_docs/tactics/\`; final deliverables: \`mkt_docs/deliverables/\`.
+- Must-reads: \`mkt_docs/README.md\`; full generated manifest: \`mkt_docs/INDEX.md\`.
+- If devPNT is available for this project, its M-VISION / plans / governed artifacts take over (Hybrid mode — see the skill).
+
+## Closure gate
+Deliverables ship only after \`python <skill_dir>/scripts/mkt_check.py check\` is
+CLEAN (where the validator is adopted) and the CMO review passed.
+
+If the mkt-agentic-sdlc skill is not available in this client, ask the user to install it:
+\`npm i -g @antoneeo/mkt-agentic-sdlc-skill && mkt-sdlc-install-skill\`
+`;
+
+console.log('🚀 Initializing Marketing Agentic SDLC workflow...');
+
+// 3. Load templates from the single source (skill's templates.md)
+let sections;
+try {
+  sections = loadTemplates();
+} catch (err) {
+  console.error(`❌ Cannot load templates: ${err.message}`);
+  process.exit(1);
+}
+
+let seedFiles;
+try {
+  seedFiles = [
+    ['mkt_docs/README.md', templateFor(sections, 'mkt_docs/README.md')],
+    ['mkt_docs/vision/MKT_VISION.md', templateFor(sections, 'MKT_VISION.md')],
+    ['mkt_docs/vision/principles.md', templateFor(sections, 'principles.md')],
+    ['mkt_docs/research/evidence_ledger.md', templateFor(sections, 'evidence_ledger.md')],
+    // NOTE: INDEX.md is NOT seeded — it is generated by `mkt_check.py index`
+    // and would immediately fail validate.
+  ];
+} catch (err) {
+  console.error(`❌ ${err.message}`);
+  process.exit(1);
+}
+
+// 4. Create directories
+directories.forEach((dir) => {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+    console.log(`📁 Created directory: ${path.relative(cwd, dir)}`);
+  }
+});
+
+// 5. Write seed files (never overwrite)
+const writeIfNotExists = (relPath, content, description) => {
+  const filePath = path.join(cwd, relPath);
+  if (!fs.existsSync(filePath)) {
+    fs.writeFileSync(filePath, content, 'utf8');
+    console.log(`📄 Created file: ${relPath}${description ? ` (${description})` : ''}`);
+    return true;
+  }
+  console.log(`⏭️  Skipped: ${relPath} already exists.`);
+  return false;
+};
+
+seedFiles.forEach(([relPath, content]) => writeIfNotExists(relPath, content));
+
+// 6. Client discovery and protocol pointers
+console.log('\n--- Environment Analysis ---');
+
+const protocolFiles = {
+  claude: 'CLAUDE.md',
+  gemini: 'GEMINI.md',
+  codex: 'AGENTS.md',
+  antigravity: 'AGENTS.md', // Antigravity CLI reads AGENTS.md; single protocolContent reused.
+};
+
+for (const client of CLIENTS) {
+  if (clientDetected(client)) {
+    console.log(`✅ ${client.label} detected.`);
+    writeIfNotExists(protocolFiles[client.key], protocolContent, `${client.label} protocol pointer`);
+  }
+}
+
+// Cursor/Windsurf (always recommended)
+writeIfNotExists('.cursorrules', protocolContent, 'Cursor/Windsurf rules');
+
+// 7. Generate mkt_docs/INDEX.md so the very first `validate` is already clean.
+// The manifest is generated, never seeded: delegate to the validator if Python is available.
+const validator = path.join(SKILL_SOURCE, 'scripts', 'mkt_check.py');
+let indexed = false;
+for (const py of ['python', 'python3', 'py']) {
+  try {
+    execSync(`${py} "${validator}" index --root "${cwd}"`, { stdio: 'ignore' });
+    console.log('📇 Generated mkt_docs/INDEX.md (document manifest).');
+    indexed = true;
+    break;
+  } catch (e) { /* try the next interpreter */ }
+}
+if (!indexed) {
+  console.log('ℹ️  Python not found: generate the manifest later with '
+    + '"python <skill_dir>/scripts/mkt_check.py index" (validate reports it until then).');
+}
+
+console.log('\n✅ Setup completed successfully!');
+console.log('💡 Next steps:');
+console.log('   1. Make sure the mkt-agentic-sdlc skill is installed (mkt-sdlc-install-skill).');
+console.log('   2. Restart/open the project in your AI client so it reads the protocol pointer.');
+console.log('   3. Start an E3 engagement: the skill runs Discovery (its questions) before anything else.');

package/scripts/lib.js

@@ -0,0 +1,170 @@
+// Shared helpers for the Marketing Agentic SDLC npm scripts (init / postinstall / preuninstall).
+// Single source for client detection and skill-target paths: init and postinstall
+// must never disagree on what "Claude Code is installed" means.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const SKILL_SOURCE = path.join(PACKAGE_ROOT, 'skills', 'mkt-agentic-sdlc');
+const TEMPLATES_PATH = path.join(SKILL_SOURCE, 'templates.md');
+const SKILL_DIR_NAME = 'mkt-agentic-sdlc';
+
+// One entry per supported AI client. `home` may be overridden by an env var
+// (Claude Desktop / portable installs); presence of the home dir counts as
+// detection even when the CLI is not on PATH.
+const CLIENTS = [
+  {
+    key: 'claude',
+    label: 'Claude Code',
+    cmd: 'claude',
+    home: process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude'),
+    envVar: 'CLAUDE_CONFIG_DIR',
+    reload: 'Restart Claude Code to load it. Invoke via Skill tool as "mkt-agentic-sdlc".',
+  },
+  {
+    key: 'gemini',
+    label: 'Gemini CLI',
+    cmd: 'gemini',
+    home: process.env.GEMINI_HOME || path.join(os.homedir(), '.gemini'),
+    envVar: 'GEMINI_HOME',
+    reload: 'Run "gemini skills reload" or restart Gemini CLI to load it.',
+  },
+  {
+    key: 'codex',
+    label: 'Codex AI',
+    cmd: 'codex',
+    home: process.env.CODEX_HOME || path.join(os.homedir(), '.codex'),
+    envVar: 'CODEX_HOME',
+    reload: 'Restart Codex to load it. Invoke it as "$mkt-agentic-sdlc" or by asking for the Marketing SDLC skill.',
+  },
+  {
+    // Google Antigravity 2.0 discovers global agent skills under
+    // ~/.gemini/config/skills/ -- the SAME home the legacy Gemini CLI claims.
+    // To avoid a shared-home double-install, this entry sets:
+    //  - skillsSubdir 'config/skills': distinct target from gemini's ~/.gemini/skills
+    //  - homeMarker on ~/.gemini/config/skills: detection never fires on bare
+    //    ~/.gemini (which every Antigravity user has); only the Antigravity skills
+    //    dir, the `agy` CLI, or ANTIGRAVITY_HOME count as "Antigravity installed".
+    key: 'antigravity',
+    label: 'Google Antigravity',
+    cmd: 'agy',
+    home: process.env.ANTIGRAVITY_HOME || path.join(os.homedir(), '.gemini'),
+    envVar: 'ANTIGRAVITY_HOME',
+    skillsSubdir: 'config/skills',
+    homeMarker: path.join(
+      process.env.ANTIGRAVITY_HOME || path.join(os.homedir(), '.gemini'),
+      'config',
+      'skills',
+    ),
+    reload: 'Restart Antigravity, or run "agy skills reload", to load it. Invoke by asking for the Marketing SDLC skill.',
+  },
+];
+
+function commandExists(cmd) {
+  try {
+    execSync(`${cmd} --version`, { stdio: 'ignore' });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+function clientDetected(client) {
+  // An entry may override the fs-existence probe with a `homeMarker` (a more
+  // specific path than the bare home) so two clients sharing a home dir do not
+  // both fire on its mere existence. Entries without a marker check `home`
+  // exactly as before (backward-compatible).
+  const homePathToCheck = client.homeMarker || client.home;
+  return commandExists(client.cmd)
+    || Boolean(process.env[client.envVar])
+    || fs.existsSync(homePathToCheck);
+}
+
+function skillTarget(client) {
+  // An entry may override the default `skills` sub-path with `skillsSubdir`
+  // (split on '/' to keep cross-platform path.join correctness). Entries
+  // without it resolve to <home>/skills/mkt-agentic-sdlc exactly as before.
+  const subdir = client.skillsSubdir ? client.skillsSubdir.split('/') : ['skills'];
+  return path.join(client.home, ...subdir, SKILL_DIR_NAME);
+}
+
+function copyRecursive(src, dest) {
+  if (typeof fs.cpSync === 'function') {
+    fs.cpSync(src, dest, { recursive: true, force: true });
+    return;
+  }
+  // Fallback for Node < 16.7
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyRecursive(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+/**
+ * Parse templates.md into { headingText: [fencedBlock, ...] }.
+ * Templates are single-sourced there: the init script must extract them
+ * instead of carrying its own inline copies (which historically drifted).
+ */
+function loadTemplates() {
+  const text = fs.readFileSync(TEMPLATES_PATH, 'utf8');
+  const lines = text.split(/\r?\n/);
+  const sections = {};
+  let heading = null;
+  let block = null;
+  for (const line of lines) {
+    const h = line.match(/^##\s+(.*)$/);
+    if (h && block === null) {
+      heading = h[1].trim();
+      sections[heading] = sections[heading] || [];
+      continue;
+    }
+    if (/^```/.test(line)) {
+      if (block === null) {
+        block = [];
+      } else {
+        if (heading) sections[heading].push(block.join('\n') + '\n');
+        block = null;
+      }
+      continue;
+    }
+    if (block !== null) block.push(line);
+  }
+  return sections;
+}
+
+/**
+ * Return the Nth fenced block of the section whose heading contains `needle`.
+ * Throws with a clear message when missing: writing a wrong or empty
+ * boilerplate silently would be worse than failing the init.
+ */
+function templateFor(sections, needle, index = 0) {
+  const heading = Object.keys(sections).find((h) => h.includes(needle));
+  const blocks = heading ? sections[heading] : undefined;
+  if (!blocks || !blocks[index]) {
+    throw new Error(
+      `Template section containing "${needle}" (block ${index}) not found in ${TEMPLATES_PATH}. ` +
+      'The package is corrupted or templates.md was restructured: fix templates.md, do not improvise content.'
+    );
+  }
+  return blocks[index];
+}
+
+module.exports = {
+  PACKAGE_ROOT,
+  SKILL_SOURCE,
+  TEMPLATES_PATH,
+  SKILL_DIR_NAME,
+  CLIENTS,
+  commandExists,
+  clientDetected,
+  skillTarget,
+  copyRecursive,
+  loadTemplates,
+  templateFor,
+};

package/scripts/postinstall.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const { SKILL_SOURCE, CLIENTS, clientDetected, skillTarget, copyRecursive } = require('./lib');
+
+function installSkill(client) {
+  if (!fs.existsSync(SKILL_SOURCE)) {
+    console.log(`⚠️  Skill source not found at ${SKILL_SOURCE}; skipping ${client.label} install.`);
+    return false;
+  }
+  const target = skillTarget(client);
+  try {
+    fs.mkdirSync(target, { recursive: true });
+    copyRecursive(SKILL_SOURCE, target);
+    console.log(`📦 Installed ${client.label} skill at: ${target}`);
+    console.log(`   ${client.reload}`);
+    return true;
+  } catch (err) {
+    console.log(`⚠️  Failed to install ${client.label} skill: ${err.message}`);
+    console.log(`   Manual install: copy "${SKILL_SOURCE}" to "${target}".`);
+    return false;
+  }
+}
+
+console.log('\n--- Marketing Agentic SDLC Skill Discovery ---');
+
+let detected = false;
+for (const client of CLIENTS) {
+  if (clientDetected(client)) {
+    console.log(`✅ Detected: ${client.label}`);
+    detected = true;
+    installSkill(client);
+  }
+}
+
+if (!detected) {
+  console.log('ℹ️  No specific AI CLI detected globally, but you can still use the skill.');
+}
+
+console.log('\nTo initialize a project with the marketing protocol, run:');
+console.log('👉 npx mkt-sdlc-init');
+console.log('------------------------------------\n');

package/scripts/preuninstall.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const { CLIENTS, skillTarget } = require('./lib');
+
+function removeSkill(client) {
+  const target = skillTarget(client);
+  if (!fs.existsSync(target)) return;
+  try {
+    fs.rmSync(target, { recursive: true, force: true });
+    console.log(`🧹 Removed ${client.label} skill at: ${target}`);
+  } catch (err) {
+    console.log(`⚠️  Could not remove ${target}: ${err.message}`);
+  }
+}
+
+CLIENTS.forEach(removeSkill);

package/skills/mkt-agentic-sdlc/ENFORCEMENT.md

@@ -0,0 +1,82 @@
+# Mechanical Enforcement (optional)
+
+The prompt is not enforcement. Where the project needs repeatable guarantees,
+wire the validator into the workflow. Everything here is optional: the skill
+must stay usable without Python or hooks, declaring what it cannot verify.
+
+## 1. Pre-delivery gate (the one that matters)
+
+Before presenting any E2/E3 deliverable as finished:
+
+```bash
+python <skill_dir>/scripts/mkt_check.py check --root <project_root>
+```
+
+`check` runs `validate + ledger + budget + funnel + trace`. Errors block the
+delivery; warnings ship only with explicit user acknowledgment. This is the
+marketing twin of "tests must pass before DONE".
+
+## 2. CI
+
+For a marketing repo kept under version control:
+
+```yaml
+# e.g. GitHub Actions step
+- run: python skills/mkt-agentic-sdlc/scripts/mkt_check.py validate --strict --root .
+- run: python skills/mkt-agentic-sdlc/scripts/mkt_check.py ledger --root .
+```
+
+Use `--strict` only in CI: locally, warnings are guidance; in CI they are
+drift.
+
+## 3. Git hook (pre-commit)
+
+```bash
+#!/bin/sh
+python skills/mkt-agentic-sdlc/scripts/mkt_check.py check --root . || {
+  echo "mkt_check failed — fix the plan before committing."; exit 1; }
+```
+
+## 4. What the validator cannot check (honesty list)
+
+- Whether a BENCHMARK's URL actually supports the claimed number (it checks
+  presence, not truth) — that is the review's R2/R3 territory.
+- Whether the positioning passes the swap test (R1) — adversarial review only.
+- Whether kill/scale thresholds are sensible — review, with ledger evidence.
+- Whether the deliverable language matches the target market — Discovery
+  record + review.
+
+Declare these residuals when reporting a CLEAN check: mechanical CLEAN plus
+review PASS is the full gate, neither alone.
+
+## 5. Skill self-test (skill development only)
+
+Two deterministic batteries — the release gate. Run both:
+
+```bash
+python -m unittest discover -s skills/mkt-agentic-sdlc/scripts -p "test_*.py"
+```
+
+- `test_mkt_check.py` — the validator itself; gate for changes to
+  `mkt_check.py` or to the parseable template formats in `templates.md` (the
+  two must move together: a template format change without a validator change
+  is drift).
+- `test_skill_invariants.py` — the doctrine invariants: asserts the
+  load-bearing rules are still present in `SKILL.md` and the support files
+  (the three guarantees, the review red-flags R1/R11b/R15, the elicitation
+  rules, the research URL rule, the parseable template tokens, every support
+  file wired). Fails when a rule is deleted or weakened — a real regression,
+  never flakiness.
+
+## 6. Behavioral eval layer (opt-in, non-gating)
+
+```bash
+python skills/mkt-agentic-sdlc/evals/run_behavioral.py skills/mkt-agentic-sdlc/evals/scenarios/<scenario>.md
+```
+
+Declarative scenarios exercise real agent *adherence* (elicitation asks only
+owned facts, no number without a ledger entry, swap-test enforced, low-cost
+trap flagged, E2-without-strategy escalates, no guaranteed-success promise).
+The driver seeds a throwaway fixture, prints the prompt + pass criteria, makes
+NO model call, and never gates — LLM nondeterminism is why the deterministic
+gate stays §5. See `evals/scenarios/README.md`.