@antoneeo/kb-agentic-skill 1.8.0 → 1.10.0

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 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.
+
+### Added
+- **Installing or updating the package wires the session-orientation hook
+  machine-wide** (Claude Code with Python; user-level settings). The npm install
+  is the consent -- no question is ever asked. Removal is a standing opt-out: a
+  per-target marker remembers every settings file ever wired and no update
+  re-adds a removed hook; deleting the marker re-enables. `npm uninstall`
+  surgically removes only the entries attributable to the removed skill, across
+  every world the marker remembers, so no dead hook is left behind. `init` now
+  reports "covered by the machine-global hook" instead of wiring a duplicate,
+  and still reports a dead or unverifiable global wrapper while wiring the
+  project.
+- **The check note is global-aware and speaks user language.** Detection now
+  also reads the user-level settings (`CLAUDE_CONFIG_DIR` honored;
+  `AGENTIC_SDLC_USER_SETTINGS` is the test seam), so a fixed machine stops
+  being nagged; the two notes are reworded consequence-first ("agent sessions
+  start without automatic orientation...") so the agent relaying them can ask a
+  question a normal user understands.
+
 ## [1.8.0] - 2026-08-28
 
 F-041 -- the mid-session drift field report, both items.

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
@@ -71,7 +73,12 @@ kb-agentic-init
 
 Run it inside a project to create `ai_docs/`, Vision documents, strategic docs, audit plan, and agent protocol files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`).
 
-It also **wires the SessionStart orientation hook** into `.claude/`, so an agent opening
+Installing or updating the npm package **wires the session-orientation hook
+machine-wide** (user-level `~/.claude/settings.json`, Claude Code with Python):
+every project with a docs root greets its agent already oriented, and removing
+the entry is a standing opt-out that no update ever overrides. `init` still
+wires per-project where that is the better shape (a vendored validator, a
+shared team file), so an agent opening
 the project is handed the reading guide, the generated manifest, the guide router and the
 last handoff before it does anything — instead of only when it remembers to look. That
 wiring used to be a manual step documented in `ENFORCEMENT.md`; being manual, it was
@@ -82,8 +89,8 @@ 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. Since F-041, `check` also
-prints a one-line note when a project has no orientation hook wired (or a dead
+with the correction rather than counted as installed. `check` prints a one-line
+note when a machine has no orientation hook at project or user level (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.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "kb-agentic-skill",
-  "version": "1.8.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.8.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/scripts/init.js

@@ -3,7 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const { SKILL_SOURCE, INSTALLED_SKILL_NAME, SELF_LENS, SIBLING_LENSES, CLIENTS, clientDetected, skillTarget, wireOrientHook, loadTemplates, templateFor } = require('./lib');
+const { SKILL_SOURCE, INSTALLED_SKILL_NAME, SELF_LENS, SIBLING_LENSES, CLIENTS, clientDetected, skillTarget, wireOrientHook, detectPython, loadTemplates, templateFor } = require('./lib');
 
 const cwd = process.cwd();
 
@@ -152,16 +152,8 @@ let protocolPreexisting = false;
 // Probed ONCE and reused by section 6c: re-filtering CLIENTS there would
 // run every client's detection a second time.
 const detectedClients = CLIENTS.filter(clientDetected);
-const PYTHON_CANDIDATES = ['python', 'python3', 'py'];
-const detectedPython = (() => {
-  for (const py of PYTHON_CANDIDATES) {
-    try {
-      execSync(`${py} --version`, { stdio: 'ignore' });
-      return py;
-    } catch (e) { /* try the next interpreter */ }
-  }
-  return null;
-})();
+// One probe, shared with postinstall's global wiring (F-042): lib owns it.
+const detectedPython = detectPython();
 
 for (const client of detectedClients) {
   {
@@ -276,8 +268,21 @@ if (!claudeClient) {
     hybrid: hybridProject, docsLabel: 'ai_docs',
   });
   switch (r.code) {
+    case 'global':
+      // F-042: a resolving machine-global hook already orients every project.
+      console.log('⏭️  Covered by the machine-global orientation hook — no project-level');
+      console.log(`   hook needed (${r.target}).`);
+      break;
     case 'wired':
       console.log(`🪝 Wired the SessionStart orientation hook in .claude/${r.file}.`);
+      if (r.globalNote === 'dead') {
+        console.log('⚠️  Note: a machine-global orientation hook exists but its validator');
+        console.log('   does not resolve — it emits nothing. Fix or remove it in your user');
+        console.log('   settings (ENFORCEMENT.md §4).');
+      } else if (r.globalNote === 'unverifiable') {
+        console.log('ℹ️  Note: your user settings carry an orientation hook this installer');
+        console.log('   cannot verify; the project-level hook above covers this project.');
+      }
       if (r.local) {
         console.log('   It names a path on THIS machine, so it went to the git-ignored');
         console.log('   file: each teammate runs init once to get their own.');
@@ -321,6 +326,12 @@ if (!claudeClient) {
       console.log(`   hook command safely: ${r.validator}`);
       console.log('   Refusing to build one. Wire it by hand (ENFORCEMENT.md §4).');
       break;
+    default:
+      // A lens port missing a case must be loud, never a silent skip — the
+      // exact defect class the manual-snippet note below exists to prevent.
+      console.log(`ℹ️  Orientation hook: unhandled result '${r.code}'. Wire it by hand`);
+      console.log('   per ENFORCEMENT.md §4.');
+      break;
   }
 }
 for (const c of otherClients) {

package/scripts/lib.js

@@ -358,6 +358,31 @@ function wireOrientHook(options) {
       : { code: 'broken', file: name, target: p, existing, command };
   }
 
+  // F-042: a resolving MACHINE-GLOBAL hook (user-level settings) already
+  // orients every project. Checked AFTER the project scan on purpose: a
+  // project-level broken/malformed/unverifiable must be reported first — a
+  // pre-check would mask a dead project hook behind "covered globally", the
+  // wired-and-DEAD state F-041 calls the worst of the three. A dead or
+  // unverifiable global hook falls through to the project write (the wrapper
+  // may be emitting nothing) and the caller gets `globalNote` to print the
+  // correction. A user-level token that is not absolute has no cwd to resolve
+  // against, so it is treated as unverifiable.
+  let globalNote;
+  {
+    const userTarget = path.join(client.home, 'settings.json');
+    const ustate = orientSettingsState(userTarget);
+    if (ustate.ok) {
+      const uexisting = findOrientHook(ustate.settings);
+      if (uexisting) {
+        const ufound = orientHookValidator(uexisting);
+        if (ufound !== null && path.isAbsolute(ufound) && fs.existsSync(ufound)) {
+          return { code: 'global', target: userTarget, command: uexisting };
+        }
+        globalNote = (ufound === null || !path.isAbsolute(ufound)) ? 'unverifiable' : 'dead';
+      }
+    }
+  }
+
   // A machine-specific command must not reach the shared, committed file.
   const file = vendored ? 'settings.json' : 'settings.local.json';
   const target = path.join(cwd, '.claude', file);
@@ -384,7 +409,209 @@ function wireOrientHook(options) {
   } catch (e) {
     return { code: 'write-failed', file, target, command, error: e.message };
   }
-  return { code: 'wired', file, target, command, local: !vendored };
+  return { code: 'wired', file, target, command, local: !vendored, globalNote };
+}
+
+// --- F-042: the machine-global hook (install-time wiring) -------------------
+// The F-041 field lesson: the check note asked a question a normal user cannot
+// evaluate. The owner's ruling: the hook is wired by the act the user already
+// performs — installing/updating the package — at the USER level, which the
+// installer knows exactly. `orient` is fail-open (no docs root ⇒ silent), so a
+// global hook is safe by construction on unmanaged projects. Removal is a
+// STANDING opt-out: a per-target marker remembers every settings file ever
+// wired, and no install or update ever re-adds a removed hook. Deleting the
+// marker file is the documented re-enable gesture (ENFORCEMENT §4).
+
+// Python detection, shared by init (project wiring + index) and postinstall
+// (global wiring). One list, one probe.
+const PYTHON_CANDIDATES = ['python', 'python3', 'py'];
+function detectPython() {
+  for (const py of PYTHON_CANDIDATES) {
+    try {
+      execSync(`${py} --version`, { stdio: 'ignore' });
+      return py;
+    } catch (e) { /* try the next interpreter */ }
+  }
+  return null;
+}
+
+// Case/separator normalization uses the PLATFORM'S OWN path.relative: win32
+// folds case and separators; forcing win32 semantics on POSIX would fold
+// genuinely distinct paths (a false positive). One helper guards BOTH the
+// uninstall attribution and the marker lookup — a naive prefix/string match
+// misses `c:\` vs `C:\`, which on attribution re-manufactures the dead hook
+// and on the marker re-wires against a standing opt-out.
+function pathsEqual(a, b) {
+  try {
+    return path.relative(String(a), String(b)) === '';
+  } catch (e) {
+    return false;
+  }
+}
+function pathInside(child, parent) {
+  try {
+    const rel = path.relative(String(parent), String(child));
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+  } catch (e) {
+    return false;
+  }
+}
+
+// The marker lives under the family's agent-global root (the same root the
+// validator's AGENTIC_SDLC_KB_ROOT seam names), read at call time so the test
+// battery's stubbed env applies. Every helper is fail-open: a broken marker
+// must never break an install, and a failed marker write never undoes a wire.
+function orientMarkerPath() {
+  const root = process.env.AGENTIC_SDLC_KB_ROOT
+    || path.join(os.homedir(), '.agentic-sdlc');
+  return path.join(root, 'orient-hook-wired');
+}
+function orientMarkerTargets() {
+  try {
+    return fs.readFileSync(orientMarkerPath(), 'utf8')
+      .split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+  } catch (e) {
+    return [];
+  }
+}
+function orientMarkerHas(target) {
+  return orientMarkerTargets().some((t) => pathsEqual(t, target));
+}
+function orientMarkerAdd(target) {
+  try {
+    if (orientMarkerHas(target)) return;
+    fs.mkdirSync(path.dirname(orientMarkerPath()), { recursive: true });
+    fs.appendFileSync(orientMarkerPath(), target + String.fromCharCode(10), 'utf8');
+  } catch (e) { /* fail-open */ }
+}
+function orientMarkerRemove(target) {
+  try {
+    const rest = orientMarkerTargets().filter((t) => !pathsEqual(t, target));
+    if (rest.length) {
+      fs.writeFileSync(orientMarkerPath(), rest.join(String.fromCharCode(10)) + String.fromCharCode(10), 'utf8');
+    } else {
+      fs.rmSync(orientMarkerPath(), { force: true });
+    }
+  } catch (e) { /* fail-open */ }
+}
+
+// Wire the machine-global hook into client.home/settings.json — exactly ONE
+// file (user level has no local split; the path is machine-local by nature).
+// Codes follow the wireOrientHook contract, plus `opted-out`.
+function wireGlobalOrientHook(options) {
+  const client = options.client;
+  const python = options.python;
+
+  const validator = path.join(skillTarget(client), 'scripts', ORIENT_ENTRY_POINT);
+  if (!fs.existsSync(validator)) return { code: 'no-validator', validator };
+  if (!python) return { code: 'no-python', validator };
+  if (ORIENT_UNSAFE_IN_PATH.test(validator)) return { code: 'unsafe-path', validator };
+  const command = orientHookCommand(python, validator, false);
+
+  const target = path.join(client.home, 'settings.json');
+  const state = orientSettingsState(target);
+  if (!state.ok) return { code: 'malformed', target, why: state.why, command };
+
+  const existing = findOrientHook(state.settings);
+  if (existing) {
+    const found = orientHookValidator(existing);
+    if (found === null || !path.isAbsolute(found)) {
+      // No cwd exists at user level, so an unresolvable token is "cannot
+      // tell" — left alone, never remembered as ours.
+      return { code: 'unverifiable', target, existing, command };
+    }
+    if (fs.existsSync(found)) {
+      // A hand-wired live hook, once removed, deserves the same respect as
+      // one this installer wrote: remember the target.
+      orientMarkerAdd(target);
+      return { code: 'already', target, command: existing };
+    }
+    return { code: 'broken', target, existing, command };
+  }
+
+  if (orientMarkerHas(target)) return { code: 'opted-out', target };
+
+  const settings = state.settings;
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.SessionStart)) settings.hooks.SessionStart = [];
+  settings.hooks.SessionStart.push({
+    hooks: [{
+      type: 'command',
+      command,
+      timeout: ORIENT_HOOK_TIMEOUT,
+      statusMessage: 'Loading docs orientation...',
+    }],
+  });
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, JSON.stringify(settings, null, 2) + String.fromCharCode(10), 'utf8');
+  } catch (e) {
+    return { code: 'write-failed', target, command, error: e.message };
+  }
+  orientMarkerAdd(target);
+  return { code: 'wired', target, command };
+}
+
+// Uninstall symmetry: removing the skill dirs would leave any global hook
+// naming them wired-and-DEAD. So, across EVERY settings target the marker
+// remembers (a hook wired under CLAUDE_CONFIG_DIR=/x must be cleaned from a
+// shell without that env) unioned with the current client.home, remove ONLY
+// the SessionStart entries whose validator token resolves INTO a root being
+// removed. Foreign or unverifiable entries are never touched. The marker line
+// is cleared ONLY when an entry was actually removed — when the user had
+// already removed the hook, the line stays and the opt-out survives uninstall,
+// reinstall, and sibling-lens uninstalls.
+function removeGlobalOrientHooks(removedRoots) {
+  const targets = [];
+  const claude = CLIENTS.find((c) => c.key === 'claude');
+  if (claude) targets.push(path.join(claude.home, 'settings.json'));
+  for (const t of orientMarkerTargets()) {
+    if (!targets.some((x) => pathsEqual(x, t))) targets.push(t);
+  }
+  const removedFrom = [];
+  for (const target of targets) {
+    try {
+      const state = orientSettingsState(target);
+      if (!state.ok || !fs.existsSync(target)) continue;
+      const hooks = state.settings.hooks;
+      if (!hooks || !Array.isArray(hooks.SessionStart)) continue;
+      let removedHere = false;
+      const ours = (h) => {
+        const cmd = h && typeof h.command === 'string' ? h.command : '';
+        if (!(ORIENT_ENTRY_POINTS.some((n) => cmd.includes(n)) && / orient(\s|$)/.test(cmd))) return false;
+        const tok = orientHookValidator(cmd);
+        if (tok === null || !path.isAbsolute(tok)) return false;   // cannot attribute: keep
+        return removedRoots.some((root) => pathInside(tok, root));
+      };
+      const kept = [];
+      for (const group of hooks.SessionStart) {
+        if (!group || typeof group !== 'object') { kept.push(group); continue; }
+        if (Array.isArray(group.hooks)) {
+          const inner = group.hooks.filter((h) => {
+            if (ours(h)) { removedHere = true; return false; }
+            return true;
+          });
+          if (inner.length) kept.push({ ...group, hooks: inner });
+          else if (inner.length !== group.hooks.length) { /* emptied: prune */ }
+          else kept.push(group);
+        } else if (ours(group)) {
+          removedHere = true;                      // direct-object shape: prune
+        } else {
+          kept.push(group);
+        }
+      }
+      if (!removedHere) continue;
+      state.settings.hooks.SessionStart = kept;
+      if (!kept.length) delete state.settings.hooks.SessionStart;
+      if (state.settings.hooks && !Object.keys(state.settings.hooks).length) {
+        delete state.settings.hooks;
+      }
+      fs.writeFileSync(target, JSON.stringify(state.settings, null, 2) + String.fromCharCode(10), 'utf8');
+      orientMarkerRemove(target);
+      removedFrom.push(target);
+    } catch (e) { /* fail-open per target: never abort an uninstall */ }
+  }
+  return removedFrom;
 }
 
 module.exports = {
@@ -397,6 +624,10 @@ module.exports = {
   clientDetected,
   skillTarget,
   wireOrientHook,
+  wireGlobalOrientHook,
+  removeGlobalOrientHooks,
+  detectPython,
+  pathsEqual,
   orientHookCommand,
   copyRecursive,
   loadTemplates,

package/scripts/postinstall.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 
 const fs = require('fs');
-const { SKILL_SOURCE, CLIENTS, clientDetected, skillTarget, copyRecursive } = require('./lib');
+const {
+  SKILL_SOURCE, CLIENTS, clientDetected, skillTarget, copyRecursive,
+  wireGlobalOrientHook, detectPython,
+} = require('./lib');
 
 function installSkill(client) {
   if (!fs.existsSync(SKILL_SOURCE)) {
@@ -29,7 +32,36 @@ for (const client of CLIENTS) {
   if (clientDetected(client)) {
     console.log(`✅ Detected: ${client.label}`);
     detected = true;
-    installSkill(client);
+    const installed = installSkill(client);
+    // F-042: wire the machine-global orientation hook — the install IS the
+    // consent, so no question is ever asked. Claude Code only (the one client
+    // whose hook shape a fixture pins); removal is a standing opt-out the
+    // marker remembers. A convenience must never fail an npm install: wrapped.
+    if (client.key === 'claude' && installed) {
+      try {
+        const r = wireGlobalOrientHook({ client, python: detectPython() });
+        if (r.code === 'wired') {
+          console.log('🔗 Session orientation wired for every project on this machine');
+          console.log(`   (${r.target}).`);
+          console.log('   Agents now start oriented on any project with a docs root; projects');
+          console.log('   without one see nothing. To opt out, remove that hook entry — it');
+          console.log('   will not be re-added.');
+        } else if (r.code === 'broken') {
+          console.log('⚠️  A session-orientation hook exists but the validator it names does');
+          console.log('   not resolve, so it has been emitting nothing. Correct its command to:');
+          console.log(`     ${r.command}`);
+        } else if (r.code === 'no-python') {
+          console.log('ℹ️  Python not found: session orientation not wired (wire it later per');
+          console.log('   ENFORCEMENT.md §4).');
+        } else if (r.code === 'malformed' || r.code === 'write-failed'
+                   || r.code === 'unsafe-path') {
+          console.log(`⚠️  Session orientation not wired (${r.code}). Wire it by hand per`);
+          console.log('   ENFORCEMENT.md §4.');
+        }
+        // already / opted-out / unverifiable / no-validator: silent — an
+        // install must not nag (the opt-out is the user's standing choice).
+      } catch (e) { /* never fail the install for a convenience */ }
+    }
   }
 }
 

package/scripts/preuninstall.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 const fs = require('fs');
-const { CLIENTS, skillTarget } = require('./lib');
+const { CLIENTS, skillTarget, removeGlobalOrientHooks } = require('./lib');
 
 function removeSkill(client) {
   const target = skillTarget(client);
@@ -14,4 +14,17 @@ function removeSkill(client) {
   }
 }
 
+// F-042: BEFORE the skill dirs go, remove the global orientation hooks that
+// name them — otherwise every future session carries a hook whose validator no
+// longer exists, the wired-and-DEAD state the check note calls the worst of
+// the three. Surgical (only entries attributable to the removed dirs; the
+// marker's opt-out lines survive when nothing was removed) and fail-open (an
+// uninstall must never abort on a settings file).
+try {
+  const removedFrom = removeGlobalOrientHooks(CLIENTS.map(skillTarget));
+  for (const target of removedFrom) {
+    console.log(`🧹 Removed the session-orientation hook entry (${target}).`);
+  }
+} catch (e) { /* never abort an uninstall for a convenience */ }
+
 CLIENTS.forEach(removeSkill);

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

@@ -100,6 +100,23 @@ not see them, because the wired hook legitimately lives in the git-ignored
 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.
 
+**Installing the package wires the hook machine-wide (F-042).** On Claude Code
+with Python, `npm i -g` (and every update) wires a SessionStart orient hook into
+the USER-level settings (`$CLAUDE_CONFIG_DIR/settings.json` when set, else
+`~/.claude/settings.json`), covering every project on the machine -- `orient` is
+fail-open, so projects without a docs root see nothing. The install itself is
+the consent: no question is asked. **Removing that hook entry is a standing
+opt-out**: a per-target marker (`<agentic-sdlc root>/orient-hook-wired`,
+default `~/.agentic-sdlc/`) remembers each settings file ever wired, and no
+install or update ever re-adds a removed hook; deleting the marker file is the
+re-enable gesture. `npm uninstall` removes the entries it can attribute to the
+removed skill (and only those), so no hook is left pointing at deleted files.
+Notes: the global command carries no `--hybrid` (a machine-global hook cannot
+know per-project mode -- on Hybrid projects only the devPNT pointer line is
+absent); a project wired per-project AND globally prints its orientation twice
+-- remove one of the two entries; `init` reports "covered by the machine-global
+hook" instead of wiring a project-level duplicate.
+
 **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:
 
@@ -152,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.8.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
 
 

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

@@ -1654,8 +1654,10 @@ def cmd_mark(root, paths):
 # 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.
+# ENFORCEMENT par.4 but never written by init. Pinned equal on both sides:
+# the entry-point names, and (F-042) the user-settings path derivation --
+# CLAUDE_CONFIG_DIR when set, else <home>/.claude -- empty-string env falsy
+# on both sides.
 ORIENT_HOOK_ENTRY_POINTS = ("sdlc_check.py", "mkt_check.py")
 ORIENT_HOOK_CONFIG_FILES = (".claude/settings.json",
                             ".claude/settings.local.json",
@@ -1665,38 +1667,63 @@ _ORIENT_HOOK_CMD_RE = re.compile(r" orient(\s|$)")
 _ORIENT_HOOK_TOKEN_RE = re.compile(r'"([^"]*)"|(\S+)')
 
 
+def _orient_entries_in(p):
+    """Yield the SessionStart commands invoking an orient entry point from ONE
+    client config file. 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)."""
+    try:
+        if not p.is_file() or p.stat().st_size > ORIENT_HOOK_CONFIG_CAP:
+            return
+        data = json.loads(p.read_text(encoding="utf-8-sig"))
+    except Exception:
+        return
+    if not isinstance(data, dict):
+        return
+    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):
+        return
+    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_user_settings_path():
+    """The machine-global settings file (F-042 wires it at install time).
+
+    Read at CALL time -- a DECLARED divergence from AGENTIC_SDLC_KB_ROOT's
+    import-time read: unittest imports this module once before any test runs,
+    so an import-time seam would be frozen before the matrix could set it.
+    AGENTIC_SDLC_USER_SETTINGS is the test-isolation seam (python-side only);
+    the production derivation mirrors lib.js: CLAUDE_CONFIG_DIR || ~/.claude."""
+    seam = os.environ.get("AGENTIC_SDLC_USER_SETTINGS")
+    if seam:
+        return Path(seam)
+    cfg = os.environ.get("CLAUDE_CONFIG_DIR")
+    return (Path(cfg) if cfg else Path.home() / ".claude") / "settings.json"
+
+
 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)."""
+    """Yield (command, at_user_level) across every known client config: the
+    three project-relative files, then the machine-global user settings --
+    the file the installer wires (F-042), without which a fixed machine's
+    projects would read as unwired forever."""
     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
+        for cmd in _orient_entries_in(Path(root) / rel):
+            yield cmd, False
+    for cmd in _orient_entries_in(_orient_user_settings_path()):
+        yield cmd, True
 
 
 def orient_hook_state(root):
@@ -1705,11 +1732,13 @@ def orient_hook_state(root):
     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."""
+    the client runs ALL SessionStart hooks -- project-level AND user-level
+    merge -- so one live entry at either level still orients the session
+    (any-resolves aggregation across levels). Relative tokens resolve against
+    the project root (the vendored-validator convention); a USER-level relative
+    token has no cwd to resolve against and is treated as cannot-tell."""
     matched = False
-    for cmd in _orient_hook_commands(root):
+    for cmd, at_user_level in _orient_hook_commands(root):
         matched = True
         token = None
         for m in _ORIENT_HOOK_TOKEN_RE.finditer(cmd):
@@ -1721,6 +1750,8 @@ def orient_hook_state(root):
             return "wired"
         tp = Path(token)
         if not tp.is_absolute():
+            if at_user_level:
+                return "wired"  # cannot tell: no cwd exists at user level
             tp = Path(root) / tp
         if tp.exists():
             return "wired"
@@ -1738,13 +1769,16 @@ def print_orient_hook_note(root):
     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")
+            print("[note] agent sessions start without automatic orientation on this "
+                  "machine (no session-orientation hook found at project or user level). "
+                  "Fix once: update or reinstall the skill npm package (on Claude Code "
+                  "with Python it wires the hook machine-wide), 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)")
+            print("[note] a session-orientation hook is configured but points at a "
+                  "validator that no longer exists, so sessions start unoriented. Fix: "
+                  "update or reinstall the skill npm package, or correct the command. "
+                  "Details: ENFORCEMENT.md par.4")
     except Exception:
         pass  # detection must never break check