@antoneeo/kb-agentic-skill 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 Every significant change to this skill is recorded here.
 
+## [1.10.0] - 2026-08-28
+
+F-043 -- the revision doctrine: documents read as current state.
+
+### Added
+- **`## Revision — the full re-read` (SKILL.md).** Incorporating new knowledge
+  into an existing document is a rewrite, not an append: full re-read first,
+  body rewritten to current state, history in the Diary (past entries never
+  rewritten -- a correction is a new entry), claim tables exempt (rows move only
+  per reconciliation), node frontmatter exempt (a revision never re-parents),
+  and a multi-document pass re-reads PER DOCUMENT. Wired where the trigger
+  fires: the L2 triage row and the L3 Phase-4 flow (citation-only pointers);
+  the honest limit is in the doctrine's own text. Born from a field post-mortem
+  (12 documents realigned by delta-append; stale sentences left standing) --
+  and completed by its own review: three rounds, each catching the doctrine's
+  failure mode inside its own ANALYSIS.
+- **The `remind` line carries the gesture** ("Re-read it whole and rewrite it
+  to current state ..."): 443 chars, ~75 tokens per prompt, still one constant
+  zero-read line.
+
 ## [1.9.0] - 2026-08-28
 
 F-042 -- the install wires the hook; the incomprehensible question dies.

package/README.md

@@ -24,6 +24,8 @@ Two axes are kept apart on purpose — **abstraction** (a topic made of topics:
 
 7. **Capture — the day's decisions reach the ledger before they evaporate.** At a user-signed closing ("chiudiamo"), one sweep question — carrying its own inline result: "today I recorded X and Y — any other decisions from today?" — reaches even the decisions taken outside the session, which no transcript search could find. What surfaces lands on the existing rails (an elicited dated note, an L1 claim row) with explicit provenance; the sweep is idempotent (nothing captured twice), never creates topics, and stays silent when no one signed off. The kb `orient` shows notes recency at every session start — dated from note frontmatter, because file mtimes lie after a clone or worktree — so a missed capture is visible the next morning.
 
+8. **Revision — documents read as current state.** Incorporating new knowledge into an existing document is a full re-read and a body rewrite, not a stack of dated deltas: anchored edits are each correct while the document as a whole rots. The doctrine keeps history in the Diary (past entries never rewritten), leaves claim tables to reconciliation and graph edges to the taxonomy, and runs per document even in a multi-document pass. Born from a real field post-mortem: twelve documents realigned by append, every untouched sentence left standing as printed truth.
+
 Deliberately absent: any per-node coverage or completion state. `gaps:` says what a node lacks; nothing collects it into a dashboard. A **source** does record how far it has been read, but on its own sidecar and nowhere else — the corpus index prints that fact for every artifact, including the finished ones, because a list of only what is behind is the dashboard this method refuses.
 
 ## Key features

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "kb-agentic-skill",
-  "version": "1.9.0",
+  "version": "1.10.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.9.0",
+  "version": "1.10.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

@@ -169,8 +169,8 @@ Gemini CLI — wire the same command into its startup-hook mechanism if present;
 `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
+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

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

@@ -1,6 +1,6 @@
 ---
 name: kb-agentic
-version: 1.9.0
+version: 1.10.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
@@ -46,7 +46,7 @@ Always classify the request before choosing the process. Declare the chosen leve
 | Level | Criteria | Required process |
 |---|---|---|
 | **L1 - Quick Fact / Snippet** | One claim row added to an existing topic; a typo; a preference update. No node created, no source entering the corpus, no frontmatter change. | Implement edit directly in existing note. No new documents. |
-| **L2 - Propagation of settled knowledge** | The fact is **already settled** in the corpus and the work carries it into existing documents — restating, correcting a stale copy, updating an SOP that quotes it. No node created or superseded, no hierarchy change, no node frontmatter change, no new source ingested. | Mini-analysis in message: objective, impact, sources, validation. Update existing document or create single SOP/note. |
+| **L2 - Propagation of settled knowledge** | The fact is **already settled** in the corpus and the work carries it into existing documents — restating, correcting a stale copy, updating an SOP that quotes it. No node created or superseded, no hierarchy change, no node frontmatter change, no new source ingested. | Mini-analysis in message: objective, impact, sources, validation. Update existing document (full re-read per `## Revision`) or create single SOP/note. |
 | **L3 - New knowledge unit / Corpus** | A source enters the corpus; a topic node is created or superseded; the hierarchy moves; a conflict must be reconciled; or what a claim asserts changes. | Full workflow: Vision Gate, Spec Elicitation, Taxonomy Pass, Knowledge Analysis, Distillation, Review, Indexing. |
 | **Spike - Exploration** | Time-boxed exploratory research or draft without merging into official KB. | Outcome in `ai_docs/solutions/SPIKE_[topic].md`. |
 
@@ -124,7 +124,7 @@ Use this mode when `devpnt_*` tools are available and point at the current proje
 - **Design review gate (end of Phase 3, before any drafting):** the analysis is reviewed by somebody other than its author — a subagent with fresh context, or a declared self-pass when no higher rung is usable — a permission-gated rung is asked about, never silently skipped (`review.md`). Follow `review.md`; log the outcome in `audit/reviews/REVIEW_LOG.md`. A knowledge structure reviewed only by the person who chose it is not reviewed.
 
 ### 4. Knowledge Processing & Distillation
-- **Isolate the work (Branch/worktree hygiene).** Distillation rewrites existing notes: do it on a branch or a worktree, never directly on the shared corpus, so a half-finished reconciliation is never what the next reader finds.
+- **Isolate the work (Branch/worktree hygiene).** Distillation rewrites existing notes — full re-read per `## Revision` — and does it on a branch or a worktree, never directly on the shared corpus, so a half-finished reconciliation is never what the next reader finds.
 - Before drafting (L2/L3; L1 exempt), **consult the guide router** for a guide covering the task and read it first (the consult trigger, `guides.md` §0). A targeted description match, not a blanket read. Its result is the router verdict already declared with the triage level (Rule Zero).
 - Execute knowledge extraction using **Signal Distillation** (`distillation.md`).
 - **Opt-in subagent execution**: for an L3 with an approved analysis, the work MAY be executed via subagents per `dispatch.md`; default stays same-session.
@@ -243,6 +243,24 @@ exist — this section adds only the MOMENT.
 - **Silence stays legal where no one signed off**: no closing signal → no question,
   no ritual line.
 
+## Revision — the full re-read
+
+Incorporating new knowledge into an existing document is a rewrite, not an
+append: anchored edits are each correct while the global invariant — the body
+reads as CURRENT state — is never re-verified. The gesture:
+- Re-read the WHOLE document before editing; then rewrite the body so it reads
+  as written today — new knowledge fused, never quarantined in dated
+  sections — never append a delta.
+- History goes to the Diary/notes, never an inline chronicle — and past Diary
+  entries are never rewritten: a correction is a new entry.
+- A SUPERSEDED banner is a tombstone, never a revision device in a living doc.
+- Claim tables are EXEMPT (rows move only per `reconciliation.md`) and node
+  frontmatter moves only per `taxonomy.md` — a revision never re-parents; the
+  rewrite governs prose, never the ledger or the graph edges.
+- A multi-document pass re-reads PER DOCUMENT; set coverage is not integrity.
+- The re-read raises the probability of catching a false premise; it cannot
+  guarantee it — domain judgment stays the human's.
+
 ## Mechanical Enforcement
 - `scripts/sdlc_check.py index`: updates `ai_docs/INDEX.md` and `ai_docs/reference/INDEX.md`.
 - `scripts/sdlc_check.py validate`: validates YAML frontmatter (`status`, `description`).

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

@@ -1602,7 +1602,7 @@ 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
+    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
@@ -1614,7 +1614,7 @@ def kb_cmd_remind(_argv):
           "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.")
+          "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