@antoneeo/kb-agentic-skill 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 Every significant change to this skill is recorded here.
 
+## [1.8.0] - 2026-08-28
+
+F-041 -- the mid-session drift field report, both items.
+
+### Added
+- **`check` notes an unwired or dead session-orientation hook.** `init` wires the
+  hook at init time only; pre-F-036 and agent-bootstrapped projects never got it,
+  silently. `check` now prints, right after its summary line, a one-line `[note]` when no hook is detectable
+  in `.claude/settings.json` / `.claude/settings.local.json` / `.codex/hooks.json`,
+  and a distinct note when a hook is wired but its validator does not resolve
+  (any-resolves aggregation across entries; BOM-tolerant reads; fail-open on
+  malformed config). Informational only: never the exit code, never a `validate`
+  warning -- CI stays green because the wired hook legitimately lives in the
+  git-ignored local settings file.
+- **`remind` -- an opt-in per-turn one-line reminder (UserPromptSubmit).** orient
+  fires once; mid-session drift had no mechanical guard. One constant, zero-read
+  line re-arms the kb minimum (triage levels, the topics/INDEX.md recall trigger,
+  the capture moment) at every prompt. Never wired by `init`, never a default:
+  ENFORCEMENT par.4 documents the snippet and the ~50 tokens/prompt cost.
+
 ## [1.7.0] - 2026-08-28
 
 F-040 — the capture moment (second-brain unit 2): the day's decisions reach the

package/README.md

@@ -82,7 +82,11 @@ it: a repo that vendors it gets a repo-relative command in the shared `.claude/s
 (portable — commit it); otherwise the path is machine-specific and goes to the git-ignored
 `.claude/settings.local.json`, and each teammate runs `init` once. Re-running `init` never
 duplicates the hook, and a hook whose validator no longer resolves is reported as **broken**
-with the correction rather than counted as installed.
+with the correction rather than counted as installed. Since F-041, `check` also
+prints a one-line note when a project has no orientation hook wired (or a dead
+one), and an opt-in per-turn reminder exists for long sessions: `sdlc_check.py
+remind`, one constant line via UserPromptSubmit -- documented in `ENFORCEMENT.md`
+par.4, never wired by default.
 
 ## The family: three lenses, one spine
 

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "kb-agentic-skill",
-  "version": "1.7.0",
+  "version": "1.8.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.7.0",
+  "version": "1.8.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

@@ -86,6 +86,20 @@ that cannot be placed in a command safely, or a settings file it cannot write. `
 prints which case applied, per client — a silent skip is what let "documented default
 that nobody installs" survive in the first place.
 
+**Older and agent-bootstrapped projects are silently unwired -- `check` now tells you (F-041).**
+`init` wires the hook at init time only: a project initialized before F-036, or whose
+docs root was bootstrapped by the agent (which runs `index`, never `init`), never
+received it retroactively -- and until F-041 nothing said so. `check` now prints, right after its summary line, a
+one-line `[note]` when no orientation hook is detectable (`.claude/settings.json`,
+`.claude/settings.local.json`, `.codex/hooks.json`), and a DISTINCT note when a hook is
+wired but the validator it names does not resolve (the wired-and-DEAD state below --
+silence there would bless the worst of the three states). The notes are informational
+only: never the exit code, never a `validate` warning -- CI (`validate --strict`) does
+not see them, because the wired hook legitimately lives in the git-ignored
+`settings.local.json`. Known residuals, accepted as honest: a client with no hook
+mechanism (Gemini today) keeps the note -- read it as the manual-reads reminder; a
+`.codex/hooks.json` wired in a shape other than the documented one keeps it too.
+
 **Which settings file, and why it is not always the shared one.** The command names a
 validator, and where that validator lives decides where the hook may be written:
 
@@ -133,6 +147,38 @@ 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 -- for the client to inject at every prompt. Cost: ~50 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):
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python \"C:\\Users\\<user>\\.claude\\skills\\kb-agentic\\scripts\\sdlc_check.py\" remind"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
 ## 5. Skill eval battery (release gate)
 
 **Skill development only.** `test_*.py` and `evals/` are deliberately absent from the npm `files` allowlist — they never reach an installed consumer, so this section applies to whoever builds the skill, not to a project that uses it. (Consumers get `sdlc_check.py`; §1–§4 are theirs.)

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

@@ -1,6 +1,6 @@
 ---
 name: kb-agentic
-version: 1.7.0
+version: 1.8.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
@@ -23,7 +23,7 @@ Support files in the skill directory:
 - `review.md`: the review discipline — when a review is due, how to request one, how to receive findings, how to review.
 - `dispatch.md`: opt-in subagent execution of an approved plan.
 - `routing.md`: which lens owns this unit of work. Read ONLY when a sibling lens skill is installed alongside this one; a single-lens install never reads it.
-- `scripts/sdlc_check.py` + `scripts/sdlc_core.py`: the mechanical validator for the docs root (`check`, `validate`, `index`, `stale`, `mark`, `gate`, `plan`, `orient`, `migrate`, and the knowledge overlay: `graph`, `corpus`, `claim-id`, `anchor`, `export`, `import`). Two files: the core is the family's shared spine; the entry point IS the knowledge overlay — the claim ledger and topic-graph checks live inside it, so the core alone runs none of them. Copy both, or neither.
+- `scripts/sdlc_check.py` + `scripts/sdlc_core.py`: the mechanical validator for the docs root (`check`, `validate`, `index`, `stale`, `mark`, `gate`, `plan`, `orient`, `migrate`, and the knowledge overlay: `graph`, `corpus`, `claim-id`, `anchor`, `export`, `import`, plus `remind` — the opt-in per-turn one-line reminder, ENFORCEMENT §4). Two files: the core is the family's shared spine; the entry point IS the knowledge overlay — the claim ledger and topic-graph checks live inside it, so the core alone runs none of them. Copy both, or neither.
 - `ENFORCEMENT.md`: optional setup for CI and hooks.
 
 Read these files only when needed. `SKILL.md` is the operating contract; the support files are progressive resources.

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

@@ -1598,6 +1598,26 @@ 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. 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.")
+    return 0
+
+
 def kb_cmd_help():
     """The spine's usage, then the overlay's own commands.
 
@@ -1619,6 +1639,8 @@ knowledge overlay (kb-agentic) -- also available:
   anchor <path> <phrase>      resolve a phrase to a verified locator span
   export --out <dir>          bundle a subgraph WITH the bytes its claims cite
   import <dir>                merge a bundle in additively (never overwrites)
+  remind                      one-line per-turn reminder (UserPromptSubmit hook,
+                              opt-in -- ENFORCEMENT par.4; constant, zero-read)
 
   index / validate / check    the spine's behaviour PLUS the claim ledger and
                               the topic graph""")
@@ -1636,6 +1658,10 @@ 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

@@ -1646,6 +1646,109 @@ def cmd_mark(root, paths):
     return 0
 
 
+# ------------------------------------------------- orientation-hook wiring
+# F-041: read-only mirror of the installer-side detection in lib.js
+# (findOrientHook + orientHookValidator). The JS owns WRITING hooks, with its
+# injection guards; this side only DETECTS, at `check`, so a project whose
+# sessions start unoriented hears about it in-project (ENFORCEMENT par.4: the
+# hook is wired at init only -- pre-F-036 and agent-bootstrapped projects never
+# got it, and a wired-but-dead hook is "the worst of the three states").
+# The file list is a SUPERSET of the JS one: .codex/hooks.json is documented in
+# ENFORCEMENT par.4 but never written by init. Entry-point names are pinned
+# equal on both sides.
+ORIENT_HOOK_ENTRY_POINTS = ("sdlc_check.py", "mkt_check.py")
+ORIENT_HOOK_CONFIG_FILES = (".claude/settings.json",
+                            ".claude/settings.local.json",
+                            ".codex/hooks.json")
+ORIENT_HOOK_CONFIG_CAP = 1024 * 1024  # settings are tiny; cap pathological files
+_ORIENT_HOOK_CMD_RE = re.compile(r" orient(\s|$)")
+_ORIENT_HOOK_TOKEN_RE = re.compile(r'"([^"]*)"|(\S+)')
+
+
+def _orient_hook_commands(root):
+    """Yield the command strings of SessionStart entries invoking an orient
+    entry point, across every known client config under root. Fail-open: an
+    unreadable, oversized, malformed or directory-shaped file contributes
+    nothing. Reads are utf-8-sig -- a BOM'd settings.json (PowerShell/Notepad)
+    must not read as unwired (declared divergence from Node's JSON.parse)."""
+    for rel in ORIENT_HOOK_CONFIG_FILES:
+        p = Path(root) / rel
+        try:
+            if not p.is_file() or p.stat().st_size > ORIENT_HOOK_CONFIG_CAP:
+                continue
+            data = json.loads(p.read_text(encoding="utf-8-sig"))
+        except Exception:
+            continue
+        if not isinstance(data, dict):
+            continue
+        hooks = data.get("hooks")
+        groups = hooks.get("SessionStart") if isinstance(hooks, dict) else None
+        if groups is None:
+            groups = data.get("SessionStart")  # the .codex/hooks.json shape
+        if not isinstance(groups, list):
+            continue
+        for group in groups:
+            if not isinstance(group, dict):
+                continue
+            inner = group.get("hooks")
+            for h in inner if isinstance(inner, list) else [group]:
+                cmd = h.get("command") if isinstance(h, dict) else None
+                if (isinstance(cmd, str)
+                        and any(n in cmd for n in ORIENT_HOOK_ENTRY_POINTS)
+                        and _ORIENT_HOOK_CMD_RE.search(cmd)):
+                    yield cmd
+
+
+def orient_hook_state(root):
+    """'wired' | 'dead' | 'unwired'.
+
+    A matching entry whose tokens name no validator is "cannot tell" and counts
+    as wired (the lib.js contract: never report broken on cannot-tell). 'dead'
+    requires every matching entry to name a validator that does not resolve:
+    the client runs ALL SessionStart hooks, so one live entry beside a dead one
+    still orients the session (any-resolves aggregation). Relative tokens
+    resolve against the project root -- the vendored-validator convention."""
+    matched = False
+    for cmd in _orient_hook_commands(root):
+        matched = True
+        token = None
+        for m in _ORIENT_HOOK_TOKEN_RE.finditer(cmd):
+            tok = m.group(1) if m.group(1) is not None else m.group(2)
+            if any(tok.endswith(n) for n in ORIENT_HOOK_ENTRY_POINTS):
+                token = tok
+                break
+        if token is None:
+            return "wired"
+        tp = Path(token)
+        if not tp.is_absolute():
+            tp = Path(root) / tp
+        if tp.exists():
+            return "wired"
+    return "dead" if matched else "unwired"
+
+
+def print_orient_hook_note(root):
+    """Print the FS-A wiring note (unwired / dead), or nothing when wired.
+
+    Informational only, by contract: never an exit code, never a validate
+    warning (--strict CI must not fail on a hook that legitimately lives in
+    git-ignored settings.local.json). Called by the spine's cmd_check AND by
+    an overlay that replaces check with its own pipeline (the marketing lens
+    does): the note is check-layer behaviour, whoever owns the check."""
+    try:
+        state = orient_hook_state(root)
+        if state == "unwired":
+            print("[note] no session-orientation hook wired (.claude/settings.json, "
+                  ".claude/settings.local.json, .codex/hooks.json): sessions start "
+                  "unoriented -- run the installer's init or wire it per ENFORCEMENT.md par.4")
+        elif state == "dead":
+            print("[note] a session-orientation hook is wired but the validator it names "
+                  "does not resolve: sessions start unoriented -- re-run init or fix the "
+                  "command (ENFORCEMENT.md par.4)")
+    except Exception:
+        pass  # detection must never break check
+
+
 def cmd_check(root, strict=False, hybrid=False):
     print("===== validate =====")
     rc_v = cmd_validate(root, strict=strict, hybrid=hybrid)
@@ -1653,6 +1756,7 @@ def cmd_check(root, strict=False, hybrid=False):
     rc_s = cmd_stale(root, hybrid=hybrid)
     print(f"\ncheck: {'CLEAN' if not (rc_v or rc_s) else 'NOT CLEAN'} "
           f"(validate rc={rc_v}, stale rc={rc_s})")
+    print_orient_hook_note(root)
     return 1 if (rc_v or rc_s) else 0