@antoneeo/kb-agentic-skill 1.14.0 → 1.15.0

package/skills/kb-agentic-skill/dispatch.md

@@ -45,12 +45,50 @@ below — so it needs no separate dispatch hook.)
 
 ## Model tiers (client-relative, no provider names)
 
-- Default dispatch: **economy** implementer tier.
+- Default dispatch: **economy** implementer tier. This is legal precisely
+  because a dispatched task carries `task.verify` — the threshold signal that
+  makes a wrong cheap answer visible. **The floor that governs every role, and
+  the rule that a tier may be lowered only where such a signal exists, is
+  `review.md` §The capability floor** — cited, never restated here.
 - After **two** consecutive `verify_result: fail` on the same task: escalate
   to the **deep** tier for the retry (ADR 2026-07-02). Do not escalate on the
   first failure — a single fail is often a brief or environment issue, not a
   capability gap.
 
+## What may be delegated at all
+
+The sections above govern the opt-in PLAN loop; **this one is family-wide** and
+applies to any pass, at any level, dispatch or no dispatch. Delegation is not a
+token-saving technique — a second context re-reads, re-briefs and reports back,
+so the total spend goes UP. What it buys is a main context that stays clean, and
+independence where independence is the point. Judge a pass on two axes:
+
+| | output falsifiable cheaply (`file:line`, an assertion result, a diff) | output is judgement |
+|---|---|---|
+| **reads ≫ report** | **delegate** — the whole win lives here | **never**: the biggest apparent win is where plausible-but-wrong enters |
+| **reads ≈ report** | keep it: the brief costs more than the pass | keep it |
+
+- **Delegate**: locating and verifying (a pass that returns citable facts and
+  discards its exploration trace), executing a probe or battery and reporting
+  the assertion table, and every independent review — the last for correctness,
+  not economy, and it is mandatory regardless of what it costs.
+- **Never delegate**: authoring a governed artifact (Vision, ANALYSIS/E-ISP,
+  threat model, use cases, the Interface Contract), the triage level and router
+  verdict, a reconciliation or scope decision, and any pass whose result the
+  orchestrator must hold across many later turns — delegating that one just
+  moves the reading into the main context via the report.
+- **The delegability condition**: a task whose brief cannot be expressed as
+  **pointers** — paths, ids, a command — is **not delegable** yet; a brief that
+  must carry the content pays those tokens twice, once to write it and once to
+  read it. `plan brief` is this rule already realized for the PLAN loop (it
+  prints `guides` as paths, never pasted content); the condition generalizes it.
+
+**Declared residual**, so the silence is not read as prohibition: this section
+settles the CLASSIFICATION. *When* to reach for a delegated search or
+orientation pass — the trigger, its brief format and its output contract — is a
+separate unit and is not answered here; until it lands, reaching for one is the
+orchestrator's judgement against the table above, not a rule.
+
 ## Review slots — one-shot, not iterative
 
 Exactly three review touches per task, never a loop:

package/skills/kb-agentic-skill/distillation.md

@@ -96,11 +96,19 @@ Claims live in the owning topic's `## Claims` table (`templates.md` has the temp
   makes the same assertion mint the same id in another project, which is what makes
   `portability.md`'s de-duplication mechanical instead of a judgement call. The price is
   that **one span cannot carry two different assertions at the same qty** — the id
-  cannot tell them apart, and the validator refuses the pair. The fix is to widen one
-  locator to the span that actually carries its assertion, or to merge the two rows.
-  It is **not** to edit the qty or nudge the locator until the hash differs: that
-  distorts the evidence to satisfy a hash function, which is the one repair this
-  ledger exists to prevent.
+  cannot tell them apart, and the validator refuses the pair. That refusal is a
+  symptom of a non-atomic row (§3): the fix is to **narrow each locator to the
+  sub-span that carries its own assertion** — narrow spans make atomic rows
+  id-distinct by construction. Merge ONLY when the two rows state the same single
+  assertion twice; merging distinct assertions manufactures a bundled row (§3),
+  trading the mechanical error for a semantic one no check can see. Narrowing is
+  not nudging: a narrowed locator still addresses exactly the words that support
+  its assertion, and the validator still opens the span. What stays forbidden is
+  editing the qty, or moving a locator onto bytes that do NOT carry the assertion,
+  until the hash differs — that distorts the evidence to satisfy a hash function,
+  which is the one repair this ledger exists to prevent. A locator edit mints a
+  NEW id; citers of the old one are reached by the cascade (`reconciliation.md`
+  §Splitting a bundled row).
 - **valid** — `-`, `from X`, `until X`, `from X until Y`, `if <condition>`. Half-open:
   `until 2026-03-01` and `from 2026-03-01` do NOT overlap. A time-bounded fact is not a
   conflict with its successor — write the scope, or reconciliation will manufacture one.
@@ -117,8 +125,8 @@ Claims live in the owning topic's `## Claims` table (`templates.md` has the temp
   the file and checks.
 - **prov** — `GIVEN | ELICITED | DERIVED | RULING | IMPORTED`. `IMPORTED` is a ruling that came from another project (`portability.md`): it keeps its text and original `basis:`, its note must say `imported_from:`, and it may not supersede a local row until you re-ratify it. Information for whoever resolves a
   conflict; never a rank.
-- **state** — `OK`, `CONTESTED <ids>`, `SUPERSEDED <id>` (`reconciliation.md` owns the
-  transitions).
+- **state** — `OK`, `CONTESTED <id>[,..]`, `SUPERSEDED <id>[,..]` (`reconciliation.md`
+  owns the transitions; a split bundle names ALL its successors).
 
 ## 3. Extraction discipline
 
@@ -127,6 +135,29 @@ the offset span it came from. The extractor **invents nothing**: no labels, no
 summaries-as-claims, no filling of gaps from model knowledge. What the source does not
 assert does not become a row — it may become a `gaps:` entry on the topic.
 
+**One row asserts one thing — the span is not the unit.** The extraction unit is a
+source span; the unit of use is one assertion, and they are not the same size: a row
+can be atomic as provenance and plural as meaning. The common source of plurality is
+the **reviewer-comment shape** — one comment under one feature heading asserting
+several facts about several subjects (a capability at the door, another actor's
+console, a verification flow). Extracted as one span it becomes one legal row, and
+every downstream citation of it is faithful to the text while asserting what the
+source did not: the off-topic part is read as applying to the citing context
+(borrowed capability), another actor's surface counts as this actor's (wrong actor),
+an ambiguous subject silently switches referent — and the writer who avoids all
+three by quoting only the on-topic part has lost an assertion instead. Both halves
+of the north star, violated by one bundled row. So **emit one row per assertion even
+when the source packs several into one sentence**, and **cite the narrowest span
+that supports the assertion, not the paragraph that contains it** — narrow spans are
+also what make atomic rows id-distinct (§2). Sub-line precision needs no
+re-extraction on a stored `.txt`: a form-feed-free file is one page, so
+`p=1@<a>-<b>` addresses character offsets below the line; re-extraction is needed
+only for a source with no character-addressable stored form. A bundled row already
+in the ledger is repaired by splitting (`reconciliation.md` §Splitting a bundled
+row), never edited in place. The validator can only hint here — a `[note]` on
+suspicious claim text, heuristic and fallible, never an error: atomicity is
+meaning, and meaning is verified at the ingestion review.
+
 **Exhaust the source; never sample it.** *Invents nothing* is a floor, and a floor is not
 a target: an extractor that stops the moment nothing it wrote is false stops on page
 twenty of a two-hundred-page manual, with every row it emitted correct. A source is

package/skills/kb-agentic-skill/reconciliation.md

@@ -69,6 +69,28 @@ premise: signed amendments arrive later.
 | newer source vs a ruling | new set {new row, ruling row}; escalation shows the `basis:` |
 | member refined | the refining row inherits the member's contested relations (re-judged); counterparts rewritten to the new id |
 | corroboration of a contested member | source appended; the set untouched — more evidence is not new information, and the escalation form shows source counts |
+| bundled row split (`distillation.md` §3) | N atomic rows `OK`, each on its narrowed span; the bundle → `SUPERSEDED <id1>[, <id2> ..]`, text intact; contested relations re-judged per successor |
+
+## 3-bis. Splitting a bundled row
+
+A row carrying more than one assertion (`distillation.md` §3 — atomic as provenance,
+plural as meaning) is repaired by supersession, never in place:
+
+1. Write one atomic row per assertion, each citing the **narrowed span** that carries
+   it (`p=1@<a>-<b>` reaches below a line on a stored `.txt`). Narrow spans mint
+   distinct ids by construction.
+2. The bundled row becomes `SUPERSEDED <id1>, <id2>, ...` — every successor named,
+   its text intact, exactly as refinement keeps superseded text.
+3. Contested relations of the bundle are **re-judged per successor**: a counterpart
+   usually contests ONE of the assertions, not all of them.
+4. The cascade runs (§2, *the cascade runs*): every living document citing the fallen
+   id joins the revision worklist, and each citer is revised to the successor in ITS
+   scope — the moment a borrowed-capability citation dies.
+
+This is not new information arriving (§2): the source said N things all along; the
+ledger only now says them one at a time. No ruling and no `basis:` is needed — the
+split is a repair of our own extraction, and it travels with its own diary/commit
+record like any claim-table edit.
 
 ## 4. Escalation — batched, and in the legal form only
 

package/skills/kb-agentic-skill/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/kb-agentic-skill/scripts/sdlc_check.py

@@ -187,6 +187,13 @@ def kb_claim_id(source_path, locator, qty_key=""):
     return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:12]
 
 
+# F-047: bundling tells for the atomicity note in kb_check_claims. Literal
+# substrings, deliberately few and conservative: the note is a hint, and a
+# noisy hint trains readers to skip notes. Field-calibrated on the motivating
+# reviewer-comment shape ("states X, that Y, and that Z").
+KB_BUNDLE_HINTS = (", and that ", "; ", ", while ", " and also ")
+
+
 def kb_unquote(value):
     """Strip ONE pair of wrapping YAML quotes (then re-strip whitespace).
     load_frontmatter keeps values verbatim by design; paths with spaces force
@@ -498,6 +505,20 @@ def kb_check_claims(root):
                 if not m:
                     errors.append("%s: about must be '<predicate> -> <slug>' or '-'"
                                   % where)
+            # --- atomicity hint (F-047): a row atomic as provenance can be
+            # plural as meaning. Text cannot PROVE plurality, so this is a
+            # note — never a warning or an error, never the exit code.
+            hints = [h for h in KB_BUNDLE_HINTS if h in row["claim"]]
+            if hints:
+                notes.append("%s: claim text of %s reads like more than one "
+                             "assertion (matched %s) — one row asserts one "
+                             "thing; if it is a bundle, split it "
+                             "(distillation.md section 3, reconciliation.md "
+                             "section 'Splitting a bundled row'). Heuristic "
+                             "only: a genuinely "
+                             "single assertion needs no change"
+                             % (where, row["id"] or "(id pending)",
+                                ", ".join(repr(h) for h in hints)))
             # --- id: recompute, or note fill-pending ---
             if not row["id"]:
                 notes.append("%s: id missing — fill-pending, run "
@@ -534,14 +555,22 @@ def kb_check_claims(root):
                                       "is global across topics/" % (where, row["id"],
                                                                     all_ids[row["id"]]))
                     elif same_span:
+                        # F-047: recommending a merge here was a trap — merging
+                        # distinct assertions manufactures a bundled row, trading
+                        # this mechanical error for a semantic one no check sees.
                         errors.append(
                             "%s: id %s collides with the row at %s — two "
                             "DIFFERENT rows cite the same span with the same "
                             "qty, and the id function cannot separate them (it "
                             "hashes path#locator#qty and excludes the text on "
-                            "purpose). Widen one locator to the span that "
-                            "actually carries its assertion, or merge the two "
-                            "rows — do not edit the qty to break the tie"
+                            "purpose). Narrow each locator to the sub-span that "
+                            "carries its own assertion — narrow spans make "
+                            "atomic rows id-distinct (on a stored .txt, "
+                            "p=<page>@<a>-<b> reaches below a line). Merge ONLY "
+                            "if the two rows state the same single assertion; "
+                            "merging distinct assertions trades this mechanical "
+                            "error for a semantic one no check can see — do not "
+                            "edit the qty to break the tie"
                             % (where, row["id"], all_ids[row["id"]]))
                     else:
                         # Same id, different text AND different span: the id
@@ -570,7 +599,7 @@ def kb_check_claims(root):
             m = re.match(r"^(CONTESTED|SUPERSEDED) ([0-9a-f, ]+)$", state)
             if not m:
                 errors.append("%s: state must be OK, 'CONTESTED <id>[,..]' or "
-                              "'SUPERSEDED <id>': %r" % (where, state))
+                              "'SUPERSEDED <id>[,..]': %r" % (where, state))
                 continue
             kind = m.group(1)
             targets = [t.strip() for t in m.group(2).split(",") if t.strip()]

package/skills/kb-agentic-skill/scripts/sdlc_core.py

@@ -1320,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):
@@ -2052,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
@@ -2315,6 +2546,11 @@ 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)")
 
@@ -2374,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/kb-agentic-skill/templates.md

@@ -439,16 +439,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
@@ -460,9 +462,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` —
@@ -631,7 +638,8 @@ status: CURRENT
 - `qty`: `<value> <unit> <kind>` — effort in person-days (h/d/w/mo/fte-mo; 8h=1d, 1w=5d,
   1mo=21d), duration in calendar days (h/d/w/mo), cost within one currency, count unit-matched.
 - `about`: `<predicate> -> <slug>` for relationship claims; stored once, under the subject.
-- `state`: `OK` | `CONTESTED <id>[,..]` | `SUPERSEDED <id>` — per claim, never per node.
+- `state`: `OK` | `CONTESTED <id>[,..]` | `SUPERSEDED <id>[,..]` — per claim, never per
+  node; a split bundle (`reconciliation.md` §Splitting) names all its successors.
 - A tombstone (merged/renamed topic): `status: SUPERSEDED` + `redirect_to: <slug>`, body empty.
 
 ## ai_docs/corpus/given/[name].meta.md (source sidecar)