@antoneeo/mkt-agentic-sdlc-skill 0.9.0 → 0.11.0

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

@@ -60,6 +60,10 @@ already cover how to do this well?*
   match was not targeted (T7). Two guides are legitimate only when they cover
   distinct concerns — typically an operative guide plus the comprehension map of
   the component being touched; three is a smell, not a thorough lookup.
+- **Check a `code` guide against the code before you trust it.** No check can do
+  this for you (§6): the reader is the only one who sees that the map and the
+  component have parted. A divergence you observe is yours to close in the same
+  unit of work.
 - **Under subagent dispatch** the consult happens at plan-authoring time (the
   orchestrator populates each task's `guides` field); a context-free subagent
   reads the pointers it was handed and does not run its own router lookup. See
@@ -271,17 +275,17 @@ state it explicitly when handing off a newly created guide.
 
 ## 6. Maintenance
 
-- **Source changed**: create a new snapshot (new hash), regenerate the guide
-  from it (new `source_hash`), and if the guide is replacing a prior guide
-  rather than updating in place, mark the old one `status: SUPERSEDED`.
-- **`stale` flags hash drift**: `sdlc_check.py stale` (also under `--hybrid`)
-  compares each guide's recorded `source_hash` against the live snapshot file
-  and reports `[stale]` when they diverge — that is the signal to regenerate,
-  not a manual freshness check.
-- **`source_kind: code` freshness**: `stale` works unchanged (the code-excerpt
-  snapshot drifts when the code changes → regenerate). ADDITIONALLY, when you modify
-  the code a comprehension guide describes, refresh that guide in the SAME closure
-  (docs travel with the code) — do not wait for `stale` to catch it. A stale
-  comprehension guide is a confident-wrong map, worse than none.
+- **Source changed**: new snapshot, regenerate the guide from it (new
+  `source_hash`); a guide REPLACING another is `status: SUPERSEDED` on the old
+  one. `sdlc_check.py stale` (also under `--hybrid`) reports `[stale]` when a
+  guide's recorded hash and its snapshot file diverge — the signal to regenerate.
+- **`source_kind: code` freshness is NOT mechanized.** `stale` compares the guide
+  to its snapshot, and a code snapshot is a frozen copy — so a map whose component
+  was rewritten reports FRESH forever (measured 2026-09-06: +388/-71 lines in the
+  guided module, `stale` silent). The duty is therefore the author's, twice: when
+  you MODIFY code a comprehension guide describes, refresh the guide in the same
+  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.
 - **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/hybrid.md

@@ -0,0 +1,47 @@
+# The Hybrid Seam — coexistence with devPNT (marketing lens)
+
+**For whom**: the agent working a marketing engagement where the `devpnt_*` tools
+are available and point at this project.
+**Answers**: "which mode am I in, and who owns what when both authorities are live".
+**Does not answer**: the process itself — the engagement triage, the SOSTAC
+phases, the gates and the evidence discipline are `SKILL.md`'s, identical in both
+modes.
+
+Moved out of `SKILL.md` by F-052 so a Standalone session stops paying for a seam
+it cannot reach. **The content below is unchanged**: a relocation, not a rewrite.
+
+<!-- moved-block-sha256: b9b19d58a104e858f38460065160a61e64a6cd6f64f92c1bbf47fbf534d25ef6 -->
+### 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.

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

@@ -82,15 +82,92 @@ its outcome. The trigger term "permission-gated" scopes the STOP; the row word
 
 Use a different model from the author's where the client allows it.
 
+**The capability floor — which tier may run this role.** Independence says the
+reviewer must not be the author; it says nothing about whether the reviewer *can
+do the job*. A gate run below the capability its judgement needs produces the
+myopia the gate exists to catch, **while reporting as an independent review** —
+worse than no gate, because it certifies. So each role carries a minimum tier.
+Tiers are **client-relative capability levels, never provider names** (a name
+rots at the next model release; the tier→model binding lives in the client's own
+agent definition, never in this file):
+
+| Role | Floor | Why there |
+|---|---|---|
+| **authoring a governed artifact** (Vision, the analysis/design, use cases, the Interface Contract, threat model — `dispatch.md`'s never-list owns the enumeration) | **deep** | the purest case of the rule below: the output is judgement, nothing scores it, and `dispatch.md`'s never-list forbids moving it elsewhere — so the session's own capability IS this work's capability |
+| design review, closure review, any verdict on judgement | **deep** | the output is a judgement whose wrongness no check can see |
+| a light conformance or consistency pass (schema, coverage, citation resolution) | **light** | the criterion is stated and mechanical |
+| implementer dispatch, probe execution, anchor resolution, index regeneration | **economy** | a threshold signal catches a wrong cheap answer |
+
+The rule underneath the table: **a tier may be lowered only where a threshold
+signal exists** — `task.verify`, a test, a diff against a spec, an assertion
+harness — because that is what makes a wrong cheap answer visible instead of
+plausible. Where the output is judgement and nothing scores it, there is no
+signal to lower against, and the floor is the whole policy.
+
+**A session's floor is the highest floor among the roles it performs itself.** The
+table above binds reviewers and dispatched subagents, chosen per call — but the
+session doing the authoring was chosen by the USER before the agent existed, and
+an agent cannot re-tier itself mid-session. So the rule that reaches it is not
+routing, it is **disclosure**: where a session can determine that it is below the
+floor for a role it performs itself, it says so **once per session, at the first
+such role** — not once per unit — and the disclosure is repeated in the review
+row's existing `reviewer` cell (Hybrid: `notes`), which is what makes the pair
+below visible without adding a column.
+
+**Say plainly how thin this reach is.** A session knows its model NAME; tiers here
+are deliberately client-relative and this file maps no name to a tier, so the
+antecedent is satisfiable only where a session can recognize its own tier — which
+is also the session least likely to run the check. Where a session **cannot
+determine its own tier**, it owes nothing: the rule binds what an agent can know
+and say, never a capability it cannot acquire. **The reliably working half of this
+rule is the one addressed to the user, not to the agent** — which is why the
+package READMEs carry the tier-selection guidance, and why that is not a footnote.
+
+**Never both below the floor on the same unit — except when nothing better
+exists.** Where the authoring session ran below floor, the independent review's
+floor becomes non-negotiable and the same unit should not ALSO run a below-floor
+review. **The exception is the case *When independence and capability conflict*
+governs below**: where no independent rung at or above the floor exists at all,
+that rule wins, the review still runs, BOTH disclosures are recorded, and the
+result is not a violation but the worst admissible state — honestly labelled.
+Forbidding it outright would push the agent toward the abstention that rule
+explicitly rejects.
+
+**When independence and capability conflict, independence wins.** A client whose
+only independent rung is bound below the floor (a single-model client, or a
+subagent facility whose agent definition fixes a cheap model) still runs the
+gate: a below-floor *independent* reviewer catches the class the author is
+structurally blind to, while a self-pass catches none of it. What the floor then
+requires is **disclosure, not abstention** — the row records the tier that
+actually ran (`below floor: <reason>`), and that record IS the remedy. Where a
+higher-capability path exists but is permission-gated, nothing new applies: *The
+gated rung* above already governs, one question per gate per intact context.
+Where the client exposes no capability choice at all, the row says
+`single (client exposes no choice)` and the floor is satisfied by construction —
+it is a routing rule, and a routing rule with one route is not a failure.
+
 **Rounds are capped at 3.** FAIL → revise → re-review. If findings still stand
 after the third, stop and surface them to the user with the artifact — a gate that
 can block forever gets removed. **Log one row per completed review, PASS or FAIL**
 — a FAIL surfaced to the user is the highest-value outcome the gate produces, and
 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 | reviewer | findings_raised | findings_real | verdict | revise_rounds |`,
-with `tier` = `design` or `closure` in Standalone. One schema for both modes: a
-Hybrid project's devPNT gates write to the same file.
+`| date | doc_key | tier | model | reviewer | findings_raised | findings_real | verdict | revise_rounds |`,
+with `tier` = `design` or `closure` in Standalone. **`model` records the capability
+tier that actually ran** — `deep`, `light`, `economy`, `single (client exposes no
+choice)`, or `below floor: <reason>` — 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
+is a belief: the row would say a gate ran and never whether it could do its job, and
+the correlation with `revise_rounds` and `findings_real` — the only evidence the
+policy pays — could not be drawn.
+
+**One schema for both modes**, meaning one required CORE plus each mode's own
+**mode-specific** realization columns. The core is what both modes actually share: `date`, `doc_key`,
+`tier`, `model`, `findings_raised`, `findings_real`, `verdict`, `revise_rounds`.
+Around it, Standalone adds `reviewer` and Hybrid adds `instrument` and `notes` —
+a devPNT row carries no `reviewer` column at all, so "one identical column list"
+was never true of the two modes. This costs nothing for the reason `templates.md`
+§`ai_docs/audit/reviews/REVIEW_LOG.md` owns and states.
 The log is how the gate's value is measured over time; skipping it makes the gate
 unfalsifiable, the same defect as an unnamed EXISTS or a faked router verdict.
 

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

@@ -18,7 +18,7 @@ From the overlay (unchanged behaviour, unchanged exit codes):
   index    [--root R]              (re)generate INDEX.md
 
 From the shared core (new to this distribution):
-  stale / mark / gate / orient / plan / migrate   -- the spine commands, identical everywhere
+  stale / mark / gate / orient / benefit / plan / migrate   -- the spine commands, identical everywhere
 
 Both files must sit in the same directory. Copying only this one fails at import,
 loudly, which is the intended failure.
@@ -60,7 +60,7 @@ sdlc_core.set_profile(
     skill_name="mkt-agentic-sdlc",
     unit_noun="engagement",
     support_files=("templates.md", "frameworks.md", "research.md", "elicitation.md",
-                   "review.md", "routing.md", "guides.md", "vision.md", "dispatch.md",
+                   "review.md", "routing.md", "guides.md", "vision.md", "hybrid.md", "dispatch.md",
                    "ENFORCEMENT.md"),
     capabilities=(
         # spine
@@ -69,6 +69,14 @@ sdlc_core.set_profile(
         # marketing overlay
         "subagent_dispatch", "question_discipline",
     ),
+    remind_line=(
+        "first decide if this skill governs the work; if yes, LOAD it once -- an "
+        "unread protocol cannot be applied. Declare the engagement level and the "
+        "guide-router verdict before acting. Every claim about the market, the "
+        "audience or a competitor carries its evidence -- an unsourced assertion "
+        "is a finding, not a premise. Replay governing text -- a brief, a "
+        "positioning line, a template -- against the case that motivated it."
+    ),
     # The strategy is reviewed before any tactic is executed: nine phases, but the
     # ordering the gate cares about is the same one every domain owes.
     design_gate_between=("### 6. Strategy", "### 8. Action"),

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

@@ -268,16 +268,18 @@ _PROFILE = {
     "support_files": (),
     "capabilities": frozenset(),
     "design_gate_between": (),
+    "remind_line": "",
 }
 
 
 def set_profile(skill_name, support_files=(), capabilities=(), unit_noun="feature",
-                design_gate_between=()):
+                design_gate_between=(), remind_line=""):
     _PROFILE.update(skill_name=skill_name,
                     unit_noun=unit_noun,
                     support_files=tuple(support_files),
                     capabilities=frozenset(capabilities),
-                    design_gate_between=tuple(design_gate_between))
+                    design_gate_between=tuple(design_gate_between),
+                    remind_line=remind_line)
 
 
 def profile():
@@ -1318,7 +1320,7 @@ def cmd_validate(root, strict=False, hybrid=False):
         # comment-stripped, anchored: a '<!-- TODO: the ## Capability Ledger -->'
         # must not read as the section being present
         # Hybrid: the design lives in devPNT and its §4.5 gate owns this slot
-        # (SKILL.md ownership matrix: "run ONE of them, never both"), and its log
+        # (the Hybrid ownership matrix: "run ONE of them, never both"), and its log
         # rows are keyed on e_isp_/e_tdd_ doc_keys, not on this filename -- so
         # firing here would be a permanent, unfixable false positive.
         if not hybrid and design_review_due(meta) and not review_logged(root, p.name):
@@ -1796,6 +1798,43 @@ def cmd_check(root, strict=False, hybrid=False):
 
 # --------------------------------------------------------------------- gate
 
+# --- UserPromptSubmit reminder hook (F-046) --------------------------------
+# `orient` fires once per session and decays; a session that never invokes the
+# skill never had the protocol at all. Measured 2026-09-06: a release ran in
+# this repo against a `GUIDE_release.md` the session never consulted, because
+# SKILL.md -- where the duty is written -- had not been read.
+#
+# The carrier is kb's (F-041 item B), lifted here so all three lenses share one
+# machine instead of two that do the same thing. Its contract is kept: the line
+# is CONSTANT and reads NOTHING -- nothing repo- or session-controlled may ride
+# text injected every turn, and zero reads is what keeps the per-turn cost flat.
+# What changed is the payload's first duty and the wiring. First duty: decide
+# whether the skill governs this work and, if it does, read it once -- an
+# unread protocol cannot be applied, which is the failure above. Wiring: a
+# default instead of opt-in, on the owner's explicit acceptance of the per-turn
+# cost (`vision/rulings.md` r19; the "no ceremony ratchet" Non-Goal admits a
+# never-zero cost by that acceptance, and a trivial turn pays a yes/no
+# judgement, never a load).
+
+REMIND_FALLBACK = (
+    "decide whether the {skill} skill governs this work; if it does, load it "
+    "once before acting -- an unread protocol cannot be applied."
+)
+
+
+def cmd_remind(args):
+    """UserPromptSubmit hook: print the lens's constant per-turn line. Always 0.
+
+    argv is ignored whole and nothing is read: a hook surface must not fail, and
+    a flag typo must not cost a turn's context."""
+    try:
+        prof = profile()
+        line = prof.get("remind_line") or REMIND_FALLBACK.format(skill=prof["skill_name"])
+        print(f"{prof['skill_name']}: {line}")
+    except Exception:
+        pass
+    return 0
+
 def cmd_gate(args):
     file_path = args.file or ""
     if args.hook:
@@ -2013,6 +2052,237 @@ def cmd_plan(root, args):
     return 0
 
 
+# --- F-050: the benefit report -------------------------------------------
+# The process's central claim is that it makes divergence visible BEFORE
+# implementation. That claim lived in prose for four months while the evidence
+# for it sat unread in REVIEW_LOG. This reads it.
+#
+# Columns are resolved BY HEADER NAME, never by width. `templates.md` states
+# that contract ("extra or reordered columns are fine -- but the header must
+# say `tier`") and three widths are legal today: the original 8, Standalone's 9
+# (F-048 added `model`), and Hybrid's 10 (`instrument` + `notes`, and no
+# `reviewer` at all). A width whitelist reads none of the last, and silently
+# reports a devPNT-governed project as having no data at all.
+#
+# Two honesty rules, both learned from this unit's own review: whatever cannot
+# be read is COUNTED and NAMED, at the row level AND at the cell level. A ratio
+# over a silently shrunken denominator is worse than no ratio.
+REVIEW_CORE = ("date", "doc_key", "tier", "findings_real", "verdict")
+REVIEW_POSITIONAL = {
+    8: ("date", "doc_key", "tier", "reviewer", "findings_raised",
+        "findings_real", "verdict", "revise_rounds"),
+    9: ("date", "doc_key", "tier", "model", "reviewer", "findings_raised",
+        "findings_real", "verdict", "revise_rounds"),
+    10: ("date", "doc_key", "tier", "model", "instrument", "findings_raised",
+         "findings_real", "verdict", "revise_rounds", "notes"),
+}
+
+
+def _table_cells(line):
+    """Cells of a Markdown table row, or None when the line is not one.
+    Separator rows (---, :---:, any alignment colons) are not data."""
+    s = line.strip()
+    if not s.startswith("|"):
+        return None
+    if set(s) <= set("|-: "):
+        return None
+    return [c.strip() for c in s.strip("|").split("|")]
+
+
+def parse_review_log(text):
+    """-> (rows, unparsed). Columns come from the header when there is one.
+
+    Falls back to the positional maps only for a table with no header, so a
+    hand-kept log still reads. A row whose cell count does not match the
+    header's is unparsed and named -- never dropped."""
+    rows, unparsed, names = [], [], None
+    for n, line in enumerate(text.splitlines(), 1):
+        cells = _table_cells(line)
+        if cells is None:
+            continue
+        lowered = [c.lower() for c in cells]
+        if names is None and "tier" in lowered and "verdict" in lowered:
+            names = lowered                      # the header IS the column map
+            continue
+        # The header supplies the map -- that is what makes reordered and extra
+        # columns readable. But a log legitimately carries MIXED widths (F-048
+        # widened the schema and did not rewrite history), so a row that does
+        # not match the header is read by the positional map for its own width
+        # before it is given up on. Only a width no map knows is unparsed.
+        if names is not None and len(cells) == len(names):
+            row = dict(zip(names, cells))
+        else:
+            positional = REVIEW_POSITIONAL.get(len(cells))
+            if positional is None:
+                unparsed.append((n, "%d cells: %s" % (
+                    len(cells),
+                    "header declares %d and no positional map fits"
+                    % len(names) if names else "no header, and no map fits")))
+                continue
+            row = dict(zip(positional, cells))
+        missing = [c for c in REVIEW_CORE if c not in row]
+        if missing:
+            unparsed.append((n, "no %s column" % "/".join(missing)))
+            continue
+        if not re.match(r"^\d{4}-\d{2}-\d{2}$", row["date"]):
+            unparsed.append((n, "date cell %r is not a date" % row["date"][:24]))
+            continue
+        rows.append(row)
+    return rows, unparsed
+
+
+def review_findings(value):
+    """The count in a `findings_real` cell, or None when it states no number.
+
+    None is NOT zero. `all` and `VOID -- instrument error` appear in real logs,
+    and counting them as zero findings silently deflates the one ratio this
+    report exists to state. Anchored at the START of the cell so a prose cell
+    like `R1 4 BLOCK + 8 WARN` does not yield a confident 4."""
+    m = re.match(r"^(\d+)\b", (value or "").strip())
+    return int(m.group(1)) if m else None
+
+
+def _is_fail(verdict):
+    """FAIL as a WORD, so `PASS (no failures)` is not counted as a failure."""
+    return re.search(r"\bFAIL\b", (verdict or "").upper()) is not None
+
+
+def _is_pass(verdict):
+    return re.search(r"\bPASS\b", (verdict or "").upper()) is not None
+
+
+def _print_read_cost():
+    """The cost side, printed with the benefit and NEVER without it: a catch
+    rate with no cost term justifies unbounded doctrine, and a cost term with
+    no catch rate justifies deleting the process. When it cannot be measured
+    the line still prints, saying so -- silence here IS the catch rate quoted
+    alone, which is the thing this report exists to prevent."""
+    skill_dir = Path(__file__).resolve().parent.parent
+    contract = skill_dir / "SKILL.md"
+    print()
+    if not contract.is_file():
+        print("Read cost: unavailable -- SKILL.md not found beside this "
+              "validator (%s)" % skill_dir)
+        return
+    files = [p for p in sorted(skill_dir.glob("*.md")) if p.name != "SKILL.md"]
+    support = sum(p.stat().st_size for p in files)
+    head = contract.stat().st_size
+    # The TOTAL, and the files itemised. Printing only the two terms lets the
+    # one that fell be quoted while the one that grew stays lumped -- which is
+    # exactly how a -7.8% headline coexisted with a read surface that grew.
+    print("Read cost of %s: SKILL.md %d bytes (every session) + %d bytes "
+          "across %d support files (read on trigger) = %d bytes total"
+          % (skill_dir.name, head, support, len(files), head + support))
+    for p in files:
+        print("    %-24s %8d" % (p.name, p.stat().st_size))
+
+
+def cmd_benefit(root):
+    """Report what the process caught, beside what it costs to read.
+
+    ALWAYS exits 0 and emits no warning or advisory. This number is the
+    criterion future units are judged by; a measurement that can fail a build
+    becomes a target, and a targeted measurement stops measuring."""
+    log = root / review_log_rel()
+    print("=== benefit: what the process caught, and what it costs to read ===")
+    if not log.is_file():
+        print("[info] no %s yet: nothing to report. The number appears once "
+              "reviews are logged." % review_log_rel())
+        _print_read_cost()
+        return 0
+    rows, unparsed = parse_review_log(read_text(log))
+    # `tier` carries the MOMENT in Standalone (design / closure) and the
+    # reviewer WEIGHT in Hybrid (deep / light / code / guide / vision). A
+    # Hybrid row is a real review whose moment this column does not state, so
+    # it is counted and named, never folded into a moment by guesswork.
+    moments = {"design": [], "closure": []}
+    unstated = {}
+    unstated_found = unstated_code = unstated_uncounted = 0
+    for r in rows:
+        tier = r["tier"].lower()
+        if tier.startswith("design"):
+            moments["design"].append(r)
+        elif tier.startswith("closure"):
+            moments["closure"].append(r)
+        else:
+            unstated[tier] = unstated.get(tier, 0) + 1
+            n = review_findings(r["findings_real"])
+            if n is None:
+                unstated_uncounted += 1
+            else:
+                unstated_found += n
+                if tier.startswith("code"):
+                    unstated_code += n
+    classified = moments["design"] + moments["closure"]
+    print("rows parsed: %d   rows unparsed: %d%s"
+          % (len(rows), len(unparsed),
+             ("  -> " + "; ".join("line %d: %s" % u for u in unparsed[:5]))
+             if unparsed else ""))
+    print("reviews with a stated moment: %d   moment not stated by `tier`: %d%s"
+          % (len(classified), sum(unstated.values()),
+             ("  (" + ", ".join("%s x%d" % (t, n) for t, n
+                                in sorted(unstated.items())) + ")")
+             if unstated else ""))
+    if not classified:
+        _print_read_cost()
+        return 0
+    dates = sorted(r["date"] for r in classified)
+    print("span of the reviews counted below: %s -> %s" % (dates[0], dates[-1]))
+
+    print()
+    print("%-9s %6s %10s %11s %10s" % ("moment", "rows", "findings",
+                                       "FAIL verdict", "per review"))
+    totals, uncounted = {}, 0
+    for m in ("design", "closure"):
+        rs = moments[m]
+        counts = [review_findings(r["findings_real"]) for r in rs]
+        uncounted += sum(1 for c in counts if c is None)
+        found = sum(c for c in counts if c is not None)
+        failed = sum(1 for r in rs if _is_fail(r["verdict"]))
+        totals[m] = found
+        print("%-9s %6d %10d %11d %10.1f"
+              % (m, len(rs), found, failed, (found / len(rs)) if rs else 0.0))
+    total = sum(totals.values())
+    if uncounted:
+        print("findings cells stating no number: %d (counted as unknown, "
+              "never as zero)" % uncounted)
+    if total:
+        print()
+        print("Caught BEFORE the code existed: %d / %d findings = %.0f%%"
+              % (totals["design"], total, 100.0 * totals["design"] / total))
+        # The residue, stated as a BOUND rather than as a direction. The
+        # sentence this replaces claimed the share was "a floor, not a
+        # ceiling" because `code` rows are post-implementation -- which is
+        # backwards, since folding them LOWERS the design share. But the fact
+        # was right and only the direction wrong, so `code` findings sit on
+        # the closure side of the upper bound instead of being discarded with
+        # it. No direction is printed at all: the unstated set pushes both
+        # ways, and only an interval is true of all of it.
+        if unstated_found:
+            denom = total + unstated_found
+            print("Bounded by the %d findings in rows whose moment `tier` "
+                  "does not state: %.0f%%-%.0f%% (`code` rows are "
+                  "post-implementation by definition, so their findings sit "
+                  "on the closure side of the upper bound)"
+                  % (unstated_found, 100.0 * totals["design"] / denom,
+                     100.0 * (totals["design"] + unstated_found - unstated_code)
+                     / denom))
+        if unstated_uncounted:
+            print("%d unstated rows state no findings count (`all`, `VOID`): "
+                  "neither zero nor countable, so they lie outside both "
+                  "bounds" % unstated_uncounted)
+    failed_all = sum(1 for r in classified if _is_fail(r["verdict"]))
+    inconclusive = sum(1 for r in classified if not _is_fail(r["verdict"])
+                       and not _is_pass(r["verdict"]))
+    print("Reviews whose verdict contains FAIL: %d / %d = %.0f%%%s"
+          % (failed_all, len(classified), 100.0 * failed_all / len(classified),
+             ("   (+%d inconclusive)" % inconclusive) if inconclusive else ""))
+    print("(both figures are over the %d reviews whose moment `tier` states)"
+          % len(classified))
+    _print_read_cost()
+    return 0
+
+
 def cmd_orient(args):
     """SessionStart hook: emit a bounded, repo-sourced ai_docs/ orientation to
     stdout and ALWAYS return 0 (fail-open, P-TM T8) -- a session hook must never
@@ -2229,6 +2499,12 @@ def cmd_migrate(root, args):
 # --------------------------------------------------------------------- main
 
 def main(argv=None):
+    # `remind` is intercepted BEFORE argparse (kb's F-041 rule, kept): it is a
+    # hook surface fired on every prompt, so a stray flag must cost a usage
+    # message and a non-zero exit on a turn, not the turn itself.
+    if (argv if argv is not None else sys.argv[1:])[:1] == ["remind"]:
+        return cmd_remind(None)
+
     common = argparse.ArgumentParser(add_help=False)
     common.add_argument("--root", help="project root (default: walk up until a docs root is found)")
     common.add_argument("--docs-dir", dest="docs_dir",
@@ -2270,9 +2546,18 @@ def main(argv=None):
     gp.add_argument("--file", help="file path to evaluate (alternative to --hook)")
     gp.add_argument("--protected", default="", help="protected prefixes separated by ';' (e.g. \"src/auth;src/crypto\")")
 
+    sub.add_parser("benefit", parents=[common],
+                   help="report what the review gates caught (and what the "
+                        "doctrine costs to read) -- a report, never a gate: "
+                        "always exits 0")
+
     sub.add_parser("orient", parents=[common, hybrid_opt],
                    help="SessionStart hook: emit docs-root orientation to stdout (fail-open, zero-execution)")
 
+    sub.add_parser("remind", parents=[common],
+                   help="UserPromptSubmit hook: print the constant per-turn line "
+                        "(fail-open, zero-read, zero-execution)")
+
     pp = sub.add_parser("plan", parents=[common],
                         help="Subagent Execution: validate/brief a PLAN_[feature].md (zero-execution)")
     pp_sub = pp.add_subparsers(dest="plan_cmd", required=True)
@@ -2296,7 +2581,7 @@ def main(argv=None):
             # nothing is being guessed. Refusing here would make the guard block the
             # one command that ends the ambiguity.
             discovered, name = None, args.from_dir
-        elif args.cmd == "orient":
+        elif args.cmd in ("orient", "remind"):
             # The SessionStart hook is fail-open by contract: it must never block a
             # session, not even on a half-migrated tree. It orients on the default
             # and says so rather than exiting non-zero.
@@ -2311,6 +2596,8 @@ def main(argv=None):
         return cmd_gate(args)
     if args.cmd == "orient":
         return cmd_orient(args)
+    if args.cmd == "remind":
+        return cmd_remind(args)
 
     root = Path(args.root).resolve() if args.root else (discovered or find_project_root())
     if args.cmd == "check":
@@ -2323,6 +2610,8 @@ def main(argv=None):
         return cmd_stale(root, hybrid=args.hybrid)
     if args.cmd == "mark":
         return cmd_mark(root, args.paths)
+    if args.cmd == "benefit":
+        return cmd_benefit(root)
     if args.cmd == "migrate":
         return cmd_migrate(root, args)
     if args.cmd == "plan":

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

@@ -496,16 +496,18 @@ Date: 2026-06-11 (UTC)
 
 One row per completed review (`review.md` §When a review is due). Append-only; it
 is the record that the gate ran and what it was worth. **One schema for both
-modes** — a Hybrid project's devPNT gates write to this same file, so Standalone
-adds values to the existing columns rather than a second table.
+modes** — one required CORE (`date`, `doc_key`, `tier`, `model`, `findings_raised`,
+`findings_real`, `verdict`, `revise_rounds`) plus each mode's own realization
+columns: Standalone adds `reviewer`, a Hybrid devPNT row adds `instrument` and
+`notes` and carries no `reviewer` at all. Both modes write this same file.
 
 ```markdown
 # Independent Review Log
 
-| date | doc_key | tier | reviewer | findings_raised | findings_real | verdict | revise_rounds |
-|---|---|---|---|---|---|---|---|
-| 2026-06-11 | ANALYSIS_login_sso.md | design | subagent (opus, fresh ctx) | 4 | 3 | FAIL → PASS | 2 |
-| 2026-06-12 | diff feature/sso-login | closure | self-pass (declared; absent) | 2 | 2 | PASS with findings → corrections re-reviewed, PASS | 2 |
+| date | doc_key | tier | model | reviewer | findings_raised | findings_real | verdict | revise_rounds |
+|---|---|---|---|---|---|---|---|---|
+| 2026-06-11 | ANALYSIS_login_sso.md | design | deep | subagent (fresh ctx) | 4 | 3 | FAIL → PASS | 2 |
+| 2026-06-12 | diff feature/sso-login | closure | deep | self-pass (declared; absent) | 2 | 2 | PASS with findings → corrections re-reviewed, PASS | 2 |
 
 ## Notes
 <!-- One short paragraph per review that found something worth remembering: what
@@ -517,9 +519,14 @@ adds values to the existing columns rather than a second table.
 
 `tier` is the moment plus, in Hybrid, the reviewer weight: `design`, `design (late)`
 and `closure` (Standalone); `deep`, `light`, `code`, `guide`, `vision` (devPNT gates
-and the Vision blind check). The validator reads this column by its header name, so
+and the Vision blind check). `model` is a different question about the same review: `tier` says WHICH GATE ran,
+`model` says WHAT CAPABILITY ran it (`deep`, `light`, `economy`,
+`single (client exposes no choice)`, `below floor: <reason>` — the floor and its
+arbitration are `review.md` §The capability floor). The two columns share the words
+`deep`/`light` and mean different things by them, which is why they are read by
+header and never by position. The validator reads this column by its header name, so
 extra or reordered columns are fine — but the header must say `tier`. `reviewer`
-records the realization actually used — fresh subagent, one-shot client run, or a
+also carries the AUTHORING session's own below-floor disclosure where one is owed (the log has no column for the authoring tier, so `review.md` §The capability floor routes it here; Hybrid rows use `notes`). Otherwise it records the realization actually used — fresh subagent, one-shot client run, or a
 **declared** self-pass — and, for any rung below rung 1, WHY the rung(s) above did
 not run, in the ladder's reason words (`review.md`): `absent` — the client has no
 such facility (a claim about the client, never about a policy); `gated, declined` —