@antoneeo/mkt-agentic-sdlc-skill 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.27.0] - 2026-10-27
+
+### Added
+- Shared knowledge layer (F-084, kb CHANGELOG): `inventory <path>` and orient's upper bound of never-examined project files reach this lens; `validate`/`check` refuse a malformed `audit/INVENTORY_exclusions.md` row and the new `DECLARED`/`DIVERGES` claim rules; the docs site renders them. `sdlc_core.skip_dir` is extracted from `iter_files`, behaviour unchanged.
+- `constraints --unit <id>` and `constraints --file <path>` (shared core): the constraints an ANALYSIS states in extractable form, each with its line, ending with the sections they could not extract.
+- `benefit` and the docs site recognize a REVIEW_LOG row with tier `post-merge` (written by the code lens: the owner's report of a wrong behaviour in a merged change): `benefit` keeps it out of every review figure, the docs site shows it as "defect reported after merge". `review.md`: a reviewer derives callers and behaviours before comparing with the constraint view.
+- `guides.md`: a code guide may carry a `## Preservation constraints` section copied from a closed unit; it survives regeneration. Nothing else changes in this lens: `validate` adds no note.
+
+### Fixed
+- Shared claim checks (`check`): a `RULING` row on a note that names a foreign origin (`imported_from:`) is refused — relabelling an imported row is not ratifying it; the message for a row superseded by an `IMPORTED` one names the ratification act (F-083).
+- Guide-verdict check (`verdict --hook`, shared core): a level quoted inside a sentence (`Level: L1` in prose) no longer counts as a declaration: only a line that opens with the level word does, the rule the constraint recall already uses (level 1 alone, `L1` or `E1`; levels 2 and 3 with `router` on the same line). The check now judges the project, and its docs-root name, that holds the edited file, not the one around the session's working directory; after a `cd` out of the project it let every edit through. A router verdict follows the same rule: only a line that opens with `router` or declares the level with it counts, never `router: no match` quoted in a sentence; `Level: Spike · router: …` and markdown openers (`##`, `1.`, `•`) count. A quote that itself opens a line (blockquote, code fence) still counts. The protected-path gate (`gate --hook`, `gate --file`) also judges the edited file's project, falls back to the session's project when no docs root sits above the file, and stays silent instead of exiting with an error when two docs roots sit side by side. Its `--protected` prefixes are relative to the nearest docs root above the edited file: with nested docs roots (a monorepo package with its own `ai_docs/`, or a docs folder inside a protected path) rewrite them relative to that root, or the path is no longer protected.
+
 ## [0.26.0] - 2026-10-23
 
 ### Changed

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "mkt-agentic-sdlc",
-  "version": "0.26.0",
+  "version": "0.27.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

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

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

@@ -54,15 +54,15 @@ Semantics: exit code 2 + message on stderr ⇒ the write is blocked and the mess
 
 **Usage warnings:**
 - The gate is deliberately coarse: applied to all of `src/` it would also block the legitimate L1/L2 tasks foreseen by the Triage. Use it **only on security-critical directories** (`--protected "src/auth;src/crypto"`), where "never without analysis" is the desired policy.
-- The paths in `--protected` are prefixes relative to the project root, separated by `;`.
+- The paths in `--protected` are prefixes relative to the root of the project the hook judges (below), separated by `;`. With nested docs roots (a monorepo whose package has its own), that is the nearest one above the edited file: write the prefixes relative to it.
 - `ai_docs/`, `tests/` and `test/` are always excluded from blocking.
-- The hook assumes the working directory is the project root (standard behavior of Claude Code hooks).
+- The hook judges the project, and the docs root, holding the edited file: the session's working directory can move with a `cd`, so it is never the reference. With no docs root above the file, it is the session's own project, as before. `--root <path>` overrides it; `gate --file` resolves the same way, and two docs roots side by side leave the gate silent.
 - **Hybrid/devPNT projects**: add `--hybrid` to the gate command. Governed designs live in the devPNT DB, so the gate also unlocks when an approved E-TDD shadow (`ai_docs/solutions/SHADOW_*tdd*.md`, exported before implementation — see `hybrid.md` §Ownership matrix) is present. Without the flag the gate would block legitimate governed work. The flag is deliberately explicit: never auto-detected.
 
 ### Verdict check: `verdict` (PreToolUse -- manual for this lens)
 
 `mkt_check.py verdict --hook` refuses an Edit, Write, MultiEdit or NotebookEdit when the
-session transcript shows no guide-router verdict (`router: …`, or a level-1 declaration)
+session transcript shows no guide-router verdict (a line that opens with `router: …` or with the level, `Level: L2 · router: …`, `Level: Spike · router: …`; or one that opens with a level-1 declaration)
 or a guide the verdict names was never read; it is silent in projects without guides and
 whenever it cannot tell. The code package (`agentic-sdlc`) wires it machine-wide on
 Claude Code; this package does not. To wire it by hand, add a `PreToolUse` entry with

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

@@ -1,6 +1,6 @@
 ---
 name: mkt-agentic-sdlc
-version: 0.26.0
+version: 0.27.0
 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

package/skills/mkt-agentic-sdlc/docs_site/app.js

@@ -12,7 +12,7 @@
   var D = null;   // documents, loaded on first use
   var K = null;   // knowledge base, loaded on first use
   var app = document.getElementById("app");
-  var ORIGINS = ["given", "elicited", "derived", "ruling", "imported"];
+  var ORIGINS = ["given", "elicited", "derived", "ruling", "imported", "declared"];
 
   // ------------------------------------------------------------- helpers
 
@@ -483,6 +483,7 @@
     if (f.statement) marks.push(el("span", { "class": "tag statement", title: t("statement_notice"), text: t("statement_mark") }));
     if (f.state === "superseded") marks.push(el("span", { "class": "tag replaced", title: t("state_superseded_why"), text: t("state_superseded") }));
     if (f.state === "contested") marks.push(el("span", { "class": "tag conflict", title: t("state_contested_why"), text: t("state_contested") }));
+    if (f.state === "diverges") marks.push(el("span", { "class": "tag conflict", title: t("state_diverges_why"), text: t("state_diverges") }));
     if (opts && opts.topic) marks.push(link("#/topic/" + encodeURIComponent(f.topic), f.topic, "chip"));
     return el("li", { "class": "fact" + (f.state === "superseded" ? " replaced" : ""), onclick: function () { location.hash = "#/fact/" + encodeURIComponent(id); } },
       el("span", { "class": "dot bg-" + oc }),
@@ -597,6 +598,11 @@
           el("p", { "class": "why-line", text: t("state_contested_why") }),
           el("ul", { "class": "facts" }, (f.with || []).map(function (s) { return factLine(s, { topic: true }); })));
       }
+      if (f.state === "diverges") {
+        parts.push(el("h3", null, el("span", { "class": "tag conflict", text: t("state_diverges") }), " ", t("fact_diverges_from")),
+          el("p", { "class": "why-line", text: t("state_diverges_why") }),
+          el("ul", { "class": "facts" }, (f.diverges_from || []).map(function (s) { return factLine(s, { topic: true }); })));
+      }
       if (f.grounds) {
         parts.push(el("h3", { text: t("fact_rests_on") }),
           el("p", { "class": "why-line", text: t("ground_class_" + f.ground_class) }),

package/skills/mkt-agentic-sdlc/docs_site/strings.js

@@ -56,7 +56,9 @@ window.DOCS_SITE_STRINGS = {
   event_request: "request record",
   event_note: "note",
   event_source: "source document received",
+  event_sent: "document sent",
   event_review: "review",
+  event_defect: "defect reported after merge",
   event_decision: "decision record",
   event_project_note: "project note",
   event_spike: "exploration outcome",
@@ -231,6 +233,8 @@ window.DOCS_SITE_STRINGS = {
   origin_ruling_why: "Taken to settle a conflict.",
   origin_imported: "from another knowledge base",
   origin_imported_why: "Brought in from another knowledge base, where its own sources are.",
+  origin_declared: "declared by this project",
+  origin_declared_why: "What this project told a recipient, on the day it was sent: a statement of ours, not a fact about the product.",
   origin_other: "origin as written: {v}",
   origin_other_why: "An origin this site does not know.",
 
@@ -239,6 +243,8 @@ window.DOCS_SITE_STRINGS = {
   state_superseded_why: "A newer fact takes its place.",
   state_contested: "in conflict",
   state_contested_why: "Facts that disagree, not yet settled.",
+  state_diverges: "diverges",
+  state_diverges_why: "What we declared contradicts what the project decided. It is corrected by a new send, or the decision changes.",
 
   statement_mark: "statement",
   statement_prefix: "[statement] {text}",
@@ -254,6 +260,7 @@ window.DOCS_SITE_STRINGS = {
   fact_replaced_by: "Replaced by",
   fact_current_at_end: "Current fact at the end of each chain",
   fact_in_conflict_with: "In conflict with",
+  fact_diverges_from: "Diverges from",
   fact_rests_on: "What it rests on",
   fact_untraced: "This part could not be traced.",
   fact_sources: "Sources",
@@ -266,6 +273,7 @@ window.DOCS_SITE_STRINGS = {
   fact_unknown: "This fact is not in this knowledge base.",
 
   ground_document: "a document",
+  ground_declared: "a document this project sent",
   ground_statement: "a person's statement",
   ground_decision: "a decision",
   ground_kb: "another knowledge base",
@@ -273,6 +281,7 @@ window.DOCS_SITE_STRINGS = {
   ground_class_statement: "Rests, at least in part, on a person's statement.",
   ground_class_untraceable: "Part of what it rests on could not be traced.",
   ground_class_imported: "Rests on another knowledge base.",
+  ground_class_declared: "Rests on our own declaration to a recipient, not on evidence.",
   ground_class_documents: "Rests on documents or decisions only.",
 
   chain_loop: "The chain of replacements loops back to {id}: it stops here.",

package/skills/mkt-agentic-sdlc/docs_site/style.css

@@ -18,6 +18,7 @@
   --o-derived: #a99be0;
   --o-ruling: #7fa7e6;
   --o-imported: #9cc96b;
+  --o-declared: #d98fb0;
   --conflict: #e0605a;
   --display: "Iowan Old Style", "Palatino Linotype", Palatino, "Book Antiqua", Charter, Georgia, serif;
   --body: "Segoe UI Variable Text", "Avenir Next", Avenir, "Gill Sans Nova", "Gill Sans", "Trebuchet MS", sans-serif;
@@ -179,6 +180,7 @@ a.factid code { color: var(--link); }
 .o-derived { color: var(--o-derived); } .bg-derived { background: var(--o-derived); }
 .o-ruling { color: var(--o-ruling); } .bg-ruling { background: var(--o-ruling); }
 .o-imported { color: var(--o-imported); } .bg-imported { background: var(--o-imported); }
+.o-declared { color: var(--o-declared); } .bg-declared { background: var(--o-declared); }
 .o-other { color: var(--paper-3); } .bg-other { background: var(--paper-3); }
 
 .panel {

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

@@ -262,6 +262,12 @@ in the snapshot, never to your assumption about what the code does.
   (source-anchored), not an elaborated version of it.
 - When in doubt about whether something is "supported" by the source, treat it
   as not covered rather than stretching the marker to fit.
+- **Declared exception: `## Preservation constraints`.** A code guide may carry
+  this section, copied at an L3 closure from the ANALYSIS's table (code lens,
+  `SKILL.md` Phase 5). The section's marker cites each row it holds as
+  `[source: solutions/ANALYSIS_<name>.md#P<n>]` instead of a snapshot anchor: each
+  row records what the code must keep doing, as that unit enumerated and probed it,
+  not an excerpt of the code.
 
 ## 4. Ingestion bound (T9)
 
@@ -293,5 +299,7 @@ state it explicitly when handing off a newly created guide.
   closure (docs travel with the code); when you merely READ one, check it against
   the code before trusting it. Too large to absorb → mark it `SUPERSEDED` rather
   than leave a confident-wrong map badged CURRENT, which is worse than none.
+- **A regenerated guide keeps `## Preservation constraints` unchanged**: the
+  section does not come from the snapshot (§3), so regeneration carries it over.
 - **Agent-global KB guides** use the same pipeline and validator via
   `--root ~/.agentic-sdlc`; freshness via the same `stale` engine.

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

@@ -187,7 +187,10 @@ can block forever gets removed. **Log one row per completed review, PASS or FAIL
 logging only passes would erase exactly that evidence. The row goes in
 `ai_docs/audit/reviews/REVIEW_LOG.md` (create it if absent — `templates.md`):
 `| date | doc_key | tier | model | reviewer | findings_raised | findings_real | verdict | revise_rounds |`,
-with `tier` = `design` or `closure` in Standalone. **`model` records the capability
+with `tier` = `design` or `closure` in Standalone. In the code lens, a wrong behaviour
+the owner reports in a merged L3 change is one row too, tier `post-merge`, `model`
+`none (owner report)`, reviewer `owner`, the owner quoted in the notes: a defect
+record, not a review, so `benefit` keeps it out of every review figure. **`model` records the capability
 tier that actually ran** — `deep`, `light`, `economy`, `single (client exposes no
 choice)`, `below floor: <reason>`, or `none (not due)` on a NOT DUE row — never a provider name in doctrine (a project
 may of course write its own model names in its own log). Without it the floor above
@@ -285,6 +288,11 @@ The binding inputs, by review type:
   clause reads both), and the **probe harness** (`ai_docs/solutions/harness_[feature]/`).
   Hand these *in addition to* the design artifact — the reviewer checks the artifact
   **against** them, not only for internal consistency.
+- **The constraint view comes last.** Where the ANALYSIS carries ids, the reviewer
+  derives the callers and behaviours first, then compares with
+  `sdlc_check.py constraints --unit <id>`: a constraint the design states and the
+  diff breaks is a finding. The view never replaces the ANALYSIS or the diff in the
+  request.
 - **For a closure review, the diff and the test evidence**: the run output that
   backs every completion claim, dated after the final relevant change.
 - **For a design or closure review of an L3/E3 unit, the request record**

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

@@ -615,6 +615,11 @@ class Grounds:
             return [{"kind": "untraceable", "path": rel}]
         seen = seen | {rel}
         if rel.startswith("corpus/given/"):
+            # F-084: a document this project SENT is our own declaration, not
+            # ground for a fact about the product.
+            side = self._meta(rel + ".meta.md")
+            if _v(side, "provenance").upper() == "DECLARED":
+                return [{"kind": "declared", "path": rel}]
             return [{"kind": "document", "path": rel}]
         if not _inside(self.docs, rel) or not (self.docs / rel).is_file():
             return [{"kind": "untraceable", "path": rel}]
@@ -643,6 +648,8 @@ def ground_class(leaves):
         return "statement"
     if "untraceable" in kinds:
         return "untraceable"
+    if "declared" in kinds:
+        return "declared"
     if "kb" in kinds:
         return "imported"
     return "documents"
@@ -707,12 +714,15 @@ def build_kb(docs):
             kind, rest = _kind(r)
             f = {"text": r["claim"], "valid": r["valid"], "qty": r["qty"], "about": r["about"],
                  "origin": (r["prov"] or "").strip().lower(), "topic": slug,
-                 "state": {"SUPERSEDED": "superseded", "CONTESTED": "contested"}.get(kind, "ok")}
+                 "state": {"SUPERSEDED": "superseded", "CONTESTED": "contested",
+                           "DIVERGES": "diverges"}.get(kind, "ok")}
             if kind == "SUPERSEDED":
                 f["successors"] = _ids(rest)
                 f["chain_ends"] = chain_ends(r["id"], by_id)
             if kind == "CONTESTED":
                 f["with"] = _ids(rest)
+            if kind == "DIVERGES":
+                f["diverges_from"] = _ids(rest)
             srcs = []
             for src in r["source"].split(";"):
                 src = src.strip()
@@ -1246,7 +1256,9 @@ def chronology(docs, pages):
     text = _text(docs / rel) if (docs / rel).is_file() else None
     if text is not None:
         for row in sdlc_core.parse_review_log(text)[0]:
-            add(row["date"], "review", "%s — %s: %s" % (
+            # F-085: a `post-merge` row is the owner's defect report, not a review
+            kind = "defect" if row["tier"].lower().startswith("post-merge") else "review"
+            add(row["date"], kind, "%s — %s: %s" % (
                 row["doc_key"], row["tier"], row["verdict"]), rel)
     for p in sorted(docs.glob("architecture/ADR_*.md")):
         rel = "architecture/" + p.name
@@ -1269,7 +1281,9 @@ def chronology(docs, pages):
                 continue
             if kind == "source":
                 name = p.name[:-len(suffix)]
-                add(date, kind, name, rel, source=name)
+                # F-084: a DECLARED sidecar's date is the day it was SENT
+                sent = _v(fm, "provenance").upper() == "DECLARED"
+                add(date, "sent" if sent else kind, name, rel, source=name)
             else:
                 add(date, kind, title_of(rel, text), rel)
     # Most recent first. Within one day a document's later entry is the more recent