@antoneeo/kb-agentic-skill 1.13.0 → 1.14.0

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 Every significant change to this skill is recorded here.
 
+## [1.14.0] - 2026-09-06
+
+### Added
+- **F-046: the protocol reaches every turn (`remind`, UserPromptSubmit, wired by
+  default).** `orient` fires once at session start and decays; a session that
+  never loads the skill never had the protocol at all. Measured 2026-09-06: a
+  release ran against a `GUIDE_release.md` the session never consulted, because
+  `SKILL.md` -- where the duty is written -- had not been read. `remind` prints
+  ONE constant line at every prompt, and its first duty is that one: decide
+  whether the skill governs the work in front of you and, if it does, LOAD it
+  once. The carrier is kb's F-041 item B, LIFTED into the shared spine rather
+  than duplicated, so all three lenses share one machine; each lens declares its
+  own line in `set_profile(remind_line=...)`. Installing the package wires it
+  machine-wide on Claude Code alongside the orientation hook, never instead of
+  it; removing the hook entry is a standing opt-out. Per-turn cost disclosed and
+  accepted by the owner (`vision/rulings.md` r19, the "no ceremony ratchet"
+  Non-Goal's second door), and bounded to stay flat by a contract the new shared
+  `scripts/test_remind.py` guards: constant text, zero reads, one line under 500
+  characters, argv ignored whole, always exit 0.
+
+### Changed
+- **`guides.md` said something false about code guides.** It claimed `stale`
+  works unchanged for `source_kind: code` because "the code-excerpt snapshot
+  drifts when the code changes". A snapshot is a frozen copy and never drifts:
+  freshness is NOT mechanized there, and the duty is the author's twice -- when
+  you MODIFY code a comprehension guide describes, and when you merely READ one
+  before trusting it. Measured 2026-09-06: the guided module had gained 388
+  lines and lost 71 across four commits with `stale` silent.
+
 ## [1.13.0] - 2026-09-05
 
 Spine-only release: `review.md` updated byte-identical across the family

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "kb-agentic-skill",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Knowledge-Base & Document-First protocol with risk triage, Vision governance, signal distillation and optional devPNT integration.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antoneeo/kb-agentic-skill",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Knowledge-Base & Document-First protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, signal distillation and optional devPNT integration.",
   "keywords": [
     "claude-code",

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

@@ -202,20 +202,28 @@ Gemini CLI — wire the same command into its startup-hook mechanism if present;
 - **Hybrid/devPNT projects**: add `--hybrid` — the hook then appends a one-line pointer to run `devpnt_mcp_get_bootstrap` for the Master Plan / Knowledge Layer and does not replicate them; the filesystem orientation (router + handoff + README) still emits.
 - Like the CI gate (§2), if you copied `sdlc_check.py` into the repo, the hook references that copy — keep it current when you update the skill.
 
-### Per-turn reminder: `remind` (UserPromptSubmit -- opt-in, NEVER a default)
-
-`orient` fires once, at session start; a long session drifts after it (a compaction,
-ten turns of other work -- the F-041 field report). `sdlc_check.py remind` prints ONE
-constant line -- the kb minimum: the triage levels, the topic-index recall trigger, the
-capture moment, the revision gesture -- for the client to inject at every prompt.
-Cost: 443 characters, ~75 tokens per prompt, which is exactly why `init` never wires it and never will by default: the
-per-turn cost is the project's choice. The line is constant and zero-read, so nothing
-repo-controlled can ride into the agent's context through it, and the vision's
-no-per-turn-graph-queries non-goal stays honored -- the line re-arms the
-entry-into-topic trigger; it never runs the reading itself.
-
-Claude Code -- in the project's `.claude/settings.json` (or `settings.local.json` when
-the validator path is machine-specific, same rule as the orientation hook above):
+### Per-turn reminder: `remind` (UserPromptSubmit -- wired by default)
+
+`orient` fires once, at session start; a long session drifts after it, and a session
+that never loads the skill never had the protocol at all. Measured (F-046, 2026-09-06):
+a release ran against a `GUIDE_release.md` the session never consulted, because
+`SKILL.md` -- where the duty is written -- had not been read. `sdlc_check.py remind` prints
+ONE constant line at every prompt, and its first duty is that one: decide whether the
+skill governs the work in front of you and, if it does, load it once.
+
+Cost: 443 characters, ~75 tokens per prompt, paid on every turn including
+trivial ones. That is admissible only because the owner accepted it explicitly
+(`ai_docs/vision/rulings.md` r19, the "no ceremony ratchet" Non-Goal's second door) --
+and the acceptance was for a FLAT cost. Hence the contract, guarded by
+`scripts/test_remind.py`: the line is **constant and reads nothing** (so nothing repo-
+or session-controlled rides into the agent's context through it, and the cost cannot
+grow with the session), it is **one line under 500 characters**, and it **can never
+break a prompt** (argv ignored whole, always exit 0). A trivial turn pays a yes/no
+judgement, never a load.
+
+Installing the package wires it machine-wide on Claude Code, alongside the orientation
+hook and never instead of it; **removing that hook entry is a standing opt-out.** To
+wire it by hand:
 
 ```json
 {
@@ -225,7 +233,7 @@ the validator path is machine-specific, same rule as the orientation hook above)
         "hooks": [
           {
             "type": "command",
-            "command": "python \"C:\\Users\\<user>\\.claude\\skills\\kb-agentic\\scripts\\sdlc_check.py\" remind"
+            "command": "python \"C:\Users\<user>\.claude\skills\kb-agentic\scripts\sdlc_check.py\" remind"
           }
         ]
       }

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

@@ -1,6 +1,6 @@
 ---
 name: kb-agentic
-version: 1.13.0
+version: 1.14.0
 description: Knowledge-Base & Document-First protocol with risk-proportional triage, Vision as a guide, Signal Distillation, a complete Standalone mode and optional symbiosis with devPNT. Use for user documentation, knowledge extraction, SOPs, research notes, decision logs, knowledge management — and for answering project questions from the claim ledger and topic graph.
 author: Antonio Pinto (https://github.com/Antoneeo)
 copyright: (c) 2026 Antonio Pinto

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

@@ -80,6 +80,19 @@ sdlc_core.set_profile(
         # sdlc_core.py in three distributions to buy nothing.
         "taxonomy_pass", "subagent_dispatch", "question_discipline",
     ),
+    # F-046: the per-turn line moved from this file's own `remind` command into
+    # the shared spine, which now carries the machine for all three lenses. The
+    # kb duties below are unchanged; what is new is the first one -- an unread
+    # protocol cannot be applied, and until now nothing said so.
+    remind_line=(
+        "first decide if this skill governs the work; if yes, LOAD it once -- an "
+        "unread protocol cannot be applied. Triage: L1 quick fact, L2 propagation, "
+        "L3 new knowledge unit, Spike; declare the level. On this project's "
+        "domain, read topics/INDEX.md first and cite claim ids, or state no "
+        "coverage. Decisions today get recorded in the KB at close. Revising a "
+        "document? Re-read it whole and rewrite to current state -- never append "
+        "a delta."
+    ),
     design_gate_between=("### 3. Request Analysis & Taxonomy Pass",
                          "### 4. Knowledge Processing & Distillation"),
 )
@@ -1884,26 +1897,6 @@ def kb_cmd_orient(argv):
     return rc
 
 
-def kb_cmd_remind(_argv):
-    """F-041 item B: the per-turn one-line reminder (UserPromptSubmit, opt-in).
-
-    A CONSTANT, zero-read line -- the kb minimum an agent needs re-armed every
-    prompt: triage, the recall trigger, the capture moment, the revision gesture. Constant by
-    contract: nothing repo-controlled may ride a line injected into the agent's
-    context every turn, and zero reads is what keeps the per-turn cost flat.
-    The vision's non-goal bans per-turn GRAPH queries; this line only re-arms
-    the entry-into-topic criterion, it never runs the descent. Never wired by
-    init and never a default: ENFORCEMENT par.4 documents the manual snippet
-    and the ~50 tokens/prompt cost -- the project chooses. Fail-open like every
-    hook surface: argv is ignored whole, the exit code is always 0."""
-    print("kb-agentic: triage before acting -- L1 quick fact, L2 propagation of "
-          "settled knowledge, L3 new knowledge unit, Spike exploration; declare "
-          "the level. Answering about this project's domain? Read topics/INDEX.md "
-          "under the docs root first and cite claim ids, or state no coverage. "
-          "Decisions made today get recorded in the KB at session close. Revising an existing document? Re-read it whole and rewrite it to current state -- never append a delta.")
-    return 0
-
-
 def kb_cmd_help():
     """The spine's usage, then the overlay's own commands.
 
@@ -1946,10 +1939,6 @@ def main(argv=None):
     # spine runs it on the raw argv, the overlay only appends the topic router.
     if argv and argv[0] == "orient":
         return kb_cmd_orient(argv)
-    # `remind` too: it is a hook surface (UserPromptSubmit), so a stray flag
-    # must print the line, not an argparse usage error into someone's prompt.
-    if argv and argv[0] == "remind":
-        return kb_cmd_remind(argv)
     # Forward-by-default: anything not intercepted goes to the spine untouched.
     # Never a hand-copied command tuple - that is how a spine command gets
     # silently dropped (mkt_check.py ships that exact defect with `migrate`).

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():
@@ -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:
@@ -2229,6 +2268,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",
@@ -2273,6 +2318,10 @@ def main(argv=None):
     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 +2345,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 +2360,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":