@antoneeo/kb-agentic-skill 1.14.0 → 1.16.0

package/CHANGELOG.md

@@ -2,6 +2,98 @@
 
 Every significant change to this skill is recorded here.
 
+## [1.16.0] - 2026-09-12
+
+### Changed
+- **F-054: the recall verdict names every branch the descent opened.** The
+  descent is multi-branch by mandate (`taxonomy.md` §1: follow every parent,
+  open the final candidates), and the verdict vocabulary assumed exactly one
+  matched slug — so a mandated act had no legal way to declare its result, and
+  an agent facing two legitimate branches invented a shape for it. Both
+  node-naming verdicts now read `kb: <slug>[, <slug> …] → …`, naming every slug
+  opened and not only the one that answered, because which branches were read is
+  the part of the verdict a reader can check. **Four legal values, unchanged**:
+  the repair is the form, never a fifth value, and the count is pinned against
+  creep. Found by replaying the doctrine against a real question rather than by
+  reading it.
+
+### Fixed
+- **The behavioural eval driver died on its own scenarios.** `run_behavioral.py`
+  read scenarios as UTF-8 and printed them to a console that, on Windows,
+  defaults to cp1252 — which has no mapping for `→`. The shipped scenario
+  `recall_descends_before_answering.md` has contained that character since 1.7.0,
+  so on a default Windows console that eval was un-runnable and the driver
+  exited before printing its own pass criteria. stdout is now reconfigured to
+  UTF-8 with `errors="replace"`: a console that cannot render a glyph is not a
+  reason to withhold the scenario.
+
+### Not demonstrated
+- **The defect this release was opened to fix does not exist, as stated.** The
+  claim was that the recall's four verdicts all sit downstream of one instrument,
+  so a descent picking the wrong branch declares `kb: no coverage` on a corpus
+  that holds the answer — a false negative indistinguishable from real absence.
+  Two agent-level replays refuted it, including a fixture built to be hostile
+  (eight topics, the answering claim under `gdpr_compliance` while
+  `observability` was the more plausible branch): both returned the right claim,
+  and one ran a `grep` cross-check unprompted. A mandated text probe and a
+  generated claims inventory were therefore abandoned rather than shipped, and no
+  assertion pins them — a probe pinning what was decided against is red by
+  construction. Standing limit: two runs, one subject model, fixtures authored by
+  the session that made the claim. Record in
+  `ai_docs/solutions/SPIKE_kb_recall_second_instrument.md`.
+
+## [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

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.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)"
-}
+{
+  "name": "kb-agentic-skill",
+  "version": "1.16.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.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",
-    "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.16.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)
 
@@ -261,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.