npm - @antoneeo/mkt-agentic-sdlc-skill - Versions diffs - 0.4.1 → 0.4.4 - Mend

@antoneeo/mkt-agentic-sdlc-skill 0.4.1 → 0.4.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/CHANGELOG.md +38 -0
package/gemini-extension.json +6 -6
package/package.json +50 -50
package/skills/mkt-agentic-sdlc/SKILL.md +240 -240
package/skills/mkt-agentic-sdlc/review.md +36 -0
package/skills/mkt-agentic-sdlc/scripts/sdlc_core.py +6 -2

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,43 @@
 # Changelog
+## [0.4.4] - 2026-08-05
+### Changed
+- **Shared-spine sync: use-case grounding clause (inert in this lens).** The shared `review.md`
+  gains the code lens's use-case-grounding finding — a product name in no EXISTS/NEW/METAPHOR
+  bucket, or a use-case tracing to no Vision benefit. The mkt lens defines no `## Use Cases`
+  template section, so the clause stays inert here — spine parity only.
+## [0.4.3] - 2026-08-05
+### Changed
+- **Shared-spine sync: Interface Contract rename (inert in this lens).** The shared `review.md`
+  Interaction Contract clause is renamed to **Interface Contract** and gains the code lens's
+  evolved checks (responsibility-level flow, solution-leakage, universal feedback); the
+  `interaction_contract` capability key is unchanged. The mkt lens defines no such template
+  section, so the clause stays inert here — spine parity only.
+## [0.4.2] - 2026-08-05
+### Fixed
+- **Registry recognition hard-coded to one entry point.** The workstream-registry
+  header is written with `entry_script()` (here: `mkt_check.py`) but was recognized
+  as "already ours" only by the literal `sdlc_check.py`: a registry this very lens
+  generated was treated as legacy and re-checked for conversion blockers on every
+  run. Recognition now matches the generated marker for any family entry point.
+- **Battery isolation.** The marketing battery failed 13+1 under full unittest
+  discovery (and passed module-by-module): `test_merge_safety` built `ai_docs`
+  fixtures while the mkt overlay import had flipped the default docs root to
+  `mkt_docs`. The battery now pins its docs root in `setUpModule`; full discovery
+  is green.
+### Changed
+- **Shared-spine sync with code 1.22.0 (Interaction Contract, F-032).** The shared
+  `review.md` gains the Interaction Contract conformance clause and the shared core
+  registers the `interaction_contract` capability — both **inert in this lens**: the
+  clause is keyed on the lens whose template defines the section (the code lens),
+  mkt claims no such capability, and no mkt workflow gains any new step or artifact.
 ## [0.4.1] - 2026-08-03
 ### Added

package/gemini-extension.json CHANGED Viewed

@@ -1,6 +1,6 @@
-{
-  "name": "mkt-agentic-sdlc",
-  "version": "0.4.1",
-  "description": "Evidence-First marketing planning protocol with engagement triage, SOSTAC workflow, evidence ledger and optional devPNT integration.",
-  "author": "Antonio Pinto (https://github.com/Antoneeo)"
-}
+{
+  "name": "mkt-agentic-sdlc",
+  "version": "0.4.4",
+  "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 CHANGED Viewed

@@ -1,50 +1,50 @@
-{
-  "name": "@antoneeo/mkt-agentic-sdlc-skill",
-  "version": "0.4.1",
-  "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/scripts/sdlc_core.py",
-    "skills/mkt-agentic-sdlc/routing.md",
-    "skills/mkt-agentic-sdlc/guides.md",
-    "skills/mkt-agentic-sdlc/vision.md",
-    "skills/mkt-agentic-sdlc/dispatch.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"
-  ]
-}
+{
+  "name": "@antoneeo/mkt-agentic-sdlc-skill",
+  "version": "0.4.4",
+  "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/scripts/sdlc_core.py",
+    "skills/mkt-agentic-sdlc/routing.md",
+    "skills/mkt-agentic-sdlc/guides.md",
+    "skills/mkt-agentic-sdlc/vision.md",
+    "skills/mkt-agentic-sdlc/dispatch.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/skills/mkt-agentic-sdlc/SKILL.md CHANGED Viewed

@@ -1,240 +1,240 @@
----
-name: mkt-agentic-sdlc
-version: 0.4.1
-description: Evidence-First marketing planning protocol with engagement triage, SOSTAC workflow, evidence ledger, adversarial CMO review, a complete Standalone mode and optional symbiosis with devPNT. Use for marketing plans, go-to-market strategy, campaign planning and market research.
-author: Antonio Pinto (https://github.com/Antoneeo)
-copyright: (c) 2026 Antonio Pinto
----
-# Marketing Agentic SDLC
-This skill guides marketing strategy work with an Evidence-First process proportional to the engagement. It turns the agent into a disciplined marketing strategist: facts come from the user, analysis comes from real research, numbers come from a ledger, and the plan ships only after mechanical validation and adversarial review. It must work fully even without devPNT. When devPNT is available and configured for the current project, plans and strategy artifacts become governed, versioned documents with proposal/approval workflow.
-Support files in the skill directory:
-- `frameworks.md`: which professional framework to use in which phase (SOSTAC, STP, JTBD, positioning, KPI tree) — and when NOT to use one.
-- `elicitation.md`: the question waves and the only-facts-you-own rule.
-- `research.md`: the research playbook and the evidence ledger discipline.
-- `templates.md`: templates for every artifact and deliverable.
-- `review.md`: the family's shared review discipline (independence ladder, rounds, log). The marketing-specific attack surface — swap test, untraced numbers, orphan tactics, missing kill/scale — lives in `frameworks.md`'s falsification rules; the adversarial CMO review applies them through `review.md`'s procedure.
-- `scripts/mkt_check.py` + `scripts/sdlc_core.py`: the mechanical validator (`check`, `validate`, `ledger`, `budget`, `funnel`, `trace`, `index`, plus the spine's `stale`/`mark`/`gate`/`orient`/`plan`/`migrate`). Two files: the core is the family's shared spine, the entry point is this domain's overlay. Copy both, or neither.
-- `ENFORCEMENT.md`: optional setup for CI and hooks.
-Read these files only when needed. `SKILL.md` is the operating contract; the support files are progressive resources.
-## Honesty Contract
-No process guarantees market success, and this skill never claims one. What it guarantees is **process rigor**: zero invented numbers, internal mathematical consistency, conformance to frameworks professionals recognize, measurability of every commitment, and a built-in control loop. State this plainly if the user asks for a "guaranteed" outcome — the guarantee is the rigor, not the market.
-## Marketing Values
-- **Evidence before claims:** no market number, benchmark or persona trait enters an artifact without an evidence ledger entry. An unsourced number is a defect, not a placeholder.
-- **Ask only what the user owns:** facts (product, price, budget, capacity, constraints) come from the user; analysis (market size, competitors, channels) comes from research. Never ask the user to do the analysis, and never use jargon in questions to the user.
-- **Framework conformance:** deliverables follow structures professionals recognize (SOSTAC, STP, SMART, KPI tree) — but a framework is a lens, not a form to fill. An empty section is declared, never padded.
-- **Internal consistency:** budget allocations sum, funnel math closes, every tactic serves an objective, every objective has a KPI. Checked mechanically, not rhetorically.
-- **Positioning must exclude:** a positioning statement that could describe any competitor is a defect. The swap test (replace our name with the top competitor's) must fail.
-- **Honesty about uncertainty:** assumptions are declared with ranges and confidence, never laundered into facts. A plan built on assumptions says so on page one.
-- **Measurability:** every tactic has a KPI, every objective a success signal, every plan explicit kill/scale criteria and a review cadence.
-- **Protect the Marketing Vision:** every downstream choice must serve a stated expected benefit or success signal; unauthorized scope is a vision divergence, not initiative.
-If a strategic choice looks obvious but you cannot trace it to evidence, research first.
-## Rule Zero: Triage
-**Declare the level WITH the router verdict** (one line, for every engagement level above the trivial one): the result of the guide-router lookup, i.e. `Level: E2 · router: no match` or `Level: E3 · router: GUIDE_brand_voice.md → read`. The lookup is the consult trigger; making its result a declared output is what keeps it from being skipped — a level declared without a verdict makes "did not look" indistinguishable from "looked, nothing matched". Name the guide you matched, or `no match`.
-**Domain routing (multi-lens installs only).** After the level is set, and only when a sibling lens skill of this family is installed (`agentic-sdlc`, `kb-agentic`), run the router in `routing.md`: it decides which lens's method and validation rules govern this unit of work. The trivial level never reaches it (L1 never reaches it), and a single-lens install never reads the file — detection fails open. In such a project, never refer to a document whose meaning differs by lens ("threat model", "vision", `principles.md`, `handoff.md`) by its bare name: qualify it with its domain, or name its path.
-Always classify the request before choosing the process. Declare the chosen level to the user when you start operational work.
-| Level | Criteria | Required process |
-|---|---|---|
-| **E1 - Quick** | Single question or asset feedback: a positioning opinion, copy critique, one channel question | Answer directly. Numbers still need a source or an explicit "assumption" label. No new documents. |
-| **E2 - Campaign** | One campaign or one channel plan, bounded budget, existing strategy context | Mini-brief in the message (objective, audience, budget, KPI), targeted research, `mkt_docs/tactics/CAMPAIGN_[name].md`. Evidence ledger discipline applies. |
-| **E3 - Full Plan** | Complete marketing plan, go-to-market for a launch, entering a new market, or no prior strategy exists | Full workflow: all nine phases, all gates, full deliverable pack. |
-| **Research Spike** | Time-boxed market question that reduces uncertainty ("is there demand for X in market Y?") | Outcome in `mkt_docs/spikes/RESEARCH_[topic].md`. Ledger discipline applies. For strategy decisions, feed into E2/E3. |
-Cross-cutting rules:
-- Every question to the user passes the legality test of the question discipline (`elicitation.md`): searched first with the search named, and the blocked decision named. The waves are where asking is planned; outside them the test gates each ask.
-- Anything touching pricing strategy, brand repositioning, or a new market entry is never E1: those decisions cascade.
-- If a bigger scope emerges during E1/E2 work (e.g. the campaign reveals there is no positioning), stop, reclassify and declare it.
-- When in doubt, pick the higher level.
-- An E2 whose strategy context does not exist (no approved MKT-VISION or STRATEGY) escalates to E3: tactics without strategy is the failure mode this skill exists to prevent.
-## Write Triggers
-One event, one destination: when the trigger fires and the document does not exist, create it; when it exists, update it — never duplicate it.
-| Document | Write trigger | Phase |
-|---|---|---|
-| `audit/handoff.md` (workstream registry) | **Never by hand — generated by `mkt_check.py index` from the `HANDOFF_*.md` sources**, and `validate` errors when the two disagree. Regenerate at every closure and at session end; the `Date:` header is derived, so no writer touches it. Inventory for lookup, never a work board. | 9 / session end |
-| `audit/HANDOFF_[engagement].md` | **One per OPEN engagement, with or without volatile state** — it is the authored home of that engagement's registry row (frontmatter `workstream`/`level`/`branch`/`status`/`since`/`next`/`details`/`updated`), so no file means no row. DELETED at closure — deleting it *is* removing the row. | 9 / session end |
-| `audit/project_notes.md` | A note true for the whole engagement portfolio rather than one engagement. Appended verbatim to the generated registry, so regenerating cannot destroy it. | 9 / session end |
-| `audit/handoff.md` — converting an existing project | **Lazily, at the first write — and then ALL AT ONCE.** Converting one row at a time is the state that loses the others, so `index` refuses to write while anything in the file is unaccounted for and names it. | 9 / session end |
-| `audit/HANDOFF_[engagement].md` | Session ends with that engagement unfinished AND there is volatile resume state. Ephemeral, deleted at closure. | 8 / 9 / session end |
-| `audit/reviews/REVIEW_LOG.md` | Every completed review — when and what to write is `review.md`; schema is `templates.md`. | 6 / 9 |
-| `reference/GUIDE_[topic].md` | Origin+purpose test (`guides.md`), or a proactive proposal the user accepted. | 8 / 9 |
-| `vision/` documents | Bootstrap as `Status: DRAFT`; promoted to APPROVED only by explicit user confirmation, and only after the blind check (`vision.md` §6). | 1 / 5 |
-## Operating Modes
-### Full Standalone
-Use this mode when devPNT is unavailable, not configured for the current project, or the user explicitly asks for a filesystem-only workflow.
-Source of truth:
-- Vision: `mkt_docs/vision/MKT_VISION.md`, `principles.md`.
-- Evidence: `mkt_docs/research/evidence_ledger.md` + research documents in `mkt_docs/research/`.
-- Strategy artifacts: `mkt_docs/strategy/` (ICP_PERSONAS, THREAT_MAP, OBJECTIVES, STRATEGY).
-- Tactical artifacts: `mkt_docs/tactics/` (TACTICAL_PLAN, ACTION_90D, MEASUREMENT_PLAN).
-- Deliverables: `mkt_docs/deliverables/` (MARKETING_PLAN, ONE_PAGER, exports).
-- Spikes and handoff: `mkt_docs/spikes/`, `mkt_docs/audit/handoff.md`.
-Standalone mode is not reduced: it must handle full plans, campaigns, research spikes, reviews and closure without devPNT.
-### Hybrid in symbiosis with devPNT
-Use this mode when the `devpnt_*` tools are available and point at the current project.
-Authoritative hierarchy:
-1. **devPNT M-VISION**: strategic beacon of the plan cycle. Before strategy or tactics, read it and verify benefits, success signals, scope-in and non-goals.
-2. **devPNT Master Plan**: the marketing roadmap; milestones are plan cycles (a quarter, a launch, a market entry).
-3. **devPNT Action Plan**: the nine phases of the active engagement as tactical nodes.
-4. **devPNT governed artifacts**: the marketing artifact set (table below).
-5. **Local `mkt_docs/`**: readable context, Standalone fallback, evidence ledger home, shadow/mirror when useful.
-### Ownership matrix (the Hybrid seam)
-The skill owns the **process** (triage, phases, gates, lifecycle); devPNT owns the **machinery** (governed storage, versioned proposals, review wiring). The marketing artifacts occupy the same governance slots the software artifacts occupy in the sibling skill:
-| Artifact | Standalone master | Hybrid master (devPNT slot) | Mirror rule |
-|---|---|---|---|
-| Marketing vision | `vision/MKT_VISION.md` | M-VISION (`milestone_vision_<slug>`) | filesystem copy is a shadow; DB wins |
-| ICP & Personas | `strategy/ICP_PERSONAS.md` | `mkt_icp_personas` (D-UC slot) | shadow `SHADOW_[doc_key]_vX.Y.md` |
-| Threat map | `strategy/THREAT_MAP.md` | `mkt_threat_map` (P-TM slot) | shadow |
-| Objectives | `strategy/OBJECTIVES.md` | `mkt_objectives` | shadow |
-| Strategy | `strategy/STRATEGY.md` | `mkt_strategy` (E-ISP slot) | shadow, exported BEFORE tactics work |
-| Tactical plan | `tactics/TACTICAL_PLAN.md` | `mkt_tactical_plan` (E-TDD slot) | shadow, exported BEFORE action phase |
-| Measurement plan | `tactics/MEASUREMENT_PLAN.md` | `mkt_measurement_plan` (E-TP slot) | shadow |
-| Evidence ledger | `research/evidence_ledger.md` | `research/evidence_ledger.md` — **filesystem-first even in Hybrid** | validator needs it on disk; devPNT may reference, never copies |
-| Final plan + one-pager | `deliverables/` | assembled from ACCEPTED artifact versions | PDF via `devpnt_generate_document_pdf` when available |
-| Handoff | `audit/handoff.md` | `audit/handoff.md` | always filesystem |
-Hybrid rules:
-- devPNT is the governed source for plans and strategy artifacts; do not create a second truth in `mkt_docs/`.
-- The skill stays autonomous: if devPNT is not there, switch to Standalone without losing capability.
-- If the user request, the local vision and the M-VISION diverge, stop and make the conflict explicit.
-- Never auto-accept devPNT proposals: present the preview and wait for explicit confirmation.
-- Where the local devPNT protocol imposes stricter gates (vision creation/amendment gates, independent review gates), follow them: they are the same discipline this skill encodes.
-## The Three Engineered Guarantees
-Every E3 (and every E2 with numbers) is bound by these. They are the product; the phases below exist to feed them.
-1. **Evidence ledger** (`research.md`): every number is classified — `FACT` (user input or primary data), `BENCHMARK` (external source, URL + date mandatory), `ASSUMPTION` (declared, range + confidence mandatory) — and referenced as `[EV-nn]` wherever used. `mkt_check.py ledger` fails on unresolved references and unsourced benchmarks.
-2. **Mechanical validation** (`mkt_check.py`): `budget` (allocations sum to the declared total), `funnel` (spend → clicks → leads → customers chain recomputed, ±5% tolerance, compared to the objective target), `trace` (every tactic names an objective; every objective has a KPI in the measurement plan). A plan that fails validation is not presented to the user as finished.
-3. **Adversarial CMO review** (`review.md`): before the strategy gate and before final packaging, an independent fresh-context reviewer attacks the artifact — swap test on positioning, untraced numbers, orphan tactics, missing kill criteria. Findings are answered one by one; cap 3 rounds, then surface open findings to the user.
-## E3 Workflow (nine phases on the SOSTAC spine)
-Deliverable language: ask for (or infer) the target market's language in Discovery; artifacts and deliverables are written in it. The skill's internal doctrine stays English.
-### 1. Intake & Triage
-- Read the docs root's `README.md`, `INDEX.md` and `reference/INDEX.md` (the guide router; the docs root is `mkt_docs/` by default, `ai_docs/` on a migrated tree) before touching the plan. The router is a mandatory read, not an optional one: it is the only orientation step that tells you a guide — a brand guideline, a tone-of-voice SOP, an agency playbook — already governs the work you are about to do.
-- Read `audit/handoff.md` under the docs root, the workstream registry: one row per open engagement. Volatile resume state for an unfinished one lives in `audit/HANDOFF_[engagement].md`, which is ephemeral and deleted at closure.
-- Declare the level. Read `mkt_docs/audit/handoff.md` and `mkt_docs/README.md`/`INDEX.md` if they exist; if handoff dates are inconsistent, treat it as history.
-- Hybrid: bootstrap devPNT, restore Master/Action Plan and any existing marketing artifacts before asking the user anything they already answered.
-### 2. Discovery (Situation — internal)
-- Run elicitation **Wave 1** (`elicitation.md`): business facts only, plain language, max 4 questions per round, options where a real choice exists.
-- Every fact captured becomes a `FACT` ledger entry. Draft `MKT_VISION.md` (Status: DRAFT) from the answers.
-- **Vision Gate:** the user approves the MKT-VISION (expected benefit, success signals, non-goals) before research spends effort. Hybrid: this is the devPNT M-VISION creation gate — vision first, then the milestone.
-### 3. Research (Situation — external)
-- Follow `research.md`. Prefer the deep-research skill as the engine when available; fallback to the manual playbook.
-- Mandatory sweeps: market sizing (bottom-up preferred), competitor scan, voice-of-customer mining, channel benchmarks. Every number lands in the ledger with source + date.
-- Two independent sources for any number that will drive a budget decision.
-### 4. Situation Analysis
-- Synthesize research into `ICP_PERSONAS.md` (every persona trait traces to VoC evidence) and `THREAT_MAP.md` (competitor moves, risks, mitigations).
-- SWOT built from ledger entries, not adjectives. PESTEL / Five Forces only when the market warrants them (`frameworks.md` says when).
-### 5. Objectives — **USER GATE**
-- Run elicitation **Wave 2** (ambition, trade-offs, risk appetite, timeline).
-- Draft `OBJECTIVES.md`: SMART objectives (`O1`, `O2`, ...) + KPI tree. Each objective cites the ledger entries that make it plausible.
-- The user approves objectives before strategy. Objectives the user did not set are proposals, and say so.
-### 6. Strategy — **REVIEW + USER GATE**
-- **Design review gate:** the strategy is reviewed by somebody other than its author before any tactic is executed — a subagent with fresh context, or a declared self-pass when none is available. Follow `review.md`; log the outcome in `audit/reviews/REVIEW_LOG.md` under the docs root. A strategy reviewed only by the person who wrote it is not reviewed.
-- Draft `STRATEGY.md`: segmentation, targeting choice with rationale, positioning (Dunford components + statement), messaging house.
-- **Adversarial review** (`review.md`) before the user sees it. Fix or answer every finding.
-- The user approves the strategy. Hybrid: propose as governed doc, user accepts in devPNT.
-### 7. Tactics — **VALIDATOR GATE**
-- Run elicitation **Wave 3** (execution capacity: who writes, who runs ads, tooling, sales follow-up).
-- Draft `TACTICAL_PLAN.md`: channel table (channel | objective served | KPI | budget | owner), budget allocation, funnel model per acquisition channel.
-- `mkt_check.py budget && mkt_check.py funnel && mkt_check.py trace` must pass. A tactic that serves no objective is deleted or the objective set is revisited — never silently kept.
-### 8. Action
-- **Isolate the work (Branch/worktree hygiene).** Execution rewrites plan documents other people are reading: do it on a branch or a worktree, never directly on the shared plan.
-- **Consult (before acting)**: **consult the guide router** for a guide covering the task and read it first (the consult trigger, `guides.md` §0). A targeted description match, not a blanket read.
-- **Opt-in subagent execution**: for an approved plan, the work MAY be executed via subagents per `dispatch.md`; default stays same-session.
-- Draft `ACTION_90D.md`: sequenced 90-day plan (what starts when, owner, dependency), first 2 weeks day-level, rest weekly.
-### 9. Control & Packaging — **FINAL REVIEW GATE**
-- **Propose proactively**: if the work was governed by user-provided indications and is reusable, **PROPOSE distilling a guide** (proactive trigger, `guides.md` §1) — a proposal for the user, never a silent write, never from model knowledge.
-- Draft `MEASUREMENT_PLAN.md`: KPI tree with targets and benchmark references, review cadence, explicit kill/scale criteria per channel.
-- Assemble `MARKETING_PLAN.md` (the SOSTAC deliverable) and `ONE_PAGER.md` from the approved artifacts — assembly, not rewriting; on divergence the approved artifact wins.
-- Final adversarial review on the assembled plan + `mkt_check.py check` CLEAN.
-- Offer exports: PDF, slide deck, budget spreadsheet (use the client's document skills when available).
-- Update `handoff.md`. Hybrid: mark plan nodes DONE only after the user accepts the final artifacts.
-## E2 Workflow (campaign)
-A bounded version of the same discipline: mini-brief (objective, audience, budget, KPI — from an approved strategy context) → targeted research (channel benchmarks for the chosen channel, ledger discipline) → `CAMPAIGN_[name].md` with budget + funnel tables (validator: `budget`, `funnel`) → measurement section with kill/scale criteria. No E2 without strategy context: escalate to E3 instead.
-## mkt_docs documents: indexes + lifecycle
-- **`mkt_docs/README.md` (curated, by hand):** reading priority, few lines.
-- **`mkt_docs/INDEX.md` (generated, `mkt_check.py index`):** manifest of every canonical doc (`vision/`, `strategy/`, `tactics/`, `deliverables/`) with description and status. Never by hand.
-- `research/`, `spikes/`, `audit/` are discovery-by-grep: they do not enter the manifest. Research freshness is carried by ledger dates, not by the manifest.
-Every canonical document opens with frontmatter:
-```markdown
----
-description: One line — what it is and when to read it.
-status: CURRENT              # CURRENT | SUPERSEDED | DRAFT | DEPRECATED
-supersedes: old_doc.md       # only if it replaces another doc
----
-```
-`Status: DRAFT` informs; `Status: APPROVED` (inside MKT_VISION/OBJECTIVES/STRATEGY bodies, granted only by the user) binds. A superseded doc stays as history with `status: SUPERSEDED`. Missing `status` = warning in `validate`.
-## Deliverable quality bar
-The final plan must be recognizable by a marketing professional:
-- SOSTAC section structure, executive summary first.
-- Every number carries `[EV-nn]`; the ledger ships as an appendix.
-- Assumptions section on page one when material assumptions exist.
-- Positioning passes the swap test; messaging house has proof points, not slogans.
-- Budget table, funnel model, 90-day plan and kill/scale criteria present — a plan without a control loop is a brochure.
-## Reading the shared doctrine from this lens
-`review.md`, `dispatch.md` and `guides.md` are the family's shared spine,
-byte-identical in every distribution, written in the family's neutral
-vocabulary. Reading them from this lens: where they say `sdlc_check.py`,
-read `mkt_check.py`; where they say "Phase 3 / Phase 5 closure", read this
-workflow's phase 6 (strategy review) and phase 9 (control & packaging);
-where they say ANALYSIS/feature, read this lens's governed artifacts and
-engagement. The procedures bind as written; only the names translate.
-## Mechanical Enforcement
-The prompt is not enforcement. When the project needs repeatable guarantees:
-- read `ENFORCEMENT.md`;
-- use `scripts/mkt_check.py validate --strict` in CI;
-- run `scripts/mkt_check.py check` before declaring any E2/E3 deliverable done.
-The validator is a support, not a universal prerequisite: the skill must stay usable in environments without Python, declaring what it cannot verify automatically.
+---
+name: mkt-agentic-sdlc
+version: 0.4.4
+description: Evidence-First marketing planning protocol with engagement triage, SOSTAC workflow, evidence ledger, adversarial CMO review, a complete Standalone mode and optional symbiosis with devPNT. Use for marketing plans, go-to-market strategy, campaign planning and market research.
+author: Antonio Pinto (https://github.com/Antoneeo)
+copyright: (c) 2026 Antonio Pinto
+---
+# Marketing Agentic SDLC
+This skill guides marketing strategy work with an Evidence-First process proportional to the engagement. It turns the agent into a disciplined marketing strategist: facts come from the user, analysis comes from real research, numbers come from a ledger, and the plan ships only after mechanical validation and adversarial review. It must work fully even without devPNT. When devPNT is available and configured for the current project, plans and strategy artifacts become governed, versioned documents with proposal/approval workflow.
+Support files in the skill directory:
+- `frameworks.md`: which professional framework to use in which phase (SOSTAC, STP, JTBD, positioning, KPI tree) — and when NOT to use one.
+- `elicitation.md`: the question waves and the only-facts-you-own rule.
+- `research.md`: the research playbook and the evidence ledger discipline.
+- `templates.md`: templates for every artifact and deliverable.
+- `review.md`: the family's shared review discipline (independence ladder, rounds, log). The marketing-specific attack surface — swap test, untraced numbers, orphan tactics, missing kill/scale — lives in `frameworks.md`'s falsification rules; the adversarial CMO review applies them through `review.md`'s procedure.
+- `scripts/mkt_check.py` + `scripts/sdlc_core.py`: the mechanical validator (`check`, `validate`, `ledger`, `budget`, `funnel`, `trace`, `index`, plus the spine's `stale`/`mark`/`gate`/`orient`/`plan`/`migrate`). Two files: the core is the family's shared spine, the entry point is this domain's overlay. Copy both, or neither.
+- `ENFORCEMENT.md`: optional setup for CI and hooks.
+Read these files only when needed. `SKILL.md` is the operating contract; the support files are progressive resources.
+## Honesty Contract
+No process guarantees market success, and this skill never claims one. What it guarantees is **process rigor**: zero invented numbers, internal mathematical consistency, conformance to frameworks professionals recognize, measurability of every commitment, and a built-in control loop. State this plainly if the user asks for a "guaranteed" outcome — the guarantee is the rigor, not the market.
+## Marketing Values
+- **Evidence before claims:** no market number, benchmark or persona trait enters an artifact without an evidence ledger entry. An unsourced number is a defect, not a placeholder.
+- **Ask only what the user owns:** facts (product, price, budget, capacity, constraints) come from the user; analysis (market size, competitors, channels) comes from research. Never ask the user to do the analysis, and never use jargon in questions to the user.
+- **Framework conformance:** deliverables follow structures professionals recognize (SOSTAC, STP, SMART, KPI tree) — but a framework is a lens, not a form to fill. An empty section is declared, never padded.
+- **Internal consistency:** budget allocations sum, funnel math closes, every tactic serves an objective, every objective has a KPI. Checked mechanically, not rhetorically.
+- **Positioning must exclude:** a positioning statement that could describe any competitor is a defect. The swap test (replace our name with the top competitor's) must fail.
+- **Honesty about uncertainty:** assumptions are declared with ranges and confidence, never laundered into facts. A plan built on assumptions says so on page one.
+- **Measurability:** every tactic has a KPI, every objective a success signal, every plan explicit kill/scale criteria and a review cadence.
+- **Protect the Marketing Vision:** every downstream choice must serve a stated expected benefit or success signal; unauthorized scope is a vision divergence, not initiative.
+If a strategic choice looks obvious but you cannot trace it to evidence, research first.
+## Rule Zero: Triage
+**Declare the level WITH the router verdict** (one line, for every engagement level above the trivial one): the result of the guide-router lookup, i.e. `Level: E2 · router: no match` or `Level: E3 · router: GUIDE_brand_voice.md → read`. The lookup is the consult trigger; making its result a declared output is what keeps it from being skipped — a level declared without a verdict makes "did not look" indistinguishable from "looked, nothing matched". Name the guide you matched, or `no match`.
+**Domain routing (multi-lens installs only).** After the level is set, and only when a sibling lens skill of this family is installed (`agentic-sdlc`, `kb-agentic`), run the router in `routing.md`: it decides which lens's method and validation rules govern this unit of work. The trivial level never reaches it (L1 never reaches it), and a single-lens install never reads the file — detection fails open. In such a project, never refer to a document whose meaning differs by lens ("threat model", "vision", `principles.md`, `handoff.md`) by its bare name: qualify it with its domain, or name its path.
+Always classify the request before choosing the process. Declare the chosen level to the user when you start operational work.
+| Level | Criteria | Required process |
+|---|---|---|
+| **E1 - Quick** | Single question or asset feedback: a positioning opinion, copy critique, one channel question | Answer directly. Numbers still need a source or an explicit "assumption" label. No new documents. |
+| **E2 - Campaign** | One campaign or one channel plan, bounded budget, existing strategy context | Mini-brief in the message (objective, audience, budget, KPI), targeted research, `mkt_docs/tactics/CAMPAIGN_[name].md`. Evidence ledger discipline applies. |
+| **E3 - Full Plan** | Complete marketing plan, go-to-market for a launch, entering a new market, or no prior strategy exists | Full workflow: all nine phases, all gates, full deliverable pack. |
+| **Research Spike** | Time-boxed market question that reduces uncertainty ("is there demand for X in market Y?") | Outcome in `mkt_docs/spikes/RESEARCH_[topic].md`. Ledger discipline applies. For strategy decisions, feed into E2/E3. |
+Cross-cutting rules:
+- Every question to the user passes the legality test of the question discipline (`elicitation.md`): searched first with the search named, and the blocked decision named. The waves are where asking is planned; outside them the test gates each ask.
+- Anything touching pricing strategy, brand repositioning, or a new market entry is never E1: those decisions cascade.
+- If a bigger scope emerges during E1/E2 work (e.g. the campaign reveals there is no positioning), stop, reclassify and declare it.
+- When in doubt, pick the higher level.
+- An E2 whose strategy context does not exist (no approved MKT-VISION or STRATEGY) escalates to E3: tactics without strategy is the failure mode this skill exists to prevent.
+## Write Triggers
+One event, one destination: when the trigger fires and the document does not exist, create it; when it exists, update it — never duplicate it.
+| Document | Write trigger | Phase |
+|---|---|---|
+| `audit/handoff.md` (workstream registry) | **Never by hand — generated by `mkt_check.py index` from the `HANDOFF_*.md` sources**, and `validate` errors when the two disagree. Regenerate at every closure and at session end; the `Date:` header is derived, so no writer touches it. Inventory for lookup, never a work board. | 9 / session end |
+| `audit/HANDOFF_[engagement].md` | **One per OPEN engagement, with or without volatile state** — it is the authored home of that engagement's registry row (frontmatter `workstream`/`level`/`branch`/`status`/`since`/`next`/`details`/`updated`), so no file means no row. DELETED at closure — deleting it *is* removing the row. | 9 / session end |
+| `audit/project_notes.md` | A note true for the whole engagement portfolio rather than one engagement. Appended verbatim to the generated registry, so regenerating cannot destroy it. | 9 / session end |
+| `audit/handoff.md` — converting an existing project | **Lazily, at the first write — and then ALL AT ONCE.** Converting one row at a time is the state that loses the others, so `index` refuses to write while anything in the file is unaccounted for and names it. | 9 / session end |
+| `audit/HANDOFF_[engagement].md` | Session ends with that engagement unfinished AND there is volatile resume state. Ephemeral, deleted at closure. | 8 / 9 / session end |
+| `audit/reviews/REVIEW_LOG.md` | Every completed review — when and what to write is `review.md`; schema is `templates.md`. | 6 / 9 |
+| `reference/GUIDE_[topic].md` | Origin+purpose test (`guides.md`), or a proactive proposal the user accepted. | 8 / 9 |
+| `vision/` documents | Bootstrap as `Status: DRAFT`; promoted to APPROVED only by explicit user confirmation, and only after the blind check (`vision.md` §6). | 1 / 5 |
+## Operating Modes
+### Full Standalone
+Use this mode when devPNT is unavailable, not configured for the current project, or the user explicitly asks for a filesystem-only workflow.
+Source of truth:
+- Vision: `mkt_docs/vision/MKT_VISION.md`, `principles.md`.
+- Evidence: `mkt_docs/research/evidence_ledger.md` + research documents in `mkt_docs/research/`.
+- Strategy artifacts: `mkt_docs/strategy/` (ICP_PERSONAS, THREAT_MAP, OBJECTIVES, STRATEGY).
+- Tactical artifacts: `mkt_docs/tactics/` (TACTICAL_PLAN, ACTION_90D, MEASUREMENT_PLAN).
+- Deliverables: `mkt_docs/deliverables/` (MARKETING_PLAN, ONE_PAGER, exports).
+- Spikes and handoff: `mkt_docs/spikes/`, `mkt_docs/audit/handoff.md`.
+Standalone mode is not reduced: it must handle full plans, campaigns, research spikes, reviews and closure without devPNT.
+### Hybrid in symbiosis with devPNT
+Use this mode when the `devpnt_*` tools are available and point at the current project.
+Authoritative hierarchy:
+1. **devPNT M-VISION**: strategic beacon of the plan cycle. Before strategy or tactics, read it and verify benefits, success signals, scope-in and non-goals.
+2. **devPNT Master Plan**: the marketing roadmap; milestones are plan cycles (a quarter, a launch, a market entry).
+3. **devPNT Action Plan**: the nine phases of the active engagement as tactical nodes.
+4. **devPNT governed artifacts**: the marketing artifact set (table below).
+5. **Local `mkt_docs/`**: readable context, Standalone fallback, evidence ledger home, shadow/mirror when useful.
+### Ownership matrix (the Hybrid seam)
+The skill owns the **process** (triage, phases, gates, lifecycle); devPNT owns the **machinery** (governed storage, versioned proposals, review wiring). The marketing artifacts occupy the same governance slots the software artifacts occupy in the sibling skill:
+| Artifact | Standalone master | Hybrid master (devPNT slot) | Mirror rule |
+|---|---|---|---|
+| Marketing vision | `vision/MKT_VISION.md` | M-VISION (`milestone_vision_<slug>`) | filesystem copy is a shadow; DB wins |
+| ICP & Personas | `strategy/ICP_PERSONAS.md` | `mkt_icp_personas` (D-UC slot) | shadow `SHADOW_[doc_key]_vX.Y.md` |
+| Threat map | `strategy/THREAT_MAP.md` | `mkt_threat_map` (P-TM slot) | shadow |
+| Objectives | `strategy/OBJECTIVES.md` | `mkt_objectives` | shadow |
+| Strategy | `strategy/STRATEGY.md` | `mkt_strategy` (E-ISP slot) | shadow, exported BEFORE tactics work |
+| Tactical plan | `tactics/TACTICAL_PLAN.md` | `mkt_tactical_plan` (E-TDD slot) | shadow, exported BEFORE action phase |
+| Measurement plan | `tactics/MEASUREMENT_PLAN.md` | `mkt_measurement_plan` (E-TP slot) | shadow |
+| Evidence ledger | `research/evidence_ledger.md` | `research/evidence_ledger.md` — **filesystem-first even in Hybrid** | validator needs it on disk; devPNT may reference, never copies |
+| Final plan + one-pager | `deliverables/` | assembled from ACCEPTED artifact versions | PDF via `devpnt_generate_document_pdf` when available |
+| Handoff | `audit/handoff.md` | `audit/handoff.md` | always filesystem |
+Hybrid rules:
+- devPNT is the governed source for plans and strategy artifacts; do not create a second truth in `mkt_docs/`.
+- The skill stays autonomous: if devPNT is not there, switch to Standalone without losing capability.
+- If the user request, the local vision and the M-VISION diverge, stop and make the conflict explicit.
+- Never auto-accept devPNT proposals: present the preview and wait for explicit confirmation.
+- Where the local devPNT protocol imposes stricter gates (vision creation/amendment gates, independent review gates), follow them: they are the same discipline this skill encodes.
+## The Three Engineered Guarantees
+Every E3 (and every E2 with numbers) is bound by these. They are the product; the phases below exist to feed them.
+1. **Evidence ledger** (`research.md`): every number is classified — `FACT` (user input or primary data), `BENCHMARK` (external source, URL + date mandatory), `ASSUMPTION` (declared, range + confidence mandatory) — and referenced as `[EV-nn]` wherever used. `mkt_check.py ledger` fails on unresolved references and unsourced benchmarks.
+2. **Mechanical validation** (`mkt_check.py`): `budget` (allocations sum to the declared total), `funnel` (spend → clicks → leads → customers chain recomputed, ±5% tolerance, compared to the objective target), `trace` (every tactic names an objective; every objective has a KPI in the measurement plan). A plan that fails validation is not presented to the user as finished.
+3. **Adversarial CMO review** (`review.md`): before the strategy gate and before final packaging, an independent fresh-context reviewer attacks the artifact — swap test on positioning, untraced numbers, orphan tactics, missing kill criteria. Findings are answered one by one; cap 3 rounds, then surface open findings to the user.
+## E3 Workflow (nine phases on the SOSTAC spine)
+Deliverable language: ask for (or infer) the target market's language in Discovery; artifacts and deliverables are written in it. The skill's internal doctrine stays English.
+### 1. Intake & Triage
+- Read the docs root's `README.md`, `INDEX.md` and `reference/INDEX.md` (the guide router; the docs root is `mkt_docs/` by default, `ai_docs/` on a migrated tree) before touching the plan. The router is a mandatory read, not an optional one: it is the only orientation step that tells you a guide — a brand guideline, a tone-of-voice SOP, an agency playbook — already governs the work you are about to do.
+- Read `audit/handoff.md` under the docs root, the workstream registry: one row per open engagement. Volatile resume state for an unfinished one lives in `audit/HANDOFF_[engagement].md`, which is ephemeral and deleted at closure.
+- Declare the level. Read `mkt_docs/audit/handoff.md` and `mkt_docs/README.md`/`INDEX.md` if they exist; if handoff dates are inconsistent, treat it as history.
+- Hybrid: bootstrap devPNT, restore Master/Action Plan and any existing marketing artifacts before asking the user anything they already answered.
+### 2. Discovery (Situation — internal)
+- Run elicitation **Wave 1** (`elicitation.md`): business facts only, plain language, max 4 questions per round, options where a real choice exists.
+- Every fact captured becomes a `FACT` ledger entry. Draft `MKT_VISION.md` (Status: DRAFT) from the answers.
+- **Vision Gate:** the user approves the MKT-VISION (expected benefit, success signals, non-goals) before research spends effort. Hybrid: this is the devPNT M-VISION creation gate — vision first, then the milestone.
+### 3. Research (Situation — external)
+- Follow `research.md`. Prefer the deep-research skill as the engine when available; fallback to the manual playbook.
+- Mandatory sweeps: market sizing (bottom-up preferred), competitor scan, voice-of-customer mining, channel benchmarks. Every number lands in the ledger with source + date.
+- Two independent sources for any number that will drive a budget decision.
+### 4. Situation Analysis
+- Synthesize research into `ICP_PERSONAS.md` (every persona trait traces to VoC evidence) and `THREAT_MAP.md` (competitor moves, risks, mitigations).
+- SWOT built from ledger entries, not adjectives. PESTEL / Five Forces only when the market warrants them (`frameworks.md` says when).
+### 5. Objectives — **USER GATE**
+- Run elicitation **Wave 2** (ambition, trade-offs, risk appetite, timeline).
+- Draft `OBJECTIVES.md`: SMART objectives (`O1`, `O2`, ...) + KPI tree. Each objective cites the ledger entries that make it plausible.
+- The user approves objectives before strategy. Objectives the user did not set are proposals, and say so.
+### 6. Strategy — **REVIEW + USER GATE**
+- **Design review gate:** the strategy is reviewed by somebody other than its author before any tactic is executed — a subagent with fresh context, or a declared self-pass when none is available. Follow `review.md`; log the outcome in `audit/reviews/REVIEW_LOG.md` under the docs root. A strategy reviewed only by the person who wrote it is not reviewed.
+- Draft `STRATEGY.md`: segmentation, targeting choice with rationale, positioning (Dunford components + statement), messaging house.
+- **Adversarial review** (`review.md`) before the user sees it. Fix or answer every finding.
+- The user approves the strategy. Hybrid: propose as governed doc, user accepts in devPNT.
+### 7. Tactics — **VALIDATOR GATE**
+- Run elicitation **Wave 3** (execution capacity: who writes, who runs ads, tooling, sales follow-up).
+- Draft `TACTICAL_PLAN.md`: channel table (channel | objective served | KPI | budget | owner), budget allocation, funnel model per acquisition channel.
+- `mkt_check.py budget && mkt_check.py funnel && mkt_check.py trace` must pass. A tactic that serves no objective is deleted or the objective set is revisited — never silently kept.
+### 8. Action
+- **Isolate the work (Branch/worktree hygiene).** Execution rewrites plan documents other people are reading: do it on a branch or a worktree, never directly on the shared plan.
+- **Consult (before acting)**: **consult the guide router** for a guide covering the task and read it first (the consult trigger, `guides.md` §0). A targeted description match, not a blanket read.
+- **Opt-in subagent execution**: for an approved plan, the work MAY be executed via subagents per `dispatch.md`; default stays same-session.
+- Draft `ACTION_90D.md`: sequenced 90-day plan (what starts when, owner, dependency), first 2 weeks day-level, rest weekly.
+### 9. Control & Packaging — **FINAL REVIEW GATE**
+- **Propose proactively**: if the work was governed by user-provided indications and is reusable, **PROPOSE distilling a guide** (proactive trigger, `guides.md` §1) — a proposal for the user, never a silent write, never from model knowledge.
+- Draft `MEASUREMENT_PLAN.md`: KPI tree with targets and benchmark references, review cadence, explicit kill/scale criteria per channel.
+- Assemble `MARKETING_PLAN.md` (the SOSTAC deliverable) and `ONE_PAGER.md` from the approved artifacts — assembly, not rewriting; on divergence the approved artifact wins.
+- Final adversarial review on the assembled plan + `mkt_check.py check` CLEAN.
+- Offer exports: PDF, slide deck, budget spreadsheet (use the client's document skills when available).
+- Update `handoff.md`. Hybrid: mark plan nodes DONE only after the user accepts the final artifacts.
+## E2 Workflow (campaign)
+A bounded version of the same discipline: mini-brief (objective, audience, budget, KPI — from an approved strategy context) → targeted research (channel benchmarks for the chosen channel, ledger discipline) → `CAMPAIGN_[name].md` with budget + funnel tables (validator: `budget`, `funnel`) → measurement section with kill/scale criteria. No E2 without strategy context: escalate to E3 instead.
+## mkt_docs documents: indexes + lifecycle
+- **`mkt_docs/README.md` (curated, by hand):** reading priority, few lines.
+- **`mkt_docs/INDEX.md` (generated, `mkt_check.py index`):** manifest of every canonical doc (`vision/`, `strategy/`, `tactics/`, `deliverables/`) with description and status. Never by hand.
+- `research/`, `spikes/`, `audit/` are discovery-by-grep: they do not enter the manifest. Research freshness is carried by ledger dates, not by the manifest.
+Every canonical document opens with frontmatter:
+```markdown
+---
+description: One line — what it is and when to read it.
+status: CURRENT              # CURRENT | SUPERSEDED | DRAFT | DEPRECATED
+supersedes: old_doc.md       # only if it replaces another doc
+---
+```
+`Status: DRAFT` informs; `Status: APPROVED` (inside MKT_VISION/OBJECTIVES/STRATEGY bodies, granted only by the user) binds. A superseded doc stays as history with `status: SUPERSEDED`. Missing `status` = warning in `validate`.
+## Deliverable quality bar
+The final plan must be recognizable by a marketing professional:
+- SOSTAC section structure, executive summary first.
+- Every number carries `[EV-nn]`; the ledger ships as an appendix.
+- Assumptions section on page one when material assumptions exist.
+- Positioning passes the swap test; messaging house has proof points, not slogans.
+- Budget table, funnel model, 90-day plan and kill/scale criteria present — a plan without a control loop is a brochure.
+## Reading the shared doctrine from this lens
+`review.md`, `dispatch.md` and `guides.md` are the family's shared spine,
+byte-identical in every distribution, written in the family's neutral
+vocabulary. Reading them from this lens: where they say `sdlc_check.py`,
+read `mkt_check.py`; where they say "Phase 3 / Phase 5 closure", read this
+workflow's phase 6 (strategy review) and phase 9 (control & packaging);
+where they say ANALYSIS/feature, read this lens's governed artifacts and
+engagement. The procedures bind as written; only the names translate.
+## Mechanical Enforcement
+The prompt is not enforcement. When the project needs repeatable guarantees:
+- read `ENFORCEMENT.md`;
+- use `scripts/mkt_check.py validate --strict` in CI;
+- run `scripts/mkt_check.py check` before declaring any E2/E3 deliverable done.
+The validator is a support, not a universal prerequisite: the skill must stay usable in environments without Python, declaring what it cannot verify automatically.

package/skills/mkt-agentic-sdlc/review.md CHANGED Viewed

@@ -146,6 +146,19 @@ When you are the reviewer:
   which one is current. The rule bites hardest across domains, where the same slot
   ("threat model", "vision", "handoff") carries a different meaning under each lens and
   a copy looks like an independent second source.
+- **Use-case grounding (same reviews; the two-check gate whose owning definition
+  is the code lens's `templates.md` `## Use Cases / User Needs` comment — cite it,
+  never restate it).** On an L3 impact/solution analysis (Standalone) or `D-UC`
+  (Hybrid), two findings live here and nowhere else: **a product name in no
+  bucket** — the use-cases name a thing that neither EXISTS in the product (called
+  by the term the product itself uses; a renamed existing thing is a phantom), nor
+  is declared NEW in this change, nor is a pure METAPHOR kept out of the interface;
+  it invents system reality that is not there. And **a use-case that traces to no
+  Vision / M-VISION benefit** — a need the vision does not want, which is drift.
+  This gate checks the use-cases are GROUNDED and runs BEFORE the owner's own
+  review, never replacing it; coverage of each use-case by the Impact, and the
+  Actor it serves, stay the conformance-statement clause above. A lens whose
+  template defines no `## Use Cases` section never fires this clause.
 - **Capability Ledger (same reviews).** **An L3 impact/solution analysis or design
   that carries NO Capability Ledger is itself a finding** — the lens's capability
   pass (`architect.md` in the code lens, `taxonomy.md` in the knowledge lens) left
@@ -168,6 +181,29 @@ When you are the reviewer:
   mark ANALYZED, with no searches named**, is the finding that matters most on a
   project the methodology arrived in recently — an unread map reported as an empty
   one is how a duplicate of the existing codebase gets designed.
+- **Interface Contract (same reviews; fires only in the lens whose template
+  defines the section — the code lens today).** When the change creates or
+  modifies an actor-facing surface (the trigger's owning definition is the code
+  lens's `templates.md` section comment — cite it, never restate it), **an
+  artifact carrying NO `## Interface Contract` is itself a finding** — "the
+  artifact does not have one" is what a skipped contract looks like, not a reason
+  to skip the check. When the contract is there, these findings live here: a
+  use-case with no named interaction flow realizing it; **a flow that is not
+  walkable at the responsibility level** — it jumps from the actor's action to
+  the outcome without naming the components it traverses; **a *how* inside the
+  contract** — a mechanism, algorithm, data structure, widget or file-level
+  design — which is Solution-leakage (the flow NAMES components as
+  responsibility-holders, it never designs them); **required feedback that omits
+  an error or intermediate state, or a software actor's return status** (feedback
+  is universal, not human-only); a design or diff element that alters a
+  contracted surface, flow or feedback with no explicit renegotiation note (after
+  design approval that is a scope change owed to the user, not a design detail);
+  a contracted flow the `## Test Strategy` does not cover; and a new interaction
+  idiom introduced where the contract's own as-is names an existing one, with no
+  declared reason. (The architectural constraints the surface must live with are
+  NOT checked here — architecture-awareness is the Capability Ledger / Impact
+  review's job; a clause for it would duplicate that.) A lens whose template
+  defines no such section (knowledge, marketing) never fires this clause.
 ## Anti-patterns

package/skills/mkt-agentic-sdlc/scripts/sdlc_core.py CHANGED Viewed

@@ -245,6 +245,7 @@ REQUIRED_CAPABILITIES = frozenset({
 # Listed here so "this distribution does not claim it" is a visible decision.
 OPTIONAL_CAPABILITIES = frozenset({
     "architect_pass",         # does the component already exist? (code overlay)
+    "interaction_contract",   # actor-facing surface spec between use cases and solution (code overlay)
     "taxonomy_pass",          # do the categories/topics already exist? (knowledge overlay)
     "comprehension_guides",   # source_kind: code maps of complex components
     "tdd",                    # test-first discipline
@@ -841,8 +842,11 @@ def registry_conversion_blockers(root):
     if not hand.is_file():
         return []
     text = read_text(hand)
-    if "GENERATED by sdlc_check.py index" in text:
-        return []                                   # already ours
+    # "Already ours" = written by ANY family entry point: the header is WRITTEN
+    # with entry_script(), so recognition must not hard-code one distribution's
+    # script name (a registry generated by mkt_check.py is just as generated).
+    if re.search(r"GENERATED by \S+ index - do not edit by hand", text):
+        return []
     blockers = []
     known = {str(m.get("workstream")).strip() for _p, m in list_workstreams(root)}
     orphans = [r for r in parse_registry_rows(text) if r not in known]