@antoneeo/mkt-agentic-sdlc-skill 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.3.1 — 2026-08-02
+
+### Fixed
+- **The multi-lens routing note announced this skill as the code lens.** `init.js` wrote
+  the row for the CURRENT lens as a hardcoded literal copied from the code distribution,
+  so a project initialised with `mkt-sdlc-init` listed `agentic-sdlc` twice and never
+  named `mkt-agentic-sdlc`. Both the self row and the sibling table are now derived from
+  the shared `routing.md` lens table. Found by a cold-agent field test.
+- **`FACT` was the way past the evidence rule.** `BENCHMARK` owes a source URL and
+  `ASSUMPTION` a range; `FACT` owed nothing, so a researched observation classed FACT
+  with source "see research/VOC.md" entered the ledger unsourced. `mkt_check.py` now
+  errors on a FACT with no source, or one pointing at a document of the engagement,
+  while exempting a cell that names the client as origin. `research.md` states the two
+  legal origins.
+- `review.md` (shared spine): a review verdict travels as the reviewer's final output.
+
+## 0.3.0 — 2026-08-01
+
+- **One shared core, three lenses.** This skill is now built from the family's spine
+  instead of a copy of it: triage, the Vision gate, the review gates, the guide router,
+  question discipline and the validator core are byte-identical with
+  `@antoneeo/agentic-sdlc-skill` and `@antoneeo/kb-agentic-skill`, and a drift guard
+  verifies it on every build. `routing.md` decides which lens owns a unit of work when
+  more than one is installed.
+- `mkt_check.py` forwards every spine subcommand it does not intercept by iterating the
+  spine's parser — the hand-copied command tuple used to drop `migrate` while `SKILL.md`
+  documented it.
+
 ## 0.2.1 — 2026-07-09
 
 - **Install DX fix**: README + the generated project protocol pointer no longer present `mkt-sdlc-install-skill` as a required second step. `npm i -g` alone installs the skill (the `postinstall` runs the installer); the manual command is documented as a fallback via `npx mkt-sdlc-install-skill` for setups that block install scripts, with an explicit note that the bare command is only on PATH after a global install. Prevents the "command not recognized" error after a local `npm i`.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "mkt-agentic-sdlc",
-  "version": "0.3.0",
+  "version": "0.3.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)"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antoneeo/mkt-agentic-sdlc-skill",
-  "version": "0.3.0",
+  "version": "0.3.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",

package/scripts/init.js

@@ -3,14 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const { SKILL_SOURCE, CLIENTS, clientDetected, skillTarget, loadTemplates, templateFor } = require('./lib');
-
-// Sibling lenses of the same family: one shared core, one `ai_docs/` tree, a different
-// fidelity discipline each. Keyed by the installed skill directory name.
-const SIBLING_LENSES = {
-  'kb-agentic': 'knowledge',
-  'agentic-sdlc': 'code',
-};
+const { SKILL_SOURCE, INSTALLED_SKILL_NAME, SELF_LENS, SIBLING_LENSES, CLIENTS, clientDetected, skillTarget, loadTemplates, templateFor } = require('./lib');
 
 const cwd = process.cwd();
 
@@ -159,7 +152,7 @@ if (siblings.size > 0) {
 This project has more than one lens of the Agentic SDLC family installed:
 
 ${list}
-- \`agentic-sdlc\` — the **code** lens
+- \`${INSTALLED_SKILL_NAME}\` — the **${SELF_LENS}** lens
 
 One \`ai_docs/\` tree, one project default (\`default_domain:\` in \`ai_docs/README.md\`),
 one lens per unit of work. Before acting on any L2, L3 or Spike, run the domain router
@@ -186,7 +179,7 @@ Delete it once the merge is done.
 `, 'multi-lens routing note');
   if (wrote && protocolPreexisting) {
     console.log('   ⚠️  A protocol pointer already existed and was NOT overwritten.');
-    console.log('       Merge the code-lens ladder from AGENTIC_MULTI_LENS.md into it by hand.');
+    console.log(`       Merge the ${SELF_LENS}-lens ladder from AGENTIC_MULTI_LENS.md into it by hand.`);
   }
 }
 

package/scripts/lib.js

@@ -1,183 +1,233 @@
-// 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');
-// Kept for backward compatibility with this package's own scripts; the
-// authoritative value is INSTALLED_SKILL_NAME, derived from SKILL.md below.
-// The directory name each client loads the skill from. Derived from the manifest,
-// never hard-coded by a consumer: three distributions share these scripts, and a
-// literal here is how a copy-fork starts installing under its sibling's name.
-const INSTALLED_SKILL_NAME = (() => {
-  const m = fs.readFileSync(path.join(SKILL_SOURCE, 'SKILL.md'), 'utf8').match(/^name:\s*(\S+)/m);
-  if (!m) throw new Error(`SKILL.md carries no 'name:' field: ${SKILL_SOURCE}`);
-  return m[1];
-})();
-
-// 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.
-
-// 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, INSTALLED_SKILL_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 = {
-  INSTALLED_SKILL_NAME,
-  PACKAGE_ROOT,
-  SKILL_SOURCE,
-  TEMPLATES_PATH,
-  CLIENTS,
-  commandExists,
-  clientDetected,
-  skillTarget,
-  copyRecursive,
-  loadTemplates,
-  templateFor,
-};
+// 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');
+// Kept for backward compatibility with this package's own scripts; the
+// authoritative value is INSTALLED_SKILL_NAME, derived from SKILL.md below.
+// The directory name each client loads the skill from. Derived from the manifest,
+// never hard-coded by a consumer: three distributions share these scripts, and a
+// literal here is how a copy-fork starts installing under its sibling's name.
+const INSTALLED_SKILL_NAME = (() => {
+  const m = fs.readFileSync(path.join(SKILL_SOURCE, 'SKILL.md'), 'utf8').match(/^name:\s*(\S+)/m);
+  if (!m) throw new Error(`SKILL.md carries no 'name:' field: ${SKILL_SOURCE}`);
+  return m[1];
+})();
+
+// The family's lens table, read from the shared `routing.md` rather than restated
+// here. Same reason as INSTALLED_SKILL_NAME above, and the same failure it prevents:
+// BOTH the row for this lens and the rows for its siblings used to be literals copied
+// between distributions, so kb and mkt wrote a multi-lens note announcing themselves
+// as the code lens. routing.md is one of the byte-identical shared files, so this
+// lookup cannot drift between distributions.
+// Lazy on purpose: preuninstall.js needs INSTALLED_SKILL_NAME and nothing else, and
+// must keep working on an installation damaged badly enough to have lost routing.md.
+function lensTable() {
+  const routing = path.join(SKILL_SOURCE, 'routing.md');
+  if (!fs.existsSync(routing)) throw new Error(`routing.md missing from the skill: ${SKILL_SOURCE}`);
+  // Parsed as a table, not matched with a regex: a mis-escaped pattern matches the
+  // empty string and yields undefined instead of throwing, which is how this lookup
+  // failed the first time it was written.
+  const table = new Map();
+  for (const line of fs.readFileSync(routing, 'utf8').split(/\r?\n/)) {
+    const cells = line.split('|').map((cell) => cell.trim());
+    if (cells.length < 4) continue;
+    const [, lens, skill] = cells;
+    if (!/^[a-z]+$/.test(lens) || !/^`[a-z0-9-]+`$/.test(skill)) continue;
+    const name = skill.slice(1, -1);
+    // A duplicate row would otherwise be won silently by whichever came first, and a
+    // wrong routing.md propagates byte-identically to every distribution.
+    if (table.has(name)) throw new Error(`routing.md lists '${name}' more than once`);
+    table.set(name, lens);
+  }
+  if (!table.size) throw new Error(`routing.md carries no lens table: ${routing}`);
+  return table;
+}
+
+function selfLens() {
+  const lens = lensTable().get(INSTALLED_SKILL_NAME);
+  if (!lens) throw new Error(`routing.md has no lens row for '${INSTALLED_SKILL_NAME}'`);
+  return lens;
+}
+
+// Sibling lenses of the same family: one shared core, one docs tree, a different
+// fidelity discipline each. Keyed by the installed skill directory name.
+function siblingLenses() {
+  const table = lensTable();
+  selfLens();                       // this lens must be in the table too
+  table.delete(INSTALLED_SKILL_NAME);
+  return Object.fromEntries(table);
+}
+
+// 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.
+
+// 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, INSTALLED_SKILL_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 = {
+  INSTALLED_SKILL_NAME,
+  PACKAGE_ROOT,
+  SKILL_SOURCE,
+  TEMPLATES_PATH,
+  CLIENTS,
+  commandExists,
+  clientDetected,
+  skillTarget,
+  copyRecursive,
+  loadTemplates,
+  templateFor,
+};
+
+// Lazy: reading routing.md is deferred to the consumer that actually asks.
+Object.defineProperty(module.exports, 'SELF_LENS', { enumerable: true, get: selfLens });
+Object.defineProperty(module.exports, 'SIBLING_LENSES', { enumerable: true, get: siblingLenses });
+

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

@@ -16,7 +16,13 @@ piece of evidence:
   numbers as `[EV-nn]`.
 - **Class** (exactly one):
   - `FACT` — user input or primary data (their analytics, their CRM export).
-    Source = "user, Wave 1" or the data file.
+    Source = "user, Wave 1" or the data file. **Only these two origins.** An
+    observation *you* gathered — a forum quote, a competitor's page, a review
+    site — is a `BENCHMARK` however solid it looks, and owes its URL. FACT is
+    the one class the URL rule cannot reach, so classing research as FACT is
+    the way an unsourced number gets in wearing the strongest label; the
+    validator now rejects a FACT whose Source names one of your own documents
+    or says "see X".
   - `BENCHMARK` — external number. Source URL **and** publication date
     mandatory. The Source cell must carry the actual external URL, NOT a
     pointer to one of your own research documents that aggregates it ("see

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

@@ -85,6 +85,14 @@ When you hand work to a reviewer (human or agent), give them:
   should have been. The design reviewer checks that every threat surface the change
   touches has a matching security requirement.
 
+**The verdict travels back as the reviewer's own final output** — the text it
+returns when it finishes, nothing else. A reviewer that tries to message the
+requester mid-run depends on a delivery channel it cannot verify (a subagent
+addressed by agent TYPE rather than by session gets no such channel, and the
+attempt fails silently); a requester that waits for such a message stalls
+holding a verdict that already exists. State the return form when you request
+the review, and read the verdict where it actually arrives.
+
 Never ask a reviewer to "review my session" or "review what I just did"
 without the artifacts above — that forces them to reconstruct scope from
 conversation instead of reviewing the change itself. Say which finding
@@ -109,6 +117,10 @@ When you are the reviewer:
 
 - Verify claims against the real source, not against the diff's own
   description of itself.
+- **Your verdict is your final output.** Deliver findings and verdict as the text
+  you return when you finish — never only through a message to the requester, a
+  channel you cannot verify and which fails silently when it is not there
+  (see `## Requesting`).
 - Cite evidence as `file:line` for every finding — a finding without a
   location is not actionable.
 - Keep severity honest: do not inflate a style preference to a blocker, and

package/skills/mkt-agentic-sdlc/scripts/mkt_check.py

@@ -84,6 +84,18 @@ VALID_STATUS = ("CURRENT", "SUPERSEDED", "DRAFT", "DEPRECATED")
 LEDGER_CLASSES = ("FACT", "BENCHMARK", "ASSUMPTION")
 CONFIDENCE_VALUES = ("HIGH", "MED", "MEDIUM", "LOW")
 EV_REF = re.compile(r"\[(EV-\d+)\]")
+# A source that points INSIDE this engagement instead of at the world: a document of
+# OUR OWN under a canonical dir, or the "see X" form. Only FACT can carry it today,
+# because FACT is the one class the URL rule does not reach.
+INTERNAL_SOURCE_RE = re.compile(
+    r"(?:\b(?:mkt_docs|ai_docs|research|strategy|tactics|deliverables|vision)/\S*\.md\b"
+    r"|\b(?:see|vedi|cfr\.?)\s)", re.IGNORECASE)
+# The two origins research.md sanctions for a FACT. A cell that opens by naming the
+# client is exempt: their own primary data may well be a Markdown file they handed
+# over, and telling its author to "reclassify as BENCHMARK and add a URL" would be
+# advice to misclassify.
+CLIENT_ORIGIN_RE = re.compile(
+    r"^\s*(?:user|client|owner|utente|cliente|titolare|proprietario)\b", re.IGNORECASE)
 OBJECTIVE_HEADING = re.compile(r"^###\s+(O\d+)\b", re.MULTILINE)
 OBJECTIVE_TOKEN = re.compile(r"\bO\d+\b")
 EXAMPLE_MARKER = "(example)"
@@ -370,6 +382,20 @@ def run_ledger(root):
                 rep.error(f"ledger {rid}: BENCHMARK without a source URL")
             if not date:
                 rep.error(f"ledger {rid}: BENCHMARK without a date")
+        if cls == "FACT" and not source:
+            rep.error(f"ledger {rid}: FACT without a source -- name the origin "
+                      "('user, Wave 1' or the client's data file)")
+        if (cls == "FACT" and source and not CLIENT_ORIGIN_RE.match(source)
+                and INTERNAL_SOURCE_RE.search(source)):
+            # FACT means "the client told me" or "the client's own primary data" — the
+            # one class that legitimately has no URL. Pointing it at another document
+            # of this engagement is how a researched observation gets in without the
+            # URL its class would owe: the row cites a file that cites the source, the
+            # validator resolves nothing, and "see VOC.md" is exactly the form the
+            # BENCHMARK rule rejects. Observed in a cold-agent field test, 2026-08-02.
+            rep.error(f"ledger {rid}: FACT sourced to an internal document ('{source}') -- "
+                      "a FACT is what the client stated or their own primary data; an "
+                      "observation gathered by research is a BENCHMARK and owes its URL")
         if cls == "ASSUMPTION":
             if confidence not in CONFIDENCE_VALUES:
                 rep.error(f"ledger {rid}: ASSUMPTION without confidence (HIGH|MED|LOW)")