@antoneeo/agentic-sdlc-skill 1.27.1 → 1.29.0

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.29.0] - 2026-08-28
+
+Spine delta parked for the next release of this lens (shipped first in kb; the
+spine stays byte-identical x3 in the repo while packages publish independently).
+
+### Added
+- **F-041: `check` notes an unwired or dead session-orientation hook** (one
+  informational `[note]` line -- never the exit code, never a `validate` warning,
+  so CI is unaffected). `init` wires the hook only at init time; projects
+  initialized before F-036 or bootstrapped without `init` were silently unwired.
+
+### Added (F-042, parked with the above)
+- Install/update wires the session-orientation hook machine-wide (Claude Code
+  with Python; user-level settings; removal is a standing per-target opt-out;
+  uninstall surgically removes what it wired). The check note is global-aware
+  and reworded in consequence-first user language.
+
+### Added (F-043 port, with the above)
+- **The revision sentence.** Updating an existing analysis (the L2 row and the ANALYSIS write trigger) is a REWRITE, not an
+  append: full re-read, body rewritten to current state -- never an appended
+  delta section. Ported from the kb lens's `## Revision` doctrine (kb 1.10.0),
+  born from a field post-mortem where delta-append revisions left stale
+  sentences standing as printed truth.
+
+## [1.28.0] - 2026-08-26
+
+F-038 — the gated rung: truthful log vocabulary and a mandated ask, no grant memory.
+
+### Fixed
+- **A review rung that exists behind a permission policy is no longer logged as
+  "unavailable".** The ladder knew two states (the client supports the rung, or not)
+  and hard-coded rung 3's reason as "no subagent facility on this client" — so a gated
+  facility produced false log rows, and the ladder's own prohibition ("rung 3 is
+  illegitimate wherever rung 1 or 2 exists") was unsatisfiable on a gated client: the
+  agent could not obey it without asking, and no rule said to ask.
+
+### Added
+- **The gated-rung stop.** At a due review gate (design; closure), when the best rung is
+  permission-gated (a standing policy — an interactive per-call prompt is NOT this) and
+  no ungated rung works (a working one-shot CLI pre-empts the stop; a gated rung 2 joins
+  the question instead), the gate stops and asks ONE question in the five-bullet blocking
+  form: the gated rung(s) vs the fallback, each higher rung's status, the quoted policy,
+  the cost (~130-175k subagent tokens per deep review, measured 2026-08) AND what
+  independence last bought, and what stays blocked. **No grant memory**: the answer holds
+  while the conversation does; an agent that cannot recall a grant asks again. Unattended
+  runs never emit the question — rung 2 is still owed a try, then rung 3 with its reason.
+  (Successor to a design CANCELLED at the review cap after grant memory failed three
+  ways; rulings r18/r19.)
+- **The reason words.** A below-rung-1 row says why the rung(s) above did not run:
+  `absent` (the client has no such facility — a claim about the client, never a policy),
+  `gated, declined`, `gated, unattended`, `gated, pre-empted` (nothing asked — an
+  ungated lower rung ran the review). A rung-1 row owes nothing. For rung 3 this
+  re-words an existing duty; for rung 2 it is a new one-word duty, disclosed and
+  accepted with the rest.
+
 ## [1.27.1 / kb 1.5.1 / mkt 0.5.1] - 2026-08-25
 
 ### Fixed

package/README.md

@@ -14,7 +14,7 @@
 - **Self-activating**: a SessionStart hook emits repo-sourced orientation; a deterministic self-eval battery guards the skill's own doctrine as the release gate.
 - **Standalone complete**: works fully with local `ai_docs/` without requiring devPNT.
 - **devPNT symbiosis**: when devPNT is available, Master Plan, Action Plan, M-VISION, and governed artifacts become the authoritative planning layer, with independent fresh-context reviews of technical artifacts and diffs.
-- **Independent review, twice**: the design is reviewed before it is implemented and the diff before the work is declared done — by somebody other than its author. Three rungs of independence (fresh-context subagent > one-shot run > a declared self-pass, legal only when the first two are unavailable), capped at 3 rounds, one log line per review, and a PASS is invalid on "found nothing" — it must state where each constraint is satisfied.
+- **Independent review, twice**: the design is reviewed before it is implemented and the diff before the work is declared done — by somebody other than its author. Three rungs of independence (fresh-context subagent > one-shot run > a declared self-pass, legal only when no higher rung is usable: absent, or permission-gated and declined — a gated rung is asked about, never silently skipped, and the log says which), capped at 3 rounds, one log line per review, and a PASS is invalid on "found nothing" — it must state where each constraint is satisfied.
 - **Question discipline**: a question to the user is legal only when the agent searched first and names the search with its result, and names the decision the answer unblocks. Otherwise it proceeds on a declared assumption — same evidence duty, batched, never a stream of "shall I proceed?".
 - **Installed support files**: Claude, Codex, Gemini, and Google Antigravity receive the full skill folder, including `templates.md`, `architect.md`, `guides.md`, `vision.md`, `tdd.md`, `debugging.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`.
 - **Mechanical checks**: optional validator for document structure, generated feature history, stale audit areas, and protected-path gates — `check`, `validate`, `index`, `stale`, `mark`, `gate`, `plan`, `orient`, `migrate`.
@@ -94,6 +94,10 @@ skills/agentic-sdlc-skill/
 
 The validator is **two files**: `sdlc_core.py` is the family's shared spine, `sdlc_check.py` is this lens's entry point. Copy both, or neither — the entry point is useless alone.
 
+Installing or updating the npm package wires the session-orientation hook
+machine-wide (user-level Claude Code settings; removal is a standing opt-out
+that no update overrides -- ENFORCEMENT.md par.4).
+
 ## The family: three lenses, one spine
 
 Same process, three fidelity disciplines — what the agent's assertions must be faithful to:

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.27.1",
+  "version": "1.29.0",
   "description": "Documentation-First SDLC protocol with triage, Vision governance and optional devPNT integration.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antoneeo/agentic-sdlc-skill",
-  "version": "1.27.1",
+  "version": "1.29.0",
   "description": "Documentation-First SDLC protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, installed support files 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();
 
@@ -159,16 +159,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) {
   {
@@ -283,8 +275,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.');
@@ -328,6 +333,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

@@ -383,6 +383,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);
@@ -409,7 +434,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 = {
@@ -422,6 +649,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/agentic-sdlc-skill/ENFORCEMENT.md

@@ -79,6 +79,37 @@ 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.
+
+**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:
 

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

@@ -1,6 +1,6 @@
 ---
 name: agentic-sdlc
-version: 1.27.1
+version: 1.29.0
 description: Documentation-First SDLC protocol with risk-proportional triage, Vision as a guide, a complete Standalone mode and optional symbiosis with devPNT. Use for features, significant bugs, refactors, audits and documented maintenance.
 author: Antonio Pinto (https://github.com/Antoneeo)
 copyright: (c) 2026 Antonio Pinto
@@ -44,7 +44,7 @@ Always classify the request before choosing the process. Declare the chosen leve
 | Level | Criteria | Required process |
 |---|---|---|
 | **L1 - Trivial** | About 10 lines in 1-2 files; no API, dependency or new-behavior change; typos or fixes restoring already-expected behavior | Implement. Run relevant existing tests. No new documents. |
-| **L2 - Small** | Clear root cause; at most 3 files; no new dependency or public API; low risk | Mini-analysis in the message: objective, impact, security, tests. Tests mandatory. No new document, except updating an existing analysis on the same topic, or the handoff (see Write Triggers). |
+| **L2 - Small** | Clear root cause; at most 3 files; no new dependency or public API; low risk | Mini-analysis in the message: objective, impact, security, tests. Tests mandatory. No new document, except updating an existing analysis on the same topic (full re-read, body rewritten to current state -- never an appended delta section), or the handoff (see Write Triggers). |
 | **L3 - Significant** | More than 3 files, APIs/contracts, new dependency, user-visible behavior, security-sensitive area, architectural change or non-obvious design | Full workflow: Vision Gate, analysis, plan, implementation, tests, closure. |
 | **Spike** | Time-boxed exploration to reduce uncertainty | Code not mergeable into main. Outcome in `ai_docs/solutions/SPIKE_[topic].md`. For production, reclassify as L2 or L3. |
 
@@ -72,7 +72,7 @@ Triage decides IF documentation is due; this table decides WHICH document each e
 
 | Document | Write trigger | Phase |
 |---|---|---|
-| `solutions/ANALYSIS_[feature].md` | Every L3, after elicitation and before any code. On topic match with an existing analysis, update that one instead of a new file. A capability the architect pass splits out as its own unit of change (`architect.md` §4) gets its own ANALYSIS, and the two documents name each other. | 3 |
+| `solutions/ANALYSIS_[feature].md` | Every L3, after elicitation and before any code. On topic match with an existing analysis, update that one instead of a new file -- a revision re-reads the WHOLE document and rewrites it to current state (history in the Diary), never an appended delta section. A capability the architect pass splits out as its own unit of change (`architect.md` §4) gets its own ANALYSIS, and the two documents name each other. | 3 |
 | `solutions/SPIKE_[topic].md` | Closing any Spike — including a failed one (a negative outcome is still an outcome). | — |
 | `vision/features/VISION_[feature].md` | Feature known multi-milestone at analysis time, OR the retroactive trigger: you are about to create the SECOND `ANALYSIS_*` on the same theme — extract the shared feature vision first, then let both analyses reference it. | 3 |
 | `audit/handoff.md` (workstream registry) | **Never by hand — generated by `sdlc_check.py index` from the `HANDOFF_*.md` sources**, and `validate` errors when the two disagree. Regenerate at every L3 closure and at session end; the `Date:` header is derived, so no writer touches it. It is an inventory for lookup, not a work board: no assignment, no due dates, no ordering, no holder. | 5 / session end |

package/skills/agentic-sdlc-skill/dispatch.md

@@ -1,96 +1,98 @@
-# Subagent Execution Discipline
-
-Opt-in orchestration for L3 work with an approved design: the orchestrator
-drives a `PLAN_[feature].md` through subagents instead of implementing every
-task in the same session. Default stays same-session; this is an escalation,
-never a requirement.
-
-## Trigger
-
-Only for L3 (an approved E-TDD in Hybrid, or an ANALYSIS Action Plan in
-Standalone). Never for L1/L2 — the plan/ledger machinery is overhead a small
-change does not need. The plan is always `derived-from` the accepted design:
-it is never independently authored, exactly like an E-TDD is never authored
-without an E-ISP.
-
-## The loop
-
-1. `sdlc_check.py plan validate PLAN_[feature].md` — zero-execution schema +
-   confinement + ledger cross-check. Non-zero exit = **no dispatch**. This is
-   the hard gate: "no valid plan, no dispatch."
-2. For each task, in plan order:
-   - Read the task's status from the sidecar ledger
-     (`PLAN_[feature].ledger.json`). `status: done` (exact sentinel) → skip,
-     never re-dispatch. Anything else (pending, failed, missing, or a
-     corrupt-but-parseable entry) → treat as pending and dispatch.
-   - `sdlc_check.py plan brief PLAN_[feature].md --task <id>` — prints the
-     task block, the `produces` of prior-order tasks (interfaces), and
-     `guides` pointers (paths, never pasted content) to stdout.
-   - Spawn the subagent with that brief as its entire context window.
-   - Run `task.verify` out of band (the orchestrator executes it — the
-     validator only ever prints it, never runs it) plus the one-shot review
-     below.
-   - Write `{status, verify_result, timestamp}` back to the ledger. The
-     validator never writes the ledger — single-writer, orchestrator-owned.
-
-**Guide consumption under dispatch.** Selecting each task's `guides` field IS the
-consult trigger (`guides.md` §0) applied at plan-authoring time: the orchestrator
-runs the router lookup (project router `ai_docs/reference/INDEX.md` + the agent-KB
-router) when populating `guides`. A dispatched context-free subagent does **NOT**
-run its own router consult — it reads the guide pointers handed to it in the
-brief. The router verdict (Rule Zero) is therefore declared ONCE, by the
-orchestrator, when it authors the plan; a dispatched subagent does not declare
-one. (Proactive guide-creation stays at closure — the same broad final pass
-below — so it needs no separate dispatch hook.)
-
-## Model tiers (client-relative, no provider names)
-
-- Default dispatch: **economy** implementer tier.
-- After **two** consecutive `verify_result: fail` on the same task: escalate
-  to the **deep** tier for the retry (ADR 2026-07-02). Do not escalate on the
-  first failure — a single fail is often a brief or environment issue, not a
-  capability gap.
-
-## Review slots — one-shot, not iterative
-
-Exactly three review touches per task, never a loop:
-
-1. Inline self-review by the implementer subagent before it reports done
-   (the standard critical-review pass, not a separate call).
-2. One reviewer pass per task (Hybrid: reuse the devPNT code-review gate;
-   Standalone: the `review.md` discipline).
-3. One broad final pass over the whole plan at closure, after all tasks are
-   DONE — catches cross-task drift a per-task review cannot see.
-
-If a review FAILs, fix and re-run `verify` — that is a normal loop iteration
-via the ledger's fail path, not an extra review slot.
-
-**The scoped re-review is a round INSIDE slot 2 or 3, never a fourth slot.**
-`review.md` §Receiving requires every review-driven correction to be
-re-reviewed against the correction alone — that round belongs to the slot whose
-findings caused it, and is bounded by the same cap of 3 rounds. "Never a loop"
-bounds the SLOTS (no unbounded re-reviewing of a task), not the rounds inside
-one slot: a fix nobody looked at is the defect the round exists to catch. Slot 1
-is the implementer's own pass, not an independent review, so its fixes carry no
-re-review round. The ledger records the round on the task's fail path as usual.
-
-## Ledger protocol summary
-
-Read → skip-if-done → dispatch-if-pending → write. The ledger is the only
-memory the loop needs across sessions or context compaction: a resumed
-orchestrator re-reads it and picks up exactly where it left off, never
-re-running a DONE task.
-
-## Degradation
-
-No subagent-spawning tool available → the orchestrator runs each task in the
-same session, against the same plan and ledger, with the same one-shot review
-slots. No capability is lost, only the parallelism/isolation subagents would
-have added.
-
-## Hybrid note
-
-The plan's `derived-from` points at the accepted E-TDD document key. Per-task
-review reuses the devPNT independent reviewers (§4.6 code review gate) rather
-than restating review doctrine — see `review.md` for the single definition
-both modes share.
+# Subagent Execution Discipline
+
+Opt-in orchestration for L3 work with an approved design: the orchestrator
+drives a `PLAN_[feature].md` through subagents instead of implementing every
+task in the same session. Default stays same-session; this is an escalation,
+never a requirement.
+
+## Trigger
+
+Only for L3 (an approved E-TDD in Hybrid, or an ANALYSIS Action Plan in
+Standalone). Never for L1/L2 — the plan/ledger machinery is overhead a small
+change does not need. The plan is always `derived-from` the accepted design:
+it is never independently authored, exactly like an E-TDD is never authored
+without an E-ISP.
+
+## The loop
+
+1. `sdlc_check.py plan validate PLAN_[feature].md` — zero-execution schema +
+   confinement + ledger cross-check. Non-zero exit = **no dispatch**. This is
+   the hard gate: "no valid plan, no dispatch."
+2. For each task, in plan order:
+   - Read the task's status from the sidecar ledger
+     (`PLAN_[feature].ledger.json`). `status: done` (exact sentinel) → skip,
+     never re-dispatch. Anything else (pending, failed, missing, or a
+     corrupt-but-parseable entry) → treat as pending and dispatch.
+   - `sdlc_check.py plan brief PLAN_[feature].md --task <id>` — prints the
+     task block, the `produces` of prior-order tasks (interfaces), and
+     `guides` pointers (paths, never pasted content) to stdout.
+   - Spawn the subagent with that brief as its entire context window.
+   - Run `task.verify` out of band (the orchestrator executes it — the
+     validator only ever prints it, never runs it) plus the one-shot review
+     below.
+   - Write `{status, verify_result, timestamp}` back to the ledger. The
+     validator never writes the ledger — single-writer, orchestrator-owned.
+
+**Guide consumption under dispatch.** Selecting each task's `guides` field IS the
+consult trigger (`guides.md` §0) applied at plan-authoring time: the orchestrator
+runs the router lookup (project router `ai_docs/reference/INDEX.md` + the agent-KB
+router) when populating `guides`. A dispatched context-free subagent does **NOT**
+run its own router consult — it reads the guide pointers handed to it in the
+brief. The router verdict (Rule Zero) is therefore declared ONCE, by the
+orchestrator, when it authors the plan; a dispatched subagent does not declare
+one. (Proactive guide-creation stays at closure — the same broad final pass
+below — so it needs no separate dispatch hook.)
+
+## Model tiers (client-relative, no provider names)
+
+- Default dispatch: **economy** implementer tier.
+- After **two** consecutive `verify_result: fail` on the same task: escalate
+  to the **deep** tier for the retry (ADR 2026-07-02). Do not escalate on the
+  first failure — a single fail is often a brief or environment issue, not a
+  capability gap.
+
+## Review slots — one-shot, not iterative
+
+Exactly three review touches per task, never a loop:
+
+1. Inline self-review by the implementer subagent before it reports done
+   (the standard critical-review pass, not a separate call).
+2. One reviewer pass per task (Hybrid: reuse the devPNT code-review gate;
+   Standalone: the `review.md` discipline).
+3. One broad final pass over the whole plan at closure, after all tasks are
+   DONE — catches cross-task drift a per-task review cannot see.
+
+If a review FAILs, fix and re-run `verify` — that is a normal loop iteration
+via the ledger's fail path, not an extra review slot.
+
+**The scoped re-review is a round INSIDE slot 2 or 3, never a fourth slot.**
+`review.md` §Receiving requires every review-driven correction to be
+re-reviewed against the correction alone — that round belongs to the slot whose
+findings caused it, and is bounded by the same cap of 3 rounds. "Never a loop"
+bounds the SLOTS (no unbounded re-reviewing of a task), not the rounds inside
+one slot: a fix nobody looked at is the defect the round exists to catch. Slot 1
+is the implementer's own pass, not an independent review, so its fixes carry no
+re-review round. The ledger records the round on the task's fail path as usual.
+
+## Ledger protocol summary
+
+Read → skip-if-done → dispatch-if-pending → write. The ledger is the only
+memory the loop needs across sessions or context compaction: a resumed
+orchestrator re-reads it and picks up exactly where it left off, never
+re-running a DONE task.
+
+## Degradation
+
+No subagent-spawning tool available — absent, or permission-gated with no grant
+in context (`review.md`'s gated-rung stop owns the asking; task dispatch never
+asks; the broad final pass IS `review.md` moment 2 and asks there) → the
+orchestrator runs each task in the same session, against the same plan and ledger,
+with the same one-shot review slots. No capability is lost, only the parallelism/isolation subagents would
+have added.
+
+## Hybrid note
+
+The plan's `derived-from` points at the accepted E-TDD document key. Per-task
+review reuses the devPNT independent reviewers (§4.6 code review gate) rather
+than restating review doctrine — see `review.md` for the single definition
+both modes share.

package/skills/agentic-sdlc-skill/review.md

@@ -12,7 +12,7 @@ Two moments, and they review different things:
 |---|---|---|---|
 | **1. Design review** | End of Phase 3 — **before any implementation** | the ANALYSIS (Standalone) / the `E-ISP`+`E-TDD` (Hybrid) | L3 |
 | **1b. Late arrival** | Work that became L3 *after* code existed — an L1/L2 reclassified mid-flight, or a design increment on a feature already implemented — runs moment 1 **now**, before any further implementation, logged `design (late)` | same | L3 |
-| **2. Closure review** | Phase 5, before DONE | the actual diff, against that approved design | L2 / L3 — the L2 row is optional |
+| **2. Closure review** | Phase 5, before DONE | the actual diff, against that approved design | L2 / L3 — the L2 closure review is optional; every review that runs logs its row |
 
 **Why the design review is its own moment, and not a nicety.** The closure review
 can only tell you the code matches the design; it cannot tell you the design was
@@ -30,17 +30,56 @@ blind to it, which is why independence, not effort, is what this gate buys.
    a SELF-CONTAINED prompt — the reviewer session has no other context, which is
    exactly what makes it independent.
 3. **A declared self-pass** — a separate, explicitly adversarial pass by you,
-   against the same checklist. **Rung 3 is illegitimate wherever rung 1 or 2
-   exists**: on a client with a subagent facility or a one-shot CLI, descending to
-   it is choosing zero independence, which is the one thing this gate buys. When
-   you do use it, the log row must carry *why* — `self-pass (declared; no subagent
-   facility on this client)` — not merely that you did. A rung named without its
+   against the same checklist. **Rung 3 is illegitimate wherever a higher rung
+   is usable**: on a client with a working subagent facility or one-shot CLI,
+   descending to it is choosing zero independence, which is the one thing this
+   gate buys. A gated rung the user DECLINED is not usable — see *The gated
+   rung* below; a gated rung nobody asked about is not declined (unattended is
+   its own case below). When
+   you do use it, the log row must carry *why*, in the reason words below —
+   `self-pass (declared; absent — the client has no such facility)` — not merely
+   that you did. A rung named without its
    reason is indistinguishable from a rung chosen for convenience.
 
 Rung 3 stays in the ladder deliberately: it is what keeps the methodology
 completable with no network, no account and no subagent facility. It is a floor,
 never a default.
 
+**The gated rung — present is not absent (F-038).** A rung that exists behind a
+standing policy or instruction forbidding its use absent a user request is
+**permission-gated**, not unavailable. An interactive per-call approval prompt is
+NOT this: answering the prompt IS the grant. With an ungated rung usable — rung 1
+free, or a one-shot CLI that works (try it, or show it failed) — the prohibition
+above is already satisfiable and no stop fires (the row still carries
+`gated, pre-empted` when a gated rung sat above the one that ran); a gated
+rung 2 is not "usable" for this clause, it joins the question instead. When the best rung is gated and no
+ungated rung works, the gate STOPS and asks: descending to rung 3 on silence is
+illegal while a user is reachable. The stop is doctrine-mandated (legal by mandate,
+`elicitation.md` §Blocking is reserved) and carries that file's five-bullet
+blocking form — its closed-list exemption covers this file's round-cap hand-over
+only, not this stop. The question offers the gated rung(s) against the fallback, with what each
+buys; states each higher rung's status (tried / unusable / gated) with the
+standing instruction quoted and "no grant visible in my current context"; says
+why no assumption survives (assuming either way writes a false log row); says
+why it is the USER'S call — their tokens (~130-175k per deep review, measured
+2026-08) against a benefit only they can price, stated with what independence
+last bought; and names what stays blocked — which reviewer runs, nothing else.
+**No grant memory exists**: the answer holds while the conversation does, and an
+agent that cannot recall a grant asks again — one question per gate per intact
+context; re-asking is a smaller defect than a false row. Unattended
+(`elicitation.md`'s Unattended path — the user is not reachable), no question is
+emitted: rung 2 is still owed a try, then rung 3 runs with its reason logged.
+
+**The reason words.** A below-rung-1 row carries why the rung(s) above did not
+run; a rung-1 row owes nothing. `absent` — the client has no such facility (a
+claim about the client, never about a policy); `gated, declined` — usable only
+with the user's assent at this gate, and the user withheld it (a standing policy
+answered no, or a per-call prompt denied); `gated, unattended` — a standing policy
+gates it and no user is reachable to ask; `gated, pre-empted` — gated, nothing
+asked: an ungated lower rung ran the review instead. `gated` always appears with
+its outcome. The trigger term "permission-gated" scopes the STOP; the row word
+`gated` additionally covers a denied per-call prompt, which never triggers one.
+
 Use a different model from the author's where the client allows it.
 
 **Rounds are capped at 3.** FAIL → revise → re-review. If findings still stand

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

@@ -1646,6 +1646,143 @@ 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. 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",
+                            ".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_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 (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:
+        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):
+    """'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 -- 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, at_user_level 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():
+            if at_user_level:
+                return "wired"  # cannot tell: no cwd exists at user level
+            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] 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 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
+
+
 def cmd_check(root, strict=False, hybrid=False):
     print("===== validate =====")
     rc_v = cmd_validate(root, strict=strict, hybrid=hybrid)
@@ -1653,6 +1790,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
 
 

package/skills/agentic-sdlc-skill/templates.md

@@ -508,7 +508,7 @@ adds values to the existing columns rather than a second table.
 | date | doc_key | tier | reviewer | findings_raised | findings_real | verdict | revise_rounds |
 |---|---|---|---|---|---|---|---|
 | 2026-06-11 | ANALYSIS_login_sso.md | design | subagent (opus, fresh ctx) | 4 | 3 | FAIL → PASS | 2 |
-| 2026-06-12 | diff feature/sso-login | closure | self-pass (declared; no subagent facility) | 2 | 2 | PASS with findings → corrections re-reviewed, PASS | 2 |
+| 2026-06-12 | diff feature/sso-login | closure | self-pass (declared; absent) | 2 | 2 | PASS with findings → corrections re-reviewed, PASS | 2 |
 
 ## Notes
 <!-- One short paragraph per review that found something worth remembering: what
@@ -523,9 +523,17 @@ and `closure` (Standalone); `deep`, `light`, `code`, `guide`, `vision` (devPNT g
 and the Vision blind check). The validator reads this column by its header name, so
 extra or reordered columns are fine — but the header must say `tier`. `reviewer`
 records the realization actually used — fresh subagent, one-shot client run, or a
-**declared** self-pass. Writing `self-pass` where independence was unavailable is
-honest; writing nothing, or implying independence you did not have, is the failure
-this column exists to prevent. `findings_real` is how many raised findings survived
+**declared** self-pass — and, for any rung below rung 1, WHY the rung(s) above did
+not run, in the ladder's reason words (`review.md`): `absent` — the client has no
+such facility (a claim about the client, never about a policy); `gated, declined` —
+usable only with the user's assent at this gate, withheld (a standing policy
+answered no, or a per-call prompt denied); `gated, unattended` — a standing policy
+gates it, no user reachable; `gated, pre-empted` — gated, nothing asked, an ungated
+lower rung ran the review. A rung-1 row owes nothing. `gated` here is the ROW
+word — it also covers a denied per-call prompt, which never triggers `review.md`'s
+stop. Writing `self-pass` with its
+true reason is honest; writing nothing, or implying independence you did not have,
+is the failure this column exists to prevent. `findings_real` is how many raised findings survived
 triage: over time it is the only evidence of whether the gate earns its cost.
 `revise_rounds` counts **review rounds**, not fix cycles: the first review is round 1
 and every scoped re-review adds one. A review that produced findings which were then