@antoneeo/kb-agentic-skill 1.13.0 → 1.15.0

package/CHANGELOG.md

@@ -2,6 +2,87 @@
 
 Every significant change to this skill is recorded here.
 
+## [1.15.0] - 2026-09-12
+
+### Fixed
+- **F-047: one row asserts one thing.** Field report: a bundled claim row
+  ("X, and also Y") made the checker's remedies point in opposite directions —
+  the collision message told the author to merge rows that assert different
+  things, and the state-grammar message denied a multi-successor `SUPERSEDED`
+  that every documented site also denied. The collision message is now
+  narrow-first and proposes a merge only where a single assertion is shared;
+  the grammar message states the form it accepts; and a plurality hint
+  (notes tier, never the exit code) flags a row that reads as more than one
+  claim. NOT demonstrated: a pre-registered blind A/B of the citation-scope
+  rule on the field's own row returned NULL (3/3 correct in both arms —
+  ceiling effect, the row names its off-topic subject explicitly), and the
+  Diary records it as such.
+- **F-053: kb had no human-approval rule.** "Never auto-accept a devPNT
+  proposal: present the preview and wait for explicit confirmation" existed in
+  both sibling packages and nowhere in this one — invisible because the only
+  battery assertion sat inside a test that skips every lens without a
+  `hybrid.md`, which is exactly the lens that lacked the rule. The rule is now
+  in kb's Hybrid block, and the battery test that pins it skips no lens and
+  goes red when the rule is stripped from a whole-lens copy.
+- **F-053: the authoring-floor pointer reached one lens of three.** It is now
+  in this contract too, before the instruction to write the analysis — where
+  the rule can still change what gets written, rather than at the design-review
+  gate one phase too late.
+
+### Added
+- **The shared spine gains the capability floor, the delegation boundary and
+  `benefit`** (F-048, F-049, F-050 — see the code lens's changelog for the
+  reasoning; the files are byte-identical across the three packages).
+
+### Read cost
+- This lens's mandatory contract GREW **+7.1%** (27,516 -> 29,471 B): it
+  received the spine's new doctrine and the two rules above, and no diet. The
+  Hybrid seam was measured for extraction and DECLINED — kb's block is 299 B
+  against a 1,282 B pointer, so moving it would grow the file it should shrink.
+
+## [1.14.1] - 2026-09-06
+
+### Fixed
+- **F-046 shipped a hook that wired nowhere.** `wireRemindHookInto` used the
+  ORIENT hook's opt-out marker (`orient-hook-wired`) as its own. That file is
+  present on every machine that ever installed the skill, so the installer read
+  it as "the user opted out of the per-turn reminder" and never wrote the hook —
+  for everyone. Two smaller faults in the same function: the marker was checked
+  BEFORE testing whether the hook was already present, and no marker was ever
+  written after a successful wire, so the real opt-out could never arm. The hook
+  now has its own `remind-hook-wired` marker, checked after the presence test and
+  written only on success. Regression pinned in `scripts/test_clients.js` (red
+  against 1.32.0: an orient-marked machine got no hook).
+
+## [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/README.md

@@ -37,7 +37,7 @@ Deliberately absent: any per-node coverage or completion state. `gaps:` says wha
 - **Independent review, twice**: the design before it is implemented, the result before it is declared done — fresh-context subagent > one-shot run > a declared self-pass, 3 rounds max, one log line each, and a PASS is invalid on "found nothing".
 - **Question discipline**: a question is legal only when the agent searched first, names the search with its result, and names the decision it unblocks; otherwise it proceeds on a declared assumption, batched.
 - **Operative guides + agent-global KB**: distil user-provided indications into source-faithful `GUIDE_*.md` (`source_kind: document`) — verbatim snapshot plus hash, so drift is detected mechanically.
-- **Mechanical checks**: `check`, `validate`, `index`, `graph`, `corpus`, `claim-id`, `anchor`, `export`, `import`, `stale` (spine staleness plus `## claims` -- superseded-cited documents, expired `valid` windows, superseded derivation chains), plus the spine's `mark`/`gate`/`plan`/`orient`/`migrate`. The graph and corpus checks verify spans against the stored extraction, recompute every id, refuse cycles and unreachable nodes, and enforce `CONTESTED` symmetry.
+- **Mechanical checks**: `check`, `validate`, `index`, `graph`, `corpus`, `claim-id`, `anchor`, `export`, `import`, `stale` (spine staleness plus `## claims` -- superseded-cited documents, expired `valid` windows, superseded derivation chains), plus the spine's `mark`/`benefit`/`gate`/`plan`/`orient`/`migrate`. `benefit` reports what the review gates have already caught, beside what the doctrine costs to read; it always exits 0 and carries no verdict. The graph and corpus checks verify spans against the stored extraction, recompute every id, refuse cycles and unreachable nodes, and enforce `CONTESTED` symmetry.
 - **Installed support files**: Claude, Codex, Gemini and Google Antigravity receive the full skill folder — `SKILL.md`, `templates.md`, `taxonomy.md`, `distillation.md`, `reconciliation.md`, `guides.md`, `vision.md`, `elicitation.md`, `review.md`, `dispatch.md`, `routing.md`, `ENFORCEMENT.md`, and the validator's two files, `scripts/sdlc_check.py` + `scripts/sdlc_core.py` (the core is the family's shared spine — copy both, or neither).
 
 ## Installation
@@ -115,3 +115,32 @@ Triage, the Vision Gate, the review gates, the guide router, question discipline
 Created by **Antonio Pinto** ([GitHub](https://github.com/Antoneeo)).
 
 MIT (c) 2026 Antonio Pinto.
+
+## Which model to run it on
+
+The skill names **capability tiers**, never providers — a model name in doctrine
+rots at the next release. The binding is yours to make, and the rule is one line:
+
+> **A session's floor is the highest floor among the roles it performs itself.**
+
+Authoring a governed artifact — the vision, the analysis, the use cases, the
+threat model — is a **deep-tier** role: its output is judgement, and nothing
+downstream scores it. So a session that will DESIGN wants your strongest model.
+A session that only executes an already-approved plan, or does small maintenance,
+can sit a tier lower. The cheapest tier is the wrong choice for the main session
+whatever the task, because the failure there is not a wrong answer — it is
+**silently not applying the process**: a triage never run, a router verdict
+declared without the lookup, a gate nobody noticed. That failure is invisible to
+every check in here.
+
+**The reviewer's tier is not automatically yours.** On some clients a subagent
+inherits the session's model; on others it takes one from its own definition, so
+a strong session can be reviewed by a weak one — and a weak session can buy a
+strong review. Set it deliberately; the
+`model` column in the review log is where the choice becomes visible.
+
+**Avoid one combination**: authoring below the floor AND reviewing below the floor
+on the same unit. One disclosed weakness is a disclosed weakness; two is an
+artifact nobody competent ever read. Where your client offers nothing better, the
+review still runs and both facts are recorded — a disclosed worst case beats
+skipping the review.

package/gemini-extension.json

@@ -1,6 +1,6 @@
-{
-  "name": "kb-agentic-skill",
-  "version": "1.13.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)"
-}
+{
+  "name": "kb-agentic-skill",
+  "version": "1.15.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,51 +1,51 @@
-{
-  "name": "@antoneeo/kb-agentic-skill",
-  "version": "1.13.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",
-    "claude-skill",
-    "gemini-cli",
-    "skill",
-    "knowledge-base",
-    "documentation",
-    "ai-agent"
-  ],
-  "author": "Antonio Pinto (https://github.com/Antoneeo)",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "bin": {
-    "kb-agentic-init": "scripts/init.js",
-    "kb-agentic-install-skill": "scripts/postinstall.js"
-  },
-  "scripts": {
-    "postinstall": "node scripts/postinstall.js",
-    "preuninstall": "node scripts/preuninstall.js"
-  },
-  "files": [
-    "skills/kb-agentic-skill/SKILL.md",
-    "skills/kb-agentic-skill/templates.md",
-    "skills/kb-agentic-skill/taxonomy.md",
-    "skills/kb-agentic-skill/guides.md",
-    "skills/kb-agentic-skill/vision.md",
-    "skills/kb-agentic-skill/distillation.md",
-    "skills/kb-agentic-skill/reconciliation.md",
-    "skills/kb-agentic-skill/elicitation.md",
-    "skills/kb-agentic-skill/review.md",
-    "skills/kb-agentic-skill/dispatch.md",
-    "skills/kb-agentic-skill/routing.md",
-    "skills/kb-agentic-skill/portability.md",
-    "skills/kb-agentic-skill/ENFORCEMENT.md",
-    "skills/kb-agentic-skill/scripts/sdlc_check.py",
-    "skills/kb-agentic-skill/scripts/sdlc_core.py",
-    "gemini-extension.json",
-    "README.md",
-    "CHANGELOG.md",
-    "scripts/lib.js",
-    "scripts/init.js",
-    "scripts/postinstall.js",
-    "scripts/preuninstall.js"
-  ]
-}
+{
+  "name": "@antoneeo/kb-agentic-skill",
+  "version": "1.15.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",
+    "claude-skill",
+    "gemini-cli",
+    "skill",
+    "knowledge-base",
+    "documentation",
+    "ai-agent"
+  ],
+  "author": "Antonio Pinto (https://github.com/Antoneeo)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "kb-agentic-init": "scripts/init.js",
+    "kb-agentic-install-skill": "scripts/postinstall.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "preuninstall": "node scripts/preuninstall.js"
+  },
+  "files": [
+    "skills/kb-agentic-skill/SKILL.md",
+    "skills/kb-agentic-skill/templates.md",
+    "skills/kb-agentic-skill/taxonomy.md",
+    "skills/kb-agentic-skill/guides.md",
+    "skills/kb-agentic-skill/vision.md",
+    "skills/kb-agentic-skill/distillation.md",
+    "skills/kb-agentic-skill/reconciliation.md",
+    "skills/kb-agentic-skill/elicitation.md",
+    "skills/kb-agentic-skill/review.md",
+    "skills/kb-agentic-skill/dispatch.md",
+    "skills/kb-agentic-skill/routing.md",
+    "skills/kb-agentic-skill/portability.md",
+    "skills/kb-agentic-skill/ENFORCEMENT.md",
+    "skills/kb-agentic-skill/scripts/sdlc_check.py",
+    "skills/kb-agentic-skill/scripts/sdlc_core.py",
+    "gemini-extension.json",
+    "README.md",
+    "CHANGELOG.md",
+    "scripts/lib.js",
+    "scripts/init.js",
+    "scripts/postinstall.js",
+    "scripts/preuninstall.js"
+  ]
+}

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

@@ -102,7 +102,7 @@ Semantics: exit code 2 + message on stderr ⇒ the write is blocked and the mess
 - The paths in `--protected` are prefixes relative to the project root, separated by `;`.
 - `ai_docs/`, `tests/` and `test/` are always excluded from blocking.
 - The hook assumes the working directory is the project root (standard behavior of Claude Code hooks).
-- **Hybrid/devPNT projects**: add `--hybrid` to the gate command. Governed designs live in the devPNT DB, so the gate also unlocks when an approved E-TDD shadow (`ai_docs/solutions/SHADOW_*tdd*.md`, exported before implementation — see the SKILL.md shadow discipline) is present. Without the flag the gate would block legitimate governed work. The flag is deliberately explicit: never auto-detected.
+- **Hybrid/devPNT projects**: add `--hybrid` to the gate command. Governed designs live in the devPNT DB, so the gate also unlocks when an approved E-TDD shadow (`ai_docs/solutions/SHADOW_*tdd*.md`, exported before implementation — in this package that clause is the whole statement of the duty; the sibling lenses keep it in their `hybrid.md`, which kb does not have) is present. Without the flag the gate would block legitimate governed work. The flag is deliberately explicit: never auto-detected.
 
 ## 4. SessionStart hook (orientation, recommended default)
 
@@ -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"
           }
         ]
       }
@@ -253,3 +261,12 @@ It aggregates the three test files (`test_plan.py` + `test_session_start.py` + `
 **Optional CI** (same shape as §2, not mandatory): add a `run:` step invoking the `unittest discover` command above.
 
 **T10 note:** if you copied `sdlc_check.py` and the `test_*.py` battery into the repo for CI, that copy is authoritative — keep it current when you update the skill.
+
+## `benefit` is a report, never a CI gate
+
+`sdlc_check.py benefit` reports what the review gates caught and what the
+doctrine costs to read. It always exits 0 and emits no warning: **never wire
+it into CI**. It is the criterion by which future units are judged, and a
+measurement that can fail a build becomes a target -- a targeted measurement
+stops measuring. Run it when deciding whether a proposed rule is worth its
+ceremony, not on every push.