@antoneeo/kb-agentic-skill 1.13.0 → 1.15.0

package/skills/kb-agentic-skill/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/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)